AMOS file formats

AMOS is the name of a family of BASIC-like programming languages created for the Amiga by François Lionet, who is also known for STOS for the Atari ST and ClickPlay for the IBM PC.

This article attempts to cover all file formats defined by AMOS itself.

All multi-byte integers are stored in big-endian format (the Amiga's native format) unless otherwise specified. All numbers are decimal, except for hexadecimal numbers prefixed by '$'.

Introduction to AMOS
AMOS is an interpreted, BASIC-like language. You work in AMOS's built-in source code editor. Your code is stored in memory as tokens; each BASIC keyword is represented by a 2-byte number. You edit each line in your program as text, but once you finish editing any line in your program and move onto the next, the line is (re-)converted to tokens.

Extensions

 * Main article: AMOS extensions

AMOS not only includes the core language, but allows loading extensions. These are written in assembly code, not AMOS, and they add more instructions and functions to the AMOS language. Extensions must be loaded into one of 25 "slots", each extension has a specific slot.

Sometimes, two extensions want to use the same slot; they can't do this, you can only have one or the other. Your choice of extensions, along with all other global settings, are stored in AMOS's config file. This is AMOS1_3_PAL.env, AMOS1_3_NTSC.env in AMOS 1.3, or AMOSPro_Interpreter_Config in AMOS Pro.

When you use extension instructions, the slot number and instruction offset gets saved into your source code. Without the correct version of the extension loaded in the correct slot, your program stops working; AMOS says "Extension Not Loaded" at you. Your source code has "Extension Z" or another letter of the alphabet where the extension's instruction once was.

Memory Banks
In order to work with multimedia such as pictures and music, AMOS uses the concept of memory banks. AMOS 1.x allows up to 15 banks per AMOS program, while AMOS Professional allows up to 65535.

For example, you can load several pieces of music into different memory banks, and then identify which one you want to play by bank number: Track Play 5 will play music in bank 5. Or you could load a packed picture into bank 4 and say Unpack 4 to 0 to unpack it to 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 Sprite or Bob. Bank 2 is for Icons, which are controlled with instructions beginning Icon. Bank 3 is used for music in AMOS's native music format.

If you have memory banks in use while saving your source code, the contents of the banks get saved along with them. This makes it easy to bundle your code with the data it works on.

Banks can also be loaded from and saved to disk using the Load and Save commands. For example:


 * Save "all_banks.abs" saves all banks to disk
 * Save "single_bank.abk", 6 saves a single bank to disk
 * Load "single_bank.abk" loads the file into same slot it was saved from, bank 6
 * Load "single_bank.abk", 11 loads the file into slot 11
 * Load "all_banks.abs" clears existing banks from the program and loads the banks from the file

AMOS source code file format
AMOS source code is normally stored in a file with the extension ".AMOS". The file on disk has this format:

The tokenised BASIC code is a sequence of lines. Each line has this format:

If the indent level is 2 or more, there are {indent level + 1} space characters as the beginning of the line.

Most tokens are exactly two bytes in size. A small number of tokens have special size rules and are larger than two bytes.

Token values $0000-$004E and $2B6A must be special printed, all others are simply a signed offset into AMOS's internal token table.


 * The only negative offsets are "operator" tokens ($FF3E to $FFF6, or -$00C2 to -$000A when interpreted as signed values); AMOS 1.3 resolves these by having operator tokens before the start of its token table. AMOS Pro has a separate list of the operator tokens, as its real token table does not have any negative offsets. Extensions are not allowed to have negative offsets in their token table.
 * All offsets are even, so the highest offset is $7FFE

Each line always ends with a compulsory null token ($0000).

Procedure decryption
If you should find a procedure token with the "is encrypted" bit set, run this C function on the code to decrypt the contents of the procedure.

AMOS Memory Bank formats
AMOS memory bank files on disk can be in one of three formats, depending on the 4-byte ASCII identifier they start with:


 * AmBs: multiple memory banks
 * AmSp or AmIc: a sprite/icon memory bank
 * AmBk: a single, regular memory bank

Memory banks saved inside AMOS source code are always in the "multiple memory banks" format.

Multiple memory banks
Multiple memory banks, as found following the tokenized BASIC code in an AMOS source code file, or found on disk (usually with the file extension ".abs") are several individual banks one after the other. They have this format:

AMOS Sprite and Icon bank formats
Sprite and icon banks define graphic data which can be drawn on-screen. There can only be one sprite bank and one icon bank per program. Even though it's possible to save multiple banks (e.g. create sprites, Bank Swap 1,10, create more sprites... leaving Sprites in both banks 1 and 10), loading the program will result in the later sprite banks overwriting the earlier ones.

Sprite and Icon banks do not have a "normal" bank header, they have their own format:

Regular memory bank format
Regular memory banks, as opposed to the special-case sprite/icon banks or multiple banks, have this format:

Each bank can be located in CHIP memory, which is accessible to the Amiga's custom graphics and sound processors, or FAST memory, which is only accessible to the CPU.

Standard AMOS bank formats
The following bank types are standard to AMOS: