Skip to content

.instructions.md

Latest commit

 

History

History
153 lines (111 loc) · 4.54 KB

.instructions.md

File metadata and controls

153 lines (111 loc) · 4.54 KB
Raw

.instructions for AGEMKI v32

Project: SCUMM Adventure Editor → DOS Motor (Electron + C/Watcom)
Target: 486DX2 @ 66MHz, 8MB RAM, DOS4GW
Tech: React 18 + Zustand | C (wcc386) | Open Watcom 2.0 | MPU-401 audio

🎯 Mission

Generate code for Electron editor + DOSBox-runnable GAME.EXE + binary GAME.DAT. Audio via native MPU-401 driver (no external libs).

⚙️ Critical Constraints

What Value Impact
CPU 486DX2 66MHz (27 MIPS) No complex loops; precomputed tables
RAM 8MB (7.3MB extended) DAT < 2MB; stack over malloc
Video VGA 13h (320×200×256) 64KB framebuffer only
Timer 18.2 Hz ISR Chain interrupts; don't replace
Audio MPU-401 @ 0x330 Non-blocking queue (32 bytes/frame max)

📚 Documentation

Always loaded:

  • This file

Loaded when you ask about keywords:

  • documentation/FETCH-SYSTEM.md — Q&A lookup | audio, MIDI, compile, DAT, motor
  • documentation/CONTEXT7-AGEMKI.md — Architecture | "how does", structure, design
  • documentation/AUDIO-GUIDE.md — Audio spec | OPL, soundcard, MIDI multi-tarjeta

On-demand:

  • src/main/dat/AGEMKI_DAT_SPEC.md — DAT binary format
  • documentation/INDEX.md — Navigation guide
  • documentation/legacy/ — Reference docs

🔧 4 Code Zones

  1. Editor (src/renderer/) — React + Zustand (UI, game design)
  2. Build (src/main/) — Node.js codegen → C code + DAT binary
  3. Motor (resources/engine/) — C + asm, VGA/input/pathfind/inventory
  4. Audio (resources/engine/mididrv.c) — MPU-401 driver, interrupt-chained

🚀 Build Pipeline

Editor → JSON → codegen (Node.js) → C code + GAME.DAT
                    ↓
              wcc386 -bt=dos -6r -ox
              wlink system dos4gw
                    ↓
              GAME.EXE (32-bit protected)
                    ↓
              DOSBox (mpu401=intelligent)

🔴 Top 8 Pitfalls (Avoid!)

  1. ISR chain broken → Motor hangs
  2. Shared inventory buffers → Sprites corrupt
  3. DAT chunks unsorted → Binary search fails
  4. AUDIO.DAT in XMI → No sound (use MIDI)
  5. DOSBox without mpu401=intelligent → No audio
  6. Blocking loops in script → Input freezes
  7. Watcom without DOS4GW → Won't run
  8. PCX > 256×256 → Memory overflow

✅ When Generating Code

  • C: No stdlib; use Watcom pragmas + inline asm; chain ISR
  • JS: React hooks, Zustand patterns, template strings for C codegen
  • DAT: Match AGEMKI_DAT_SPEC.md exactly (sorted chunks, CRC32)
  • Audio: MIDI via mididrv.c API (non-blocking)

📂 Files to Edit

File Purpose Action
src/main/index.js Build init ✅ Modify
src/main/datGenerator.js DAT writer ✅ Modify
resources/engine/agemki_engine.c Motor core ✅ Add handlers
resources/engine/mididrv.c Audio API ⚠️ Caution
resources/engine/mpu.c MPU-401 HW ❌ Frozen
documentation/ Refs ❌ Read-only

🔗 For questions: Check FETCH-SYSTEM.md first (< 10s). Then CONTEXT7-AGEMKI.md if needed.

  • Understood 486DX2 + 8MB constraints?
  • Read CONTEXT7-AGEMKI.md overview?
  • Checked FETCH-SYSTEM.md for your question?
  • If C code: DOS4GW compatible, no blocking calls, memory efficient?
  • If DAT: chunks ordered, CRC32 valid, AGEMKI_DAT_SPEC.md compliant?
  • If audio: using mididrv.c API, Format 0/1 MIDI, DOSBox configured?

📞 Reference Commands

# Build a game (from Windows)
npm run build

# Compile single C file with Watcom
wcc386 -bt=dos -6r -ox -w=3 file.c

# Link DOS4GW executable
wlink system dos4gw file.obj name file.exe

# Run in DOSBox-X (with mpu401=intelligent in config)
dosbox-x GAME.EXE

# Generate GAME.DAT (inside editor → Build button)
# → calls datGenerator.js → outputs GAME.DAT to build/

# Generate main.c with handlers
# → called from src/main/index.js during build

🏁 Success Criteria for Code

Any code you generate should:

  1. ✅ Compile cleanly with wcc386 -bt=dos
  2. ✅ Run in DOS (tested in DOSBox-X)
  3. ✅ Respect 8MB RAM limit
  4. ✅ Chain interrupts (don't replace ISR)
  5. ✅ Use non-blocking I/O where possible
  6. ✅ Follow AGEMKI naming conventions (g_* for globals, engine_* for API)
  7. ✅ Match style of existing agemki_engine.c code
  8. ✅ Include comments explaining hardware constraints

Configuration Version: v32 — March 2026
Last Updated: 2026-03-26
Maintainer: AGEMKI Development Team