AMOS BASIC tokenized file

AMOS BASIC is a family of BASIC dialects for the Amiga computer. They were written by François Lionet, who also wrote AMOS"s predecessor, STOS BASIC for the Atari ST.

There are several versions of AMOS published: AMOS The Creator, Easy AMOS and AMOS Professional.

AMOS has its own integrated development environment, and it uses its own custom file formats for everything, from source code to graphics and sound.

Overview
AMOS is an interpreted BASIC dialect where code is edited and run in an integrated development environment. Every time the programmer finishes editing a line of code, it is immediately parsed into tokens. For example, typing  and pressing the return key will change the line into.

Before a program can run, it will be tested to ensure it is free of syntax errors. Source code can be saved even if it is untested or fails testing, but AMOS includes a tested flag in the saved file. This is used by external software, for example the AMOS Compiler will refuse to compile an untested source code file.

Extensions
AMOS tokens are split between instructions in the core language and instructions in extensions.

Extensions are external files, written in 68000 assembler, which begin with a token table listing all the instructions they add to the language.

Each extension is intended to be loaded into a specific slot. AMOS has 25 slots for extensions. The configuration of extensions and their slots are saved in AMOS's global config file.

To load other people's source code, AMOS needs to be configured with the same versions of the same extensions that they used, in the same slots.

Banks
In order to work with multimedia such as pictures and music, AMOS has the concept of a memory bank. An AMOS program can have up to 15 memory banks. For example, you can load several pieces of music into different memory banks, and then identify which one you want to play by a number:  will play music in bank 5. Or you could load a packed picture into bank 4 and say, which will unpack the picture onto screen 0.

While you can load anything into any bank, some instructions can only take their data from specific bank numbers. Bank 1 is used for Sprites, which are controlled with instructions beginning  or. Bank 2 is for Icons, which are controlled with instructions beginning. Bank 3 is used for music in AMOS's native music format.

If memory banks are in use while saving source code, the contents of the banks are included in the saved source code. This makes it easy to bundle code with the data it works on. The exception to this rule is banks created using the  instruction.

AMOS source code
All multi-byte integer values are in big-endian (Motorola) format.

AMOS source code is stored in a file with the extension .AMOS. It has the following structure:

Tokenised BASIC code
Tokenised BASIC code is a sequence of tokenised lines. Each tokenised line has the following format:

Some tokens have special size rules, but most are exactly 2 bytes in size.

Each token starts with a signed 16-bit number. Token values between 0x0000 and 0x004E have special printing and size rules, all other tokens are a signed offset into AMOS's internal token table. The instruction name in the internal token table is what should be printed.

Encrypted procedures
If you should find a procedure (0x0376) token with the "is encrypted" bit set, run this C function on the code and it will decrypt the contents of the procedure.

/* fetches a 4-byte integer in big-endian format */ /* fetches a 2-byte integer in big-endian format */ void decrypt_procedure(unsigned char *src) { unsigned char *line, *next, *endline; unsigned int key, key2, key3, size; /* ensure src is a pointer to a line with the PROCEDURE token on it */ if (EndGetM16(&src[2]) != 0x0376) return; /* do not operate on compiled procedures */ if (src[10] & 0x10) return; /* size + 8 + 6 is the start of the line after END PROC */ size = EndGetM32(&src[4]); endline = &src[size + 8 + 6]; line = next = &src[src[0] * 2]; /* initialise encryption keys */ key = (size << 8) | src[11]; key2 = 1; key3 = EndGetM16(&src[8]); while (line < endline) { line = next; next = &line[line[0] * 2]; /* decrypt one line */ for (line += 4; line < next;) { *line++ ^= (key >> 8) & 0xFF; *line++ ^= key       & 0xFF; key = (key & 0xFFFF0000) | ((key+key2) & 0x0000FFFF); key2 += key3; key = (key >> 1) | (key << 31); }    }     src[10] ^= 0x20; /* toggle "is encrypted" bit */ }
 * 1) define EndGetM32(a) ((((a)[0])<<24)|(((a)[1])<<16)|(((a)[2])<<8)|((a)[3]))
 * 1) define EndGetM16(a) ((((a)[0])<<8)|((a)[1]))

AMOS Memory Banks
AMOS memory banks can be found either included with AMOS source code, saved individually on disk, where they typically have the file extension .ABK

AMOS allows for 15 banks in an program. Each bank can be located in "chip" memory, which is accessible to the Amiga's custom graphics and sound processors, or it can be located in "fast" memory, which is only accessible to the CPU.

Memory banks are identified by their first four bytes. They are either Sprite/Icon banks (using the ASCII identifier AmSp or AmIc ), or they are "normal" memory banks, which covers all other possible bank formats (using the identifier AmBk )

AMOS Sprite/Icon Bank format

 * ''See also: AMOS Sprite Bank and AMOS Icon Bank

A sprite bank and an icon bank share very similar attributes. They define graphic data which can be drawn onscreen. They have this format:

AMOS Memory Bank format
Apart from Sprite and Icon banks, each bank has a standard header

AMOS Music Bank format

 * ''See also: AMOS Music Bank

This bank has the name " Music  " and is created with various conversion utilities shipped with AMOS. It is played back with the Music extension.

AMOS AMAL Bank format
This bank has the name " Amal   ". It contains instructions in AMOS Animation Language format.

AMOS Menu Bank format
This bank has the name " Menu   ". It contains pull-down menu definitions.

AMOS Data Bank format
This bank has the name " Datas  ". It is created in AMOS using the  instruction, and has no specific format.

AMOS Work Bank format
This bank has the name " Work   ". It is created in AMOS using the  instruction, and has no specific format. As a Work bank, it is not saved as part of the source code, unlike normal data banks.

AMOS Asm Bank format
This bank has the name " Asm    ". It contains Amiga machine code that was loaded into a bank using the  instruction and has no specific format, other than containing MC680x0 binary code.

The  instruction takes the first code hunk out of an Amiga executable and copies it into the bank, without even applying its relocations, therefore all code needs to use PC-relative addressing. The  instruction jumps directly to the start of the bank. The registers (A0, A1, D0, D1, ...) can be set in preparation for a call by setting the  and   arrays. Extra parameters can also be included with the  instruction, these are made available to the called function via a stack pointed to by the A3 register.

AMOS Picture Bank format
This bank has the name " Pac.Pic. " and is created with the Compact extension's  instruction.

AMOS Samples Bank format
This bank has the name " Samples " and is created with the Sample Bank Editor shipped with AMOS. The samples can be played back with the Music extension. The format of the bank data is as follows:

The format of each sample is as follows:

Links and references

 * AMOS Extensions - Amiga Coding wiki
 * AMOS file formats - ExoticA
 * STOS and AMOS publishing history