Home > Runs > Proto Run > D3-TUI Executive Summary - Build/Validation Survey

D3-TUI Executive Summary - Build/Validation Survey

Date: 2026-05-11 Agent: builder-reviewer
Phase: T0 Intake → T1 Review/Research (Read-Only Proto-Run) Status: COMPLETE ✅

Mission Context

D3-TUI is realigning to a canonical Forgejo repo with a single authoritative target: - Validation Environment: RG40XXV/Knulli FlycastVL - Visual Target: D2 Disc 1 title menu (snowy mountain, animated snow, red D2 logo, menu stack, WARP copyright) - Build Target: Flycast-compatible ELF with extracted D2 assets

Build System Status

✅ Functional Components

Build Pipeline: - make elf → Compiles KOS ELF (14+ source files) - make flycast-image → Builds validated Flycast ELF + manifest - make d2-assets → Extracts D2 title-menu assets (BLOCKED: needs private material) - make clean → Proper cleanup

Build Script (scripts/build-dreamcast.sh): - KOS toolchain auto-detection (4 fallback paths) - ELF compilation with validation (entry point must be 0x8c...) - Manifest generation (SHA256, size, build metadata) - Two modes: elf and flycast-image

Source Structure: - 14 core D3-TUI source files - 4 optional Shachi source files (if present) - Well-organized modular architecture

Test Infrastructure: - 30+ test files in src/tests/ - Comprehensive coverage: terminal, render, font, input, VMU, SPECTRE, memory, debug - Host compilation supported (manual, not wired into Makefile)

Critical Blockers

🚧 Asset Extraction Pipeline

Problem: Cannot build the D2 title menu target without extracted assets.

Root Causes: 1. Private Assets Missing: D2 material staged externally at /mnt/kitchen/from-house/assets/private/d2-title 2. Extraction Not Done: Title-menu PVM/PVR files not extracted from disc image 3. Manifest Incomplete: title_menu_manifest.json contains placeholder entry names

Required Files (from docs/ASSET_EXTRACTION_MAP.md):

NLOGO.PVM / NLOGO.CTS
Q_TITLEBGMT0.PVM
Q_TITLEBGMT1.PVM
Q_TITLEBGMT2.PVM
Q_TITLEMENU.PVM
Q_TITLE2D.PVM
Q_DMTITLE.PVM
TITLELOAD.PVM
Q_DJSNOW.PVM
SAKA_MNSNOW1A.PVM / .CTS
SAKA_MNSNOW1B.PVM / .CTS
SAKA_MNSNOW1C.PVM / .CTS
P_COMTIT*.PVR
P_COMTWD*.PVR

Extraction Workflow:

# 1. Extract PVM/PVR files from private D2 disc image
# 2. Run discovery to find exact entry names
python3 tools/extract_d2_menu_assets.py --discover --d2-dir /path/to/extracted

# 3. Update manifest with confirmed names
vim tools/title_menu_manifest.json

# 4. Generate C assets
make d2-assets

# 5. Update rendering code
vim src/d3tui_main.c

Validation Infrastructure

✅ Available

ELF Validation: - Entry point check (must be 0x8c... for Dreamcast RAM) - Size and SHA256 manifest generation

Flycast Validation: - make verify-flycast script - Manifest-based validation

Visual Target: - Defined in docs/D2_TITLE_MENU_TARGET.md - Reference image: /mnt/kitchen/from-house/control-room/d3-tui/D2-title-menu-target-20260510.png

⚠️ Blocked/Deferred

Hardware Validation: - RG40XXV access not required for current phase - Visual validation against target definition is sufficient

Documentation Status

✅ Authoritative (Current)

⚠️ Reference Only (Pre-realignment)

Next Steps (Requires Lead Dispatch)

🔧 Immediate Technical Work

  1. Extract D2 Assets:
  2. Extract title-menu PVM/PVR files from private D2 disc image

  3. Stage in /mnt/kitchen/from-house/assets/private/d2-title/extracted

  4. Discover Entry Names: bash python3 tools/extract_d2_menu_assets.py --discover --d2-dir /path/to/extracted

  5. Update Manifest:

  6. Correct entry names in tools/title_menu_manifest.json

  7. Verify all 11 assets have valid sources

  8. Generate C Assets: bash make d2-assets

  9. Update Rendering:

  10. Modify src/d3tui_main.c to compose title menu
  11. Replace W/A/R/P decoder evidence with title menu assets

📋 Process Improvements

  1. Wire Tests into Makefile:
  2. Add make test target

  3. Automate host test compilation and execution

  4. Asset Extraction Guide:

  5. Document step-by-step extraction from private D2 material

  6. Add to docs/ASSET_EXTRACTION_MAP.md

  7. Validation Checklist:

  8. Create Flycast validation checklist
  9. Document visual validation procedure

Risk Assessment

High Risk 🔴

Medium Risk 🟡

Low Risk 🟢

Recommendations

For Team Lead

  1. Prioritize Asset Extraction: This is the critical path blocker
  2. Assign Extraction Task: Designate agent to extract PVM/PVR files from private D2 staging
  3. Review Manifest: Validate title_menu_manifest.json after discovery run
  4. Dispatch Implementation: Explicit dispatch required before source modifications

For Build/Validation

  1. Keep Build System Simple: Current Makefile is clean and functional
  2. Add Test Automation: Wire tests into Makefile for CI-like validation
  3. Document Everything: Especially asset extraction and validation procedures

Conclusion

The D3-TUI project has a functional build system and clear target definition, but is blocked on asset extraction. The critical path is:

  1. Extract D2 title-menu assets from private staging
  2. Discover exact PVM entry names
  3. Update manifest and generate C assets
  4. Update rendering code
  5. Build and validate Flycast image

All other components are ready: build system, test infrastructure, validation scripts, and documentation.

Artifacts Produced

Status: Ready for lead dispatch and asset extraction task assignment.

Survey complete. Awaiting instructions.

Last generated: 2026-05-11 20:15 UTC | v0.2.0