conco/OpenMaidEngine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(opcodes): register full AGE opcode ABI

Browse Source
This commit is contained in:
gamer147
2026-07-28 22:21:40 -04:00
parent 8f84f0b083
commit 77c7b85612
8 changed files with 6682 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1497
docs/opcode-reference.md
View File

File diff suppressed because it is too large Load Diff

25
docs/remake-architecture-and-roadmap.md
View File

@@ -655,12 +655,21 @@ A cursory Kamidori boot probe on 2026-07-20 validated much of this boundary: its
archives loaded, `SYSTEM4.BIN` completed the initializer chain, call-script resolution entered
`TITLE.BIN`, and title graphics/resource commands resolved. The first hard stop was not a different
container or catalog. Kamidori's title loop reached opcode `0x1be` (`u0041D9D0`, argc 2) at bytecode
offset `0xd7`. That opcode exists in Kelebek's full AGE/SYS4 table, but it is absent from the generated
`build/opcodes.json` because that runtime artifact currently contains only opcodes observed in Himegari.
offset `0xd7`. That opcode existed in Kelebek's full AGE/SYS4 table, but was absent from the generated
`build/opcodes.json` because the runtime artifact contained only opcodes observed in Himegari.
`Sys4Loader` therefore stopped decoding at the unknown opcode; `TITLE.BIN` returned as if it had ended,
and Godot displayed its ordinary `— end —` marker instead of reporting an incompatibility.
The future multi-game design must keep three separate concepts:
**ABI-registry floor completed 2026-07-28.** `vm-map/opcodes.toml` and generated `build/opcodes.json`
now contain the complete 548-entry Kelebek AGE catalog: 248 instructions observed in Himegari and 300
catalog-only compatibility entries (including the already mapped but unused persistence opcode `0x19f`).
Each entry carries `observed_in_himegari`; per-game observation no longer limits decoding. A recognized
but unimplemented opcode reaches the VM's traced stub-and-advance fallback, so a probe continues beyond
it instead of losing the rest of the script. Catalog-only entries deliberately remain
`noop_headless=false`: skipping them is a temporary compatibility-probe behavior, not evidence that their
native effects are semantically safe to omit.
The multi-game design keeps three separate concepts:
1. A **version ABI registry** containing every known opcode number, operand count/shape, and version gate
needed to decode that SYS generation, regardless of whether the active game uses it.
@@ -669,11 +678,11 @@ The future multi-game design must keep three separate concepts:
3. **Semantic/runtime implementation coverage**, which may remain incomplete and should report a precise
unsupported-service error containing game/profile, script, opcode, and bytecode offset.
An opcode that is absent even from the selected version ABI should likewise be a structured decode error,
not a synthetic final instruction or natural script return. Supporting a new same-version game then means
selecting the complete shared ABI, measuring its corpus against existing semantics, and implementing only
the newly exercised services. It should not require cloning the VM or manufacturing a new parser table
from that game's corpus.
An opcode that is absent even from the selected version ABI should still become a structured decode error,
not a synthetic final instruction or natural script return; that diagnostic hardening remains open.
Supporting a new same-version game now means selecting the complete shared ABI, measuring its corpus
against existing semantics, and implementing only the newly exercised services. It does not require
cloning the VM or manufacturing a new parser table from that game's corpus.
The probe also exposed a separate profile/presentation concern: Kamidori creates a `1024x576` render
target while the current Himegari frontend assumes an `800x600` presentation. Logical canvas geometry,

2
docs/tools-reference.md
View File

@@ -36,7 +36,7 @@ All opcode knowledge (ABI, semantics, provenance, `depends_on`) is hand-edited *
| Tool | Purpose | Run | Reads → Writes |
|---|---|---|---|
| `opcodes_build.py` | Generator + linter for the opcode reference. | `--build` · `--lint` · `--bootstrap` | `vm-map/opcodes.toml` → ⚙ `tools/age_opcodes_himegari.py`, ⚙ `build/opcodes.json`, ⚙ `docs/opcode-reference.md`, ⚙ `build/opcode-coverage.md` |
| `opcodes_build.py` | Generator + linter for the opcode reference. `--bootstrap` appends entries observed in the Himegari corpus; `--bootstrap-age` appends every missing opcode from the pristine 548-entry AGE catalog as an unobserved compatibility stub. Catalog stubs retain Kelebek's ABI label/argument count so other AGE scripts decode past them, but remain `noop_headless=false`: the VM currently traces/skips them, while coverage continues to report them as unresolved rather than semantically safe. | `--build` · `--lint` · `--bootstrap` · `--bootstrap-age` | `vm-map/opcodes.toml` → ⚙ `tools/age_opcodes_himegari.py`, ⚙ `build/opcodes.json`, ⚙ `docs/opcode-reference.md`, ⚙ `build/opcode-coverage.md` |
| `opcodes_model.py` | In-memory model + loader + linter (dangling-ref / confidence-ceiling / vocabulary / dependents). | *Imported by `opcodes_build.py`.* | `vm-map/opcodes.toml` → — |
| `test_opcodes.py` | Unit tests for the opcode tooling. | `test_opcodes.py` | — |
| `opcode_context.py` | Read-only evidence gatherer for classifying unnamed opcodes (frequency, argc, operand-type signature, neighbours, disasm snippets, Kelebek comment). | `--top 20` · `opcode_context.py 0x1f4 0x71 …` | corpus → stdout |