BLD Bytecode

BLD Bytecode

Full specification (342 lines) in docs/BLD_BYTECODE.md.

Overview

BLD files are bytecode scripts that drive all building/room interactions. Each of the 26 .BLD files contains:

1. 8-byte header (type, paragraph count, signature EE C6 EB EA, content type)
2. Raw bytecode at offset 0x08 (processed with substitution cipher)
3. Encrypted bytecode at offset 0xA0 (decrypted via ((b+41)&0xFF)^233)

Architecture

4-layer interpreter system:

Layer	Segment	Function
1	0FDC:0008	Entry point, loads BLD data
2	0FDC:01C0	Bytecode interpreter (opcodes 0xE4-0xFF)
3	1CD3:0004	47-case dispatch (shop, heal, combat, flags)
4	1E56:03F5	Text renderer with word-wrapping

Cipher

Bytes 0x57-0x96 map to letters via a substitution table (reverse-engineered from the original game EXE). Bytes 0x80-0xE3 are structural markers (narrative mode, punctuation, price encoding).

Key Opcodes

Opcode	Name
0xE4	WRITE_CHAR — Emit decoded character
0xEC	CHECK_FLAG_EC — Branch on TrainingComplete flag
0xEB	CHECK_FLAG_EB — Branch on Milestone flag
0xF5	SHOP_DISPATCH — Dispatch to fn1CD3 (47 cases)
0xF9	JUMP_INDEXED — Computed GOTO
0xFF	STOP_INTERPRETER

Tools

Convert between BLD and JSON:

python3 tools/bld/bld_json_converter.py to-json original/bld/
python3 tools/bld/bld_json_converter.py to-bld file.json
python3 tools/bld/bld_json_converter.py roundtrip original/bld/

All 26 BLD files converted to JSON are in json/.