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:

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.