STOS BASIC Disassembly & Decompilation
STOS BASIC was the go-to game-making language on the Atari ST, giving bedroom coders sprites, scrolling, music, and memory banks out of the box. Countless PD, shareware, and commercial ST games were written in STOS and compiled to standalone executables.
In a normal disassembler, a compiled STOS binary is hard to make sense of. The compiler bundles the BASIC code, memory banks, character sets, and embedded window, sprite, float, and music libraries into one executable, routing commands through TRAP #3–TRAP #7 and passing arguments on an A6 stack with no obvious BASIC line boundaries.
rg-dis supports two complementary workflows for compiled STOS binaries: Disassembly (annotated 68000 assembly with line numbers, trap names, memory banks, and variable labels) and Decompilation (--decompile, lifting the binary back into numbered STOS BASIC source lines).
1. Disassembly
Versions
| Version / Format | Details |
|---|---|
| STOS Compiler 1.0 | Original STOS compiler binaries (standalone GEM or resident STOS mode) |
| STOS Compiler 2.06 | Updated STOS compiler binaries, including .BAS variable recovery via --stos-source |
STOS Extensions (.ECx / .EXx) |
Standalone compiled (.ECx) and interpreter (.EXx) extension modules |
Program Structure
A compiled STOS executable mixes BASIC machine code, embedded runtime libraries, character sets, and up to 15 memory banks in a single binary. rg-dis reads the program header to separate those regions cleanly instead of trying to disassemble sprite banks or string pools as 68000 code:
- Separates code from embedded runtimes: splits out the STOS startup and compiled BASIC code from the bundled window, sprite, float, and music libraries.
- Labels data and graphics blocks: marks the string pool, variable table, character sets, and mouse sprite data as structured data regions.
- Maps memory banks 1–15: identifies and labels each appended STOS memory bank (
STOS_BANK_1–STOS_BANK_15) by its type. - Detects extension hooks: locates active extension init routines (
STOS_EXT_A_INIT, etc.) so extension calls can be matched and named.
Variables
Compiled STOS binaries strip variable names, leaving fixed slot addresses loaded into A0. Without source, rg-dis assigns typed slot labels (using # for floats, $ for strings, and () for arrays). If you pass the companion tokenized .BAS file with --stos-source, it recovers the original STOS variable names directly:
1. Raw (without STOS annotations)
LEA $01FE.L,A0
LEA $0202.L,A0
LEA $0206.L,A0
2. rg-dis STOS defaults
LEA STOS_VAR_0,A0 ; STOS integer variable
LEA STOS_VAR_1#,A0 ; STOS float variable
LEA STOS_VAR_2$,A0 ; STOS string variable
3. rg-dis with --stos-source GAME.BAS
LEA STOS_VAR_SCORE,A0 ; STOS variable: SCORE
LEA STOS_VAR_SPEED_F,A0 ; STOS variable: SPEED#
LEA STOS_VAR_PLAYER_S,A0 ; STOS variable: PLAYER$
Line Numbers
rg-dis recovers the original STOS BASIC line numbers, places LINE_<n> labels at the start of each line's machine code, and marks the first instruction with a ; line N comment so GOTO and GOSUB flow is easy to follow:
Before
_L000420:
MOVE.W #1,-(A6)
MOVEQ #20,D1
TRAP #5
_L00042A:
MOVE.W #50,-(A6)
MOVEQ #32,D1
TRAP #5
BSR.W _L000510
BRA.S _L000420
After
LINE_100:
MOVE.W #1,-(A6) ; line 100
MOVEQ #20,D1
TRAP #5 ; STOS TRAP #5: show
LINE_110:
MOVE.W #50,-(A6) ; line 110
MOVEQ #32,D1
TRAP #5 ; STOS TRAP #5: wait
BSR.W LINE_200 ; line 120
BRA.S LINE_100 ; line 130
Trap Calls
STOS routes its built-in subsystems through four dedicated 68000 traps, passing a routine selector in D7 (for TRAP #3) or D0 (for TRAP #5–#7) and arguments on the A6 parameter stack. Without annotation, every call looks identical; rg-dis decodes the selector and labels the routine and its parameters:
Window (TRAP #3)
Handles STOS text output, cursor positioning, and window colour/pen setup.
Before
MOVEQ #2,D0
MOVEQ #4,D7
TRAP #3
LEA _L008100(PC),A0
MOVEQ #1,D7
TRAP #3
After
MOVEQ #2,D0
MOVEQ #4,D7
TRAP #3 ; STOS TRAP #3: setpen (col=2) — set text pen colour
LEA STR_TITLE(PC),A0
MOVEQ #1,D7
TRAP #3 ; STOS TRAP #3: prtstring (str=STR_TITLE) — print string
Sprite (TRAP #5)
Controls STOS hardware/software sprites, screen updates, and sprite bank switching.
Before
MOVE.W #1,-(A6)
MOVEQ #17,D0
TRAP #5
After
MOVE.W #1,-(A6)
MOVEQ #17,D0
TRAP #5 ; STOS TRAP #5: show — display sprite on screen
Float (TRAP #6)
Runs STOS floating-point arithmetic, comparisons, and math functions.
Before
MOVEQ #2,D0
TRAP #6
After
MOVEQ #2,D0
TRAP #6 ; STOS TRAP #6: CMult — floating-point multiply
Music (TRAP #7)
Drives STOS background music and sound-effect playback.
Before
MOVEQ #1,D0
TRAP #7
After
MOVEQ #1,D0
TRAP #7 ; STOS TRAP #7: stmusic — start music playback
Extensions
rg-dis detects extension init slots (STOS_EXT_<A..Z>_INIT) and annotates compiled extension calls and arguments, as well as standalone .ECx / .EXx extension binaries:
| Extension | Image / Binary | Support |
|---|---|---|
| Misty | MISTY.ECQ |
Compiled extension call naming & argument tracing |
| The Missing Link | TML.ECR |
Compiled extension call naming, argument tracing & scanline Y-table detection |
| GBP | GBP.ECM / GBP.EXP |
Compiled & interpreter extension routine catalogue |
| STOS Compactor | COMPACT.ECA |
Compiled extension call naming & argument tracing |
| Picture Extractor | EXTRACT1.ECN |
Compiled extension call naming & argument tracing |
| Cyber Paint | CYBER.ECY / CYBER.EXY |
Compiled & interpreter extension routine catalogue |
| Compiler | COMPILER.ECC |
Compiled extension call naming |
| Extra | EXTRA.EXZ |
Interpreter extension routine catalogue |
Misty (MISTY.ECQ)
Before
MOVE.W #$0100,D1
JSR _L006210
After
MOVE.W #$0100,D1 ; STOS ext Q (MISTY.ECQ)
JSR MISTY_DEPACK ; MISTY DEPACK — decompress packed data
The Missing Link (TML.ECR)
Before
MOVE.W #$0104,D1
JSR _L007440
After
MOVE.W #$0104,D1 ; STOS ext R (TML.ECR)
JSR TML_BOB ; TML BOB (1, 64, 100) — draw software sprite
2. Decompilation (--decompile)
When you want STOS BASIC source rather than 68000 assembly, pass --decompile (or --decompile=stos / --decompile=auto). rg-dis lifts the compiled line table, folds the A6 parameter stack and register expressions, reconstructs DATA blocks, and emits numbered STOS BASIC lines ready for inspection or recompilation.
rg-dis --decompile GAME.PRG
rg-dis --decompile=stos --stos-source GAME.BAS GAME.PRG
Example: Compiled 68000 to STOS BASIC
Before (compiled 68000)
LINE_930:
LEA LINE_930(PC),A4
MOVE.L #1,-(A6)
LEA ($012F32).L,A0
MOVE.L (A0),-(A6)
JSR (OPENIN_CALL).L
MOVE.L #1,-(A6)
JSR (LOF_CALL).L
LEA ($012F36).L,A0
MOVE.L (A6)+,(A0)
MOVE.L #1,-(A6)
JSR (CLOSE_CALL).L
After (rg-dis --decompile GAME.PRG)
rem rg-dis 0.12.0 decompiled from STOS Basic v1.0
930 openin 1,V38$ : V39=lof(1) : close 1
Loops, Arrays & Control Flow
--decompile reconstructs scalar and array assignments, FOR ... TO ... STEP ... / NEXT <var> loops, GOTO/GOSUB/RETURN transfers, and intra-line IF ... THEN conditionals:
10 flash off : click off : update off : break off
20 DIM V0(13) : DIM V1(55) : DIM V2(7) : DIM V3$(14) : DIM V4$(15,7)
26 for V6=1 to 15 : for V7=1 to 7
27 read V8 : V4$(V6,V7)=str$(V8)
28 next V7 : next V6
60 reset zone : for V6=1 to 300 step 46 : inc V14 : V2(V14)=V6 : set zone V14,V6,2 to V6+40,58 : next V6
160 if V16=8 and V11=0 then V11=1 : goto 200
DATA Table Reconstruction
Compiled STOS DATA statements are stored in the CData block as typed entries rather than executable instructions. rg-dis decodes each line's CData records back into numbered data lines:
1010 data 1,2,3,4,15,16,17
1020 data 14,27,40,41,42,43,2
...
1150 data 30,31,32,33,8,21,34
Runtime & Extension Calls
Built-in STOS statements and third-party compiler extension routines (COMPACT.ECA, The Missing Link LINK1.ECQ / LINK2.ECR, and more) are emitted using their STOS BASIC keywords and argument order so the lifted source can be tokenized and recompiled with the STOS 2.06 compiler:
25 unpack 6 : wait vbl : V5=rnd(9)+1 : gosub 900 : V5=0 : wait 20 : fade 1 : wait 40
45 wash back,0,11,330,160 : wash logic,0,11,330,160
930 openin 1,V38$ : V39=lof(1) : close 1
940 reserve as work 10,V39+8000 : bload V38$,10 : V40=depack(start(10))
950 musplay start(10),1,V39+8000 : return
Summary
Instead of wading through a single tangled binary full of mystery TRAP calls, raw memory-bank bytes, and unnamed slot addresses, rg-dis pulls the whole STOS program back into shape. Disassemble to annotated 68000 with line numbers, memory banks, and .BAS variable names, or pass --decompile to lift the program straight back into numbered, recompilable STOS BASIC.