Updated Jaguar Documentation V10

[+Stephen Moss]

Hello everyone,

after many years my project to update the key components of the Jaguar documentation is finally here, given version number 10.

No doubt you are keen to know what has changed so as an overview...

 

Index:

Indicates which documents have been updated and where practical indicates which sections of them have been added/had significant changes (except for the SoftRef).

The document names are all links, so clicking on them will open the relevant document, also all updated documents (not just the SoftRef) now have a table of contents which are also links taking you to the relevant section of the document, so no more scrolling to find it. 

IMPORTANT!  I know you want to get to the good (or possibly bad) stuff but there is important information regarding the text colour coding used in the revised documents on page 2 that you should familiarise yourself with first. 

 

Getting Started:

No real changes but added information about newer development hardware/software, i.e. SkunkBoard & JagStudio, old news for many of you but useful for those who are not up to date with what's available or taking thier first look at Jaguar programming.

 

Qsound:

Other than the TOC, no real changes apart from the removal of contact data for the company that developed it at their request.

 

SoftRef:

One or two small changes, big changes are...

1) The information from the HWBugs document has been moved into the (hopefully) relevant sections of the SoftRef, if there is a problem with something you want to know about it there and then not have to remember to scurry off to another document to check for issues. 

Although this represents a big change to the document as it is all relocated original text, not new or significantly changed information it is still Black text, but is instead highlight by a Caution symbol.

2) The outdated (struck through) data has been removed.

 

TechOver:

As I recall No real changes, but added info on SkunkBoard.

 

TechRef:

Lots of additions here, i.e. cartridge port & power specification, plus links to Schematics and some other bits.

Big changes regarding some aspects of identification and reading controllers, specifically advanced controllers. The way Atari did it made sense back then when Microcontrollers were slow and low pin count but meant Advanced controllers would not work with the Team-Tap, these revisions would make those that plug into the standard Jaguar controller port Team-Tap friendly.

 

The Other Documents folder contains some other Jaguar related documents including a partial CD unit test document, and the original 1995 Atari versions of the updated documents for reference.

 

You can find the updated documents in my Jaguar dropbox folder here (Jaguar Documents V10.zip) along with what is probably nothing new to most people here...

Jag3DStudio - 3DSCONV - Atari N3D converter (convert objects to J3D & N3D) and 3DSPOV (Raytracer).

jagdev_102 - BelBoz PC dev kit

N3D render - render for N3D Objects

Polytool - Can't remember excatly, but more 3D stuff I think

PC_Devtools - Some Original Atari development files & 

SkunkBoard Standard (User) & Full (Design) releases.

 

UPDATE 23/12/2021:

I updated the Zip file today. There are no real changes to the contents as far as those who have already downloaded it are concerneced excpt the the fact that I forgot to add bookmarks in addition the the TOC for easy navigation within teh updated documents - there is always somehting you forget.

[+Stephen]

Thanks for sharing - can't wait to check it out once I get home.

[Cyprian]

@Stephen Moss  great. thanks

[Atariman]

Thanks for sharing all of this great stuff! Will definitely be digging through it over the holidays. 

[Zerosquare]

At the moment I only took a quick glance at it. Random comments:

 

- moving the bug warnings right next to the original description is a great idea ?

 

- I don't understand the reason for some of the things being highlighted in brown. For example, the serial port documentation shouldn't be deleted: the sending part works fine, the receiving part can be made to work (with tricks). It would be better to explain instead what's broken.

 

- an additional color is needed to distinguish between "this is how existing stuff works" and "these are good practices for future developments". For example, the vast majority of rotary controllers on the market don't actually set the ID bits as documented, so you can't rely solely on them if you're writing a game. Same thing with the advanced controllers: AFAIK none have been released publicly, and there are no guarantee existing games' behaviors is compatible with the description

Edited December 22, 2021 by Zerosquare

[+Stephen Moss]

On 12/22/2021 at 12:45 AM, Zerosquare said:

- I don't understand the reason for some of the things being highlighted in brown. For example, the serial port documentation shouldn't be deleted: the sending part works fine, the receiving part can be made to work (with tricks). It would be better to explain instead what's broken.

It will not necessarly be deleted, it is only indicating that it may be deleted/changed in future updates as there is some doubt as to the current relevance/correcness/validity of the information. 

I am happy to make changes to provide more datails on what is broken and include any solution to make it work if I have that information, that was the point of converting them into editable documents, so that errors can subsequently be corrected resulting in the documents being as complete and correct as possible.

 

On 12/22/2021 at 12:45 AM, Zerosquare said:

- an additional color is needed to distinguish between "this is how existing stuff works" and "these are good practices for future developments". For example, the vast majority of rotary controllers on the market don't actually set the ID bits as documented, so you can't rely solely on them if you're writing a game.

Colours:

I will think about the additional colour but essentially the original (Black) text is the "this is how existing stuff works" and the purple "these are good practices for future developments".

 

Rotary Contollers:

I am aware that the majory of Rotary controllers do not correctly identify themselves, an unfortunate side affect of people who don't follow the documentation hacking stuff together. The original TechRef clearly indicates the identification bits are different to a standard controller, thus the apropriate alteration should have been included. That is why I added information on how to do that yourself in the TechRef, it is reasonably easy to do for anyone who can solder.

 

I know Tempest 2000 uses the rotary and does not check for its presence, for whatever reason. 

I cannot off the top of my head think of any other software that uses the rotary, but as far as I can tell (I did test with some games) the addition of the identifiction diode does not impead the function of any software that does not check for it and instead requires a standard controller to be used first to select rotary usage, well no more than using a Rotary controller on a non Rotary game would anyway.

 

There is really only two roads do go down in this regards...

1) Software developers can choose to only incorporate Rotary usage for only those Rotary controller that correctly identify themselves into new software, (automatically switching between Rotary and non Rotary contoller reads where both controller types are supported), requiring all rotary controllers to subsequently have the identification diode retrofitted, which would be the better option going forward as it creates standardisation and is in line with the specification of both the updated and 1995 TechRef, or

2) Software developers can incorporate both automatic and manual rotary selection, so that correctly identifying Rotary controllers will operate seamlessly without the users having to select them first, while also having the rather clunky (and amature looking in my view) use of a standard controller to select rotary control to allow use of those rotary controllers that do not correctly identify themselves and thereby potentially having to unplug and plug in controllers with the power on - generally not a good idea.

 

On 12/22/2021 at 12:45 AM, Zerosquare said:

Same thing with the advanced controllers: AFAIK none have been released publicly, and there are no guarantee existing games' behaviors is compatible with the description

I also do not know of any publicly released advanced contollers either, which is why there is logic to defining any new standard now with a common interface so there is not a repeat of the Rotary controller situation that would then require software writers to then decide which of potentially several different advanced controllers they are going to support becase they all have been developed Ad-Hoc, to no standard and thus have wildly differnt methods of communication with the Jaguar that would otherwise likely require either all or none to be supported.

 

As there are no publicly released Advanced controllers there is presumable also no publicly published software that supports them either, I am discounting BattleSphere as it used outdated data relying on the Jaguar having internally fitted ADC's, which were dropped in favour of BankSwitching. 

As Advanced (bank switching) controllers would not work with existing games that use Standard, Pro & Rotary controllers and so should not be used with them anyway, I don't believe that there being "no guarantee existing games' behaviors is compatible with the description" is really an issue as the one or two prototypes that might have not been released. 

 

Hopefully, there is some logic to what I have said, it seems logical to me. 

[+CyranoJ]

10 hours ago, Stephen Moss said:

Rotary Contollers:

I am aware that the majory of Rotary controllers do not correctly identify themselves, an unfortunate side affect of people who don't follow the documentation hacking stuff together. The original TechRef clearly indicates the identification bits are different to a standard controller, thus the apropriate alteration should have been included. That is why I added information on how to do that yourself in the TechRef, it is reasonably easy to do for anyone who can solder.

 

You can detect a rotary controller by scanning for LEFT + RIGHT pressed *at the same time*  -  then the user only has to spin the dial.

[SlidellMan]

As far as colors are concerned, I suggest using something that is easy-to-read, yet colorblind-friendly.

[+Stephen Moss]

On 12/24/2021 at 12:09 AM, SlidellMan said:

As far as colors are concerned, I suggest using something that is easy-to-read, yet colorblind-friendly.

I would think that is not simple, as colourblind does not necessarily mean that everything is seen in a shade of grey, as what people see depends on which of the Red, Blue or Green colour seceptors are affected. Consequently, a colour scheme that works well for someone who sees colours as mostly black, blue & yellows/olives may not work for someone who sees colours as mostly black, blues & pinks.  

[+Stephen]

Could always use this test pattern of random noise as a captcha:

[0078265317]

1 hour ago, Stephen said:

Could always use this test pattern of random noise as a captcha:

I can't even read what that says.

[+Stephen]

3 hours ago, 0078265317 said:

I can't even read what that says.

Nor can I.  Probably for the best - my wife saw it and started laughing.

[0078265317]

2 hours ago, Stephen said:

Nor can I.  Probably for the best - my wife saw it and started laughing.

F****

 

color

blind

 

The second word is unreadable.

[+Stephen]

1 hour ago, 0078265317 said:

F****

 

color

blind

 

The second word is unreadable.

I'm told it's "the".  I am severely colourblind - I can't read any of those damn tests above - I just call them random noise blots.

[+LS650]

It is indeed 'THE'.  

[+Stephen]

My wife was sweet - when we were dating, she found out how bad I was regarding colour vision.  She took that photo, and manually coloured in every dot that spelled the message.  I really thought it was just a joke image - did not know why it was getting so many laughs.

[+CyranoJ]

I can't see them either, so all I do for these is shift the hue in PaintShopPro.

 

 

My take?

 

*MY* green is beautiful. All you colour-normal people will never see it like I do, and I cannot explain it to you in any terms I could vocalize or you could comprehend 

[+Stephen Moss]

On 12/23/2021 at 10:39 PM, CyranoJ said:

 

You can detect a rotary controller by scanning for LEFT + RIGHT pressed *at the same time*  -  then the user only has to spin the dial.

That is a possability but I don't think it is a very good one as...

1) The specifications are there to be followed to ensure hardware & software compatability and so should be followed regardless, otherwise chaos ensews as people just do their own thing and you end up with a bunch of hardware and software incompatiablities.

 

2) It is really a Botch on a Botch, on a Botch, which can result in instabilty and inconsistancy in the system and may encourage some to think they don't need to follow the specifications as a work around will eventually be found to whatever problems they subsequently cause, which is the opposite of what is needed.

Also, there is no reason for it as the original cause of the problem is easily solvable. Most people could probably find someone to do it either via 6 degrees of separation or posting to a social media platform a request for an local individual/community repair hub/electronic group that could do it, it should only take 10 mintes and the diode costs pennies.

 

3) It reiles on the user remebering to perform an action which they should not and normally would not have to do on the Jaguar (or any other console), the detection of the controller should be entirely transparent to the user, that is why Atari, Sony, Microsoft and others will have created a means of controller detection where multiple controller types exist.

Additionally, there is the problem of how long to wait to see if that input pattern appears, do you read the controller once & hope, 4 times, as many times a possible in 10 seconds and hope the user has become so tired of waiting by then they have started desparately working the controller in the hope of making something happen? All seems a bit amature hour to me, may as well put a message on screen stating "Please mash all your controlls now and hope for the best as we can't be bothered to do things correctly."

[+CyranoJ]

15 minutes ago, Stephen Moss said:

That is a possability but I don't think it is a very good one as...

1) The specifications are there to be followed to ensure hardware & software compatability and so should be followed regardless, otherwise chaos ensews as people just do their own thing and you end up with a bunch of hardware and software incompatiablities.

 

2) It is really a Botch on a Botch, on a Botch, which can result in instabilty and inconsistancy in the system and may encourage some to think they don't need to follow the specifications as a work around will eventually be found to whatever problems they subsequently cause, which is the opposite of what is needed.

Also, there is no reason for it as the original cause of the problem is easily solvable. Most people could probably find someone to do it either via 6 degrees of separation or posting to a social media platform a request for an local individual/community repair hub/electronic group that could do it, it should only take 10 mintes and the diode costs pennies.

 

3) It reiles on the user remebering to perform an action which they should not and normally would not have to do on the Jaguar (or any other console), the detection of the controller should be entirely transparent to the user, that is why Atari, Sony, Microsoft and others will have created a means of controller detection where multiple controller types exist.

Additionally, there is the problem of how long to wait to see if that input pattern appears, do you read the controller once & hope, 4 times, as many times a possible in 10 seconds and hope the user has become so tired of waiting by then they have started desparately working the controller in the hope of making something happen? All seems a bit amature hour to me, may as well put a message on screen stating "Please mash all your controlls now and hope for the best as we can't be bothered to do things correctly."

1.  Nobody follows those.  We have 2k eeproms now and a bunch of other things. It's not like the Jaguar has an operating system. We're all 'on the metal' here. Scanning for something that may or may not even exist is just plain stupid.  If I followed the h/w specs I couldn't have written Gravitic Mines or Last Strike, and probably 90% of the ST conversions wouldn't run because OMG ST games mostly run from $400 and we *simply cannot* go below $4000, can we?

2. No, it actually works.  Why take a controller apart and start hacking away with a soldering gun when you can detect easily and quicky this way? Not to mention the people who *wont* do that who would get 'locked out' of said software.

3. If it says on the screen "SPIN ROTARY TO AUTO-DETECT" there's no reason to give a damn about what Atari, Sony or Microsoft say.  How long to wait?  LESS THAT ONE FRAME is enough. You are only scanning for left+right simultaneously. Also, its not like rotaries are any sort of "standard"  - 16, 32, 64, 1149, 329732, 23145534 clicks per circle?

4. This method is used in Downfall, Rebooteroids, Kobayashi Maru, and several other games... and I have yet to see anyone write as much as you did in (3) moaning about them

 

PS - the updated docco is awesome, thank you for doing that, it was very much required.  However, I completely disagree with you on this point.

 

[Zerosquare]

I agree with CJ -- while the other modifications you made to the docs are great, that particular ship has sailed long ago. Rotary controllers have been a thing on the Jaguar for 20 years now. Very few of them, if any, include the extra diodes. And every rotary-compatible game released still works fine.

 

Meanwhile, a game whose rotary mode requires the extra diodes (because the programmer followed your modified doc to the letter) will not work for 99% of the players. And their reaction won't be "I need to get my rotary controller modified", but "Why doesn't this game work? All my other rotary-compatible games do".

 

This is why it's important to document the theory ("according to Atari, rotary controllers were supposed to behave this way") and the reality ("as of 2022, here's how almost every rotary controller actually behaves").

[+CyranoJ]

Also, if you go by 'the standard way to do this is....'

Atari... 0 releases officially supporing a rotary

Homebrew.. Many

 

I think you see where this is headed.

[joeyaage]

Rumblings of excitement about the new docs. I will have a look...

[+Stephen Moss]

On 12/31/2021 at 10:28 AM, CyranoJ said:

3. If it says on the screen "SPIN ROTARY TO AUTO-DETECT" there's no reason to give a damn about what Atari, Sony or Microsoft say.  How long to wait?  LESS THAT ONE FRAME is enough. You are only scanning for left+right simultaneously. Also, its not like rotaries are any sort of "standard"  - 16, 32, 64, 1149, 329732, 23145534 clicks per circle?

I will consider making a change in regards to your and Zerosquares comments.

 

If you have time perhaps you could PM me something with a little more detail and I will take a look.

[+cubanismo]

I was digging through these for some stuff last night, and I can't stress enough how useful it is to finally be able to search the text of the software reference manual. The inline errata is also a big improvement. Thank you for all the time you put in here. It's already saved me a large number of minutes after just one session working with them.

 

This morning I noticed a tiny issue in the the software ref where I'd left it open. In the diagrams depicting the bit layouts of the various object processor object types (page 25), it looks like a grammar check green underline got baked into the image somehow:

 

"Third phrase only"

 

is underlined with a green squiggly line, and it appears to be part of an embedded image when I try to select it in the PDF viewer. Just something to consider if you ever need to re-roll these for some reason.

[+Stephen Moss]

If I remember I will take a look at it the next time I make any changes.

What gets imbedded into the PDF is largely down to conversion software, if it is a grammar highlight then ideally it should not include that and I can only assume it is interpreting it as an image. If so then hopefully tuning off grammar & spell checking before saving to PDF will resolve it.