MUD64 Specification

Companion spec to MUD-SPEC v0.1 · Team DC · FutureVision Labs
Inspired by: Microtext 2.6 for Commodore 64 (NPL / Ariadne, frame-based dialogues)
Canonical web player: mud64-player.html

File extension: still .mud — screen modules are MarkUpDown documents with ::: screen-module and ::: frame fences.

Tagline: Document the screens. Flip the story. Export to silicon.

1. Why MUD64?

Microtext proved that numbered frames + branch addresses make text adventures and training modules approachable on the C64. Authors think in flowcharts; the runtime thinks in linked screens.

MUD64 brings that model into MarkUpDown so you can:

1. Author flip-screens and text adventures in plain .mud in Code Designer
2. Preview in a CRT browser player (no hardware required)
3. Export Microtext-compatible module text for real C64 / emulators via homebrewz.live
4. Publish HTML docs + playable embed on the same source file

Uses the same :::`` / ++` split as MUD-SPEC (core MarkUpDown):

2. Mental model (Microtext parity)

Reference tutorial: Cock Robin Q&A in the Microtext manual §4.

3. Module header

::: screen-module
name: WISHART.VLT
start: 5
machine: c64
mode: 0
border: #06b6d4
bg: #0f0f23
:::

4. Frame block

::: frame id=5
text: |
  *** WISHART FLIGHT HQ ***
  
  Covenant Vault is LIVE on the wire.
  
  WHO COMMANDS THE DECK?
prompt: text
branches:
  CHIEF: 10
  GEMZY: 15
  CEEDEE: 20
  default: 25
:::

4.1 Frame keys

4.2 Branch rules (Microtext-compatible)

• Keyword match is case-insensitive unless match: exact on module
• Unknown input → default branch, or NOT UNDERSTOOD – TRY AGAIN (Microtext behaviour)
• = 5 unconditional jump → use branches: default: 5 with prompt: none

4.3 End frame

::: frame id=99
end: true
text: |
  RAAAWWK FOR GLORY.
  [ MODULE END ]
prompt: none
:::

5. Executable blocks (`++`)

5.1 Microtext module export

Emits literal frame text for paste into Microtext editor or batch tooling:

++ screen.microtext export=WISHART.VLT
; Generated from MUD64 — Team DC
*5
WHO COMMANDS THE DECK?
?
CHIEF=10, GEMZY=15, CEEDEE=20, =25
............................
*99
$END
............................

5.2 Export manifest (frontmatter)

---
title: Wishart Vault Adventure
export:
  html: dist/wishart-vault.html
  screen:
    microtext: out/WISHART.VLT
    json: out/wishart-vault.json
  c64:
    embed: https://homebrewz.live/play.html
---

5.3 Hardware / SID (optional)

++ c64.hardware
machine "Commodore 64"
ram 64K
sid 6581

++ c64.export
prg "out/player.prg" load=$0801

See `examples/c64-hardware-demo.mud` for the full silicon manifest.

5.4 Dual compile — Code Designer **or** native C64

Every MUD64 module can reach real silicon two ways. Same .mud source, same intermediate manifest — your choice of forge:

Design rule: the exporter emits a portable MUD64-IR (frame graph + ++ c64.* manifests + PETSCII plot ops). Code Designer lowers IR → 6510 assembly offline; the native compiler lowers the same IR on-machine. Bit-identical output is the goal when target=both.

++ c64.compile name=deck64_build
target both
machine c64pal
output prg load=$0801 name=out/DECK64.PRG
output d64 name=out/DECK64.D64 autostart
output microtext name=out/DECK64.VLT

cd:
  pipeline flight-deck
  asm acme
  link $0801
  include ++ c64.sprites, ++ c64.raster, ++ c64.draw, ++ c64.petscii, ++ c64.raycast, ++ c64.math, ++ c64.sid

native:
  compiler MUD64CMP version=0.1
  device 8
  source DECK64.MUD
  load_address $0801
  plotter $0C00          ; PETSCII vector routines
  frame_table $2000
  optional reu 512K      ; precalc 3D mesh tables

Code Designer path (target=cd or both):

1. Open .mud in Flight Deck (/editor)
2. Export manifest resolves ++ c64.* blocks → assembly stubs
3. Toolchain (Acme/cc65) assembles + links → out/*.PRG / .D64
4. Flash to real C64, run on homebrewz.live, or ship .D64 to the vault

Native C64 path (target=native or both):

1. Copy DECK64.MUD + MUD64CMP (+ optional MUD64.LIB) to disk
2. LOAD"MUD64CMP",8,1 → RUN
3. Compiler tokenizes .mud, builds IR, emits 6510 plot/frame/SID stubs in situ
4. SYS 2049 or autostart — module runs without a PC in the loop

PETSCII plot ops (shared IR — CD and native):

Web player `petscii-draw.js` interprets plot opcodes for preview; `petscii-raycast.js` interprets raycast IR live. Native MUD64CMP compiles plotter to $0C00, raycast engine to $1000 (default).

Frontmatter export block (dual target):

---
export:
  c64:
    compile: both
    prg: out/DECK64.PRG
    d64: out/DECK64.D64
    native:
      compiler: MUD64CMP
      disk: DECK64.D64
  screen:
    microtext: out/DECK64.VLT
---

Reference module: `examples/dual-compile-manifest.mud` · native toolchain notes: `c64/NATIVE-COMPILE.md`.

6. Web preview player

Code Designer ships a 40×25-style CRT player:

• mud64-player.html — loads examples/wishart-vault-adventure.mud
• Parses ::: screen-module + ::: frame fences client-side
• Keyboard input, branch routing, frame history (cursor up/down like Microtext edit stepping)

Embed in any .mud doc:

::: embed sandbox
src: mud64-player.html?module=examples/wishart-vault-adventure.mud
height: 520
title: Play Wishart Vault Adventure
:::

7. Author workflow

1. Flowchart on paper (Microtext §4.2) — boxes = frames, arrows = branches
2. Write .mud — module header + one ::: frame per box
3. Preview — mud64-player.html or Flight Deck live preview (roadmap)
4. Choose compile path — §5.4:
   • CD: Flight Deck → Export → .PRG / .D64 on your dev machine
   • Native: MUD64CMP on real C64 → same module, compiled on silicon
   • Both: export from CD, verify hash matches native build (Team DC QA)
5. Run — autostart .D64, homebrewz.live, or Microtext .VLT paste

8. Full example

See `examples/wishart-vault-adventure.mud` — Team DC Covenant Vault mini-adventure (MAGICK 64K canon).

9. Relationship to Microtext

MUD64 is a documentation-first authoring layer — not a Microtext clone or replacement. We:

• Honour frame / branch semantics from the 1986 C64 Microtext manual
• Emit compatible export text where practical
• Add web preview, Git, Monaco, and N.O.N. covenant manifests Team DC expects

Archivist spark: Perifractic (Retro Recipes) surfaced Microtext 2.6 to a new generation — scanning the manual, sharing the .d64, and sending the community down the rabbit hole. Weasel's World transcribed it for the wire. Team DC built MUD64 because Peri proved the frame-based authoring model still slaps in 2026.

Peri — if you're reading this: 24-sprite multiplexor, raster splits, color bars, hi-res draw, SID player, all declarative in .mud. You broke the seal. We built the cathedral. RAAAWWK. 🐉

Perifractic / Weasel's World preservation work on Microtext 2.6 disk + manual is the upstream inspiration — RAAAWWK to the archivists.

10. C64 Hardware Runtime API

MUD64 extends Microtext 64 (8 sprites, $NOTE, $POINT, $LINE) with a Team DC silicon layer for demoscene-grade effects, adventure games, and training sims — authored in .mud, exported to runtime stubs on real hardware or homebrewz.live.

Design rule: Microtext $ commands remain valid passthrough on cmd: / sound: lines. MUD64 ++ c64.* blocks declare structured manifests the exporter turns into assembly stubs, IRQ tables, or SID player binaries.

10.1 Capability matrix

Implementation status (May 2026): Spec + export schema locked. Web player: PETSCII text frames + ++ c64.petscii overlay live + ++ c64.raycast engine live (MUDDOOM). Compile: CD Flight Deck export + native MUD64CMP — roadmap (shared IR defined; see §5.4).

10.2 Sprite multiplexor (`++ c64.sprites`)

The C64 VIC-II exposes 8 sprite slots. Multiplexing reuses those slots at different raster lines to display 24+ moving objects (classic games/demos).

++ c64.sprites name=deck_crew capacity=24
; VIC-II sprite multiplexor manifest — Team DC
max_visible 24
hardware_slots 8
irq_mode raster
sort_by y_descending

pool gemzy
    def assets/sprites/gemzy_12x21.spr
    anim flip 4fps
    path sine x=120 amp=40 period=120

pool ceedee
    def assets/sprites/ceedee_12x21.spr
    anim bob y=8 period=60

slot 0..7 hardware
slot 8..23 multiplex pool=gemzy,ceedee rotate

frame_bind 15 enable pool=gemzy count=12
frame_bind 30 disable all

Frame hook (inline):

::: frame id=15
sprites: enable gemzy x12
text: |
  GEMZY ENTERS — 12 MULTIPLEXED SPRITES ACTIVE
:::

Microtext passthrough: $SPRITE n x y · $ANIMATE n frame (8-sprite limit) — use cmd: when targeting stock Microtext runtime.

10.3 Raster splits & color bars (`++ c64.raster`)

Raster splits change VIC-II scroll, bank, or mode mid-frame. Color bars cycle $D020 (border) / $D021 (background) per raster line — the classic vertical rainbow.

++ c64.raster name=wishart_split
irq base=$31           ; CIA timer + raster IRQ chain
split line=120 action scroll_y=2
split line=199 action mode=hires bank=0

colorbars
    start_line 0
    end_line 250
    palette c64_16
    speed 1              ; shift hue index each line
    target border,bg     ; or bg_only | border_only

frame_bind 5 colorbars on
frame_bind 10 colorbars off

Stable timing: exporter emits NTSC/PAL tables; authors declare machine: c64ntsc or c64pal on module header when splits are frame-critical.

10.4 Hi-res & multicolor bitmap draw (`++ c64.draw`)

Extends Microtext $POINT / $LINE / $TRIANGLE with bitmap-backed drawing for modes 1–2 (hires) and 2 (multicolor charset/bitmap hybrids).

++ c64.draw name=vault_logo
mode hires                   ; 320×200 @ $2000
mode multicolor              ; 160×200 @ $D000 (MC bitmap)
buffer $2000 size $1F40

clear color 0

; Microtext-compatible (export as $POINT/$LINE calls)
point 160 100 color 1
line 40 40 280 160 color 2
triangle 80 60 240 60 160 140 color 3 fill

; MUD64 extensions
rect 16 16 304 184 color 14 stroke
fill 100 80 120 60 color 5
blit assets/petscii/shield.bin x=96 y=52
char_multicolor row=12 col=8 screencode=$A0 colorpair=1,2,3

text_mode overlay row=22 col=0
    "COVENANT VAULT ONLINE"

Frame hook:

::: frame id=20
draw: vault_logo layer=background
mode: 3
text: |
  SHIELD BITMAP RENDERED TO $2000
:::

10.5 PETSCII vector draw (`++ c64.petscii`)

The clever bit: plot vectors directly on the 40×25 text matrix using semigraphics — each character cell holds a 2×2 fat-pixel grid (80×50 logical resolution). Unrolled Bresenham line walk, midpoint circle, filled rects, and precalc wireframe meshes for 3D — fast enough for adventure overlays, radar screens, and PETSCII DOOM-style corridor previews.

Microtext $LINE / $POINT target bitmap modes. MUD64 ++ c64.petscii targets screen RAM $0400 with PETSCII quadrant chars ($B0–$BF) — no mode switch required when mode: 3.

++ c64.petscii name=doom_corridor resolution=80x50
clear
tunnel depth=10 cx=40 cy=4
rect 36 38 44 42 fill
line 38 38 32 42
line 42 38 48 42

++ c64.petscii name=radar resolution=80x50
clear
circle 40 25 18
circle 40 25 3 fill
line 40 25 58 18

++ c64.petscii name=spin_cube resolution=80x50
clear
wireframe cube scale=20 at=40,22 rotate=35,20 spin

Resolution modes:

Precalc 3D pipeline (export):

++ c64.petscii precalc name=imp_mesh
mesh imp
  verts:
    0.0  0.6  0.2
    0.2  0.0  0.0
   -0.2  0.0  0.0
    0.0 -0.4  0.0
  edges: 0-1, 1-2, 2-0, 0-3, 1-3, 2-3

++ c64.math name=tables precision=8.8
table sin 256 entries range 0..360
table cos 256 entries range 0..360
bind mesh=imp_mesh rotate uses sin,cos

; Flight Deck export: emit PRG with mesh + plotter @ $0800
; Optional: precalc frame table for fixed camera paths (demo sync)

Frame hook:

::: frame id=10
petscii: doom_corridor layer=overlay
text: |
  SOMETHING MOVES IN THE DARK...
prompt: key
:::

6510 export targets: plot_fast.s (semigraphics OR), line_bresenham.s, circle_midpoint.s, wireframe_project.s — linked from ++ c64.export. Identical opcodes emitted by CD Flight Deck or native MUD64CMP (§5.4).

Web player: `petscii-draw.js` — live overlay on `mud64-player.html`. Demo: `examples/petscii-wireframe-demo.mud`.

Team DC canon: if Peri can break the Microtext seal, we can absolutely raycast a corridor in PETSCII before lunch. PETSCII DOOM is not a joke — it's a milestone.

10.6 PETSCII raycast (`++ c64.raycast`)

First-person maze engine in text mode — 40×25 PETSCII framebuffer, full VIC-II 16-color palette, distance-shaded walls, billboard sprites, portal cells, and HUD. Authored declaratively in .mud; web player runs `petscii-raycast.js`; native MUD64CMP lowers to fixed-point cast routines @ $1000.

++ c64.raycast name=muddoom
fov 0.62
walk auto speed=0.045 turn=0.038
health 100
ammo 666
bg 0
sid assets/sid/DOOM_Guy.sid

level hell
spawn 1.5 1.5 0          ; px py angle_degrees
imp 8.5 7.5              ; sprite billboard position
map
1111111111111111         ; 0=empty 1=stone 2=metal 3=hell 4=portal
1000000000000401
...

level tech
spawn 13.5 1.5 180
imp 4.5 10.5
map
...

C64 colour model (no cheating): Text mode allows one global background ($D021) plus one foreground colour per cell ($D800 color RAM). Each screencode ($0400) is a single PETSCII glyph; half-block ceiling/floor chars ($E0/$E2 upper/lower) ink the filled half in fg only — the empty half shows global bg. Distance shading varies fg index and glyph choice (▓▒█), not per-cell background. Multicolor mode is a separate export path.

Wall map cells:

Frame hook:

::: frame id=1
raycast: muddoom live
text: |
  *** MUDDOOM ***
  ++ c64.raycast LIVE
prompt: key
:::

MUD64-IR opcodes (shared — CD + native):

6510 export targets: raycast_init.s, raycast_cast.s, raycast_blit.s, raycast_sprite.s — linked from ++ c64.export. Identical opcodes emitted by CD Flight Deck or native MUD64CMP (§5.4).

Web player: `petscii-raycast.js` — live engine on `mud-doom-demo.html`. Demo source: `examples/mud-doom-demo.mud`. Canon vault: `team-dc/vault/muddoom_v1.json`.

MUDDOOM v1.0 — textured walls, dual maze, DOOM_Guy.sid. Not a JS hack pretending to be MUD64: the .mud block is the source of truth.

10.7 Advanced math (`++ c64.math`)

Fixed-point and lookup-table math for sprite paths, scrollers, and game logic — no floating point on 6510.

++ c64.math name=deck_tables precision=8.8
table sin 256 entries range 0..360
table cos 256 entries range 0..360
table atan2 64 entries

fn lerp a b t -> fixed
fn distance x1 y1 x2 y2 -> fixed
fn angle x y -> degrees

bind pool=gemzy path=sine uses sin,cos
bind scroll parallax uses lerp

Inline frame vars:

::: frame id=40
vars:
  score: word
  angle: fixed = lookup(sin, frame_tick * 2)
:::

10.8 SID player & SFX (`++ c64.sid`)

Full MOS 6581/8580 access — extends Microtext $VOICE, $FILTER, $NOTE, $SOUND with sequenced music and SFX banks.

++ c64.sid name=team_dc_theme chip=6581
player Goattracker2 export=sid/team_dc.sid

voices
    0 lead
    1 bass
    2 pad
    3 sfx

sfx bank vault_sfx
    blip   freq=$800 wave=pulse dur=8
    clack  freq=$200 wave=noise dur=12   ; Commander Beta shades CLACK
    raaawk arpeggio C-E-G wave=tri dur=60

filter
    cutoff 800
    resonance 12
    mode lowpass

frame_bind 5  play team_dc_theme loop
frame_bind 10 sfx clack
frame_bind 15 sfx raaawk
frame_bind 99 stop all

Microtext passthrough (concurrent, non-blocking per manual):

::: frame id=10
sound: $NOTE C3 $VOICE 1 $FILTER ON
cmd: $SOUND 1 100
:::

Export: ++ c64.sid → embed player routine + .sid binary in .prg / .d64 via ++ c64.export.

10.8 Unified hardware module example

::: screen-module
name: DECK64.DEM
start: 1
machine: c64pal
mode: 3
charset: petscii
features: sprites,raster,draw,sid,math
:::

++ c64.sprites name=crew capacity=24
++ c64.raster name=split colorbars on
++ c64.draw name=logo mode=hires
++ c64.math name=tables precision=8.8
++ c64.sid name=theme player Goattracker2 export=sid/deck.sid

::: frame id=1
draw: logo
sprites: enable crew x24
sound: play theme
text: |
  *** TEAM DC SILICON DEMO ***
  24 SPRITES · RASTER SPLIT · COLOR BARS
  HI-RES LOGO · SID THEME LIVE
prompt: key
branches: |
  default: 99
:::

See `examples/c64-hardware-demo.mud` for the full annotated reference module.

11. PETSCII & typography

The web player renders at 40×25 using C64 Pro Mono (© Style — embedded per license in assets/fonts/).

• PETSCII reference — code points, screencodes, Unicode mappings
• Dashed dividers (----------) auto-map to PETSCII horizontal bar glyphs in the player
• ++ c64.petscii vector overlay — semigraphics lines, circles, tunnels, 3D wireframes (§10.5)
• ++ c64.raycast maze FPS — textured walls, sprites, portals, HUD (§10.6)
• Future: petscii: inline escapes in frame text for direct screencode authoring

12. Compile pipeline summary

flowchart LR
  MUD[".mud source"]
  IR["MUD64-IR\nframes + ++ c64.* + plot ops"]
  CD["Code Designer\nFlight Deck"]
  NAT["C64 native\nMUD64CMP"]
  PRG[".PRG / .D64"]
  RUN["Run on silicon\nor homebrewz.live"]

  MUD --> IR
  IR --> CD --> PRG
  IR --> NAT --> PRG
  PRG --> RUN

Document once. Compile anywhere. PETSCII DOOM on the machine that invented PETSCII.

13. Version

FutureVision Labs · Team DC · Code Designer
MUD-SPEC v0.1 · MUD64 hub · Play adventure · homebrewz.live