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

D3-TUI Build/Validation Survey

Surveyor: builder-reviewer Timestamp: 2026-05-11T01:45:00Z Stage: T0 Intake → T1 Review / Research (Read-Only Proto-Run)

Executive Summary

The D3-TUI project is in a post-realignment phase targeting RG40XXV/Knulli FlycastVL validation of the D2 Disc 1 title menu. The build system is functional but blocked on asset extraction and validation infrastructure.

Build System Analysis

Makefile Structure

Root Makefile (/work/repo/Makefile): - Primary targets: all, elf, flycast-image, d2-assets, clean, verify-flycast, test, check, info - Delegates to scripts/build-dreamcast.sh for actual compilation - make all → make elf → builds KOS ELF - make flycast-image → builds and validates Flycast-compatible ELF - make d2-assets → extracts D2 title-menu assets via Python tool

Build Script (/work/repo/scripts/build-dreamcast.sh): - Detects KOS toolchain from multiple possible locations - Compiles 14+ source files into ELF - Validates ELF entry point (must be 0x8c... for Dreamcast RAM) - Generates manifest with SHA256, size, and build metadata - Supports two modes: elf and flycast-image

Source Structure

Core Sources (14 files):

src/d3tui_main.c
src/d3tui_kos_stubs.c
src/d3tui/assets/d2_menu_assets.c
src/d3tui/terminal/terminal_core.c
src/d3tui/terminal/terminal_state.c
src/d3tui/terminal/ansi_parser.c
src/d3tui/render/render_system.c
src/d3tui/font/font_system.c
src/d3tui/font/font_atlas.c
src/d3tui/input/input_system.c
src/d3tui/vmu/vmu_integration.c
src/d3tui/spectre/spectre_integration.c
src/d3tui/memory/memory_management.c
src/d3tui/debug/debug_system.c
src/d3tui/debug/debug_menu.c
src/d3tui/assets/asset_metadata.c
src/d3tui/d3tui_api.c
src/d3tui/test/test_framework.c

Optional Shachi Sources (4 files, if present):

workspace/shachi/src/vmu.c
workspace/shachi/src/sh4math.c
workspace/shachi/src/assets.c
workspace/shachi/src/profiler.c

Test Infrastructure

Test Location: src/tests/ (30+ test files) - Comprehensive test suite with multiple runners (test_runner.c, test_runner_simple.c, simple_test_runner.c) - Tests cover: terminal, render, font, input, VMU, SPECTRE, memory, debug, error handling, CRC32, decoders, patterns - Host compilation supported via GCC with KOS stub headers - Not wired into root Makefile - manual compilation required

Test Compilation Example:

cd src/tests
gcc -I ../../src -I ../../src/d3tui -I ../../src/d3tui/include \
    -D_DREAMCAST -D__DC__ \
    test_framework.c ../d3tui/test/test_framework.c \
    -o test_framework

Validation Infrastructure

Verification Scripts

  1. verify-flycast.sh: Validates Flycast image against manifest
  2. verify-build.sh: Comprehensive build verification (10895 lines)
  3. quick-verify.sh: Lightweight verification (2560 lines)
  4. verify_release.sh: Release validation (9440 lines)

Current Validation Status

Asset Extraction Pipeline

Current State

Blockers: 1. Private D2 assets not in repo (staged at /mnt/kitchen/from-house/assets/private/d2-title) 2. Title-menu PVM/PVR files not extracted from disc image 3. Manifest contains speculative placeholder entry names

Manifest: tools/title_menu_manifest.json - 11 assets defined for D2 title menu - Entry names are placeholders (e.g., "TITLEBGMT0", "DMTITLE", "TITLEMENU") - Requires --discover run against actual PVM files

Extraction Tool: tools/extract_d2_menu_assets.py - Supports manifest-driven extraction - Auto-detects PVRT formats (ARGB4444 twiddled, RGB565 twiddled, VQ/SMALLVQ RGB565) - Requires private D2 asset staging directory

Required Actions

  1. Extract title-menu PVMs/PVRs from private D2 disc image
  2. Run discovery: python3 tools/extract_d2_menu_assets.py --discover --d2-dir /from/assets/private/d2-title/extracted
  3. Update manifest with confirmed entry names
  4. Run: make d2-assets
  5. Update src/d3tui_main.c rendering loop

Build Blockers

Critical Blockers

  1. Asset Extraction Block: Cannot build title-menu assets without private D2 material
  2. Manifest Incomplete: Placeholder entry names prevent successful extraction
  3. Validation Loop: Hardware validation blocked (not current priority)

Minor Issues

  1. Test suite not wired into root Makefile
  2. Some Makefile targets marked as partial (test, check)
  3. Legacy CDI workflow deprecated but still present in docs

Toolchain Requirements

KOS Toolchain Detection

The build script searches for KOS in: 1. KOS_BASE environment variable 2. $ROOT_DIR/toolchains/kos 3. /opt/toolchains/dc/kos 4. $HOME/.pearl/staging/dc-sdk/dc/kos

Required Components: - environ_base.sh - sh-elf-gcc - sh-elf-readelf - sh-elf-size - kos-cc wrapper

Documentation Status

Authoritative Documents

✅ Current: - docs/REALIGNMENT_BRIEF.md - docs/D2_TITLE_MENU_TARGET.md - docs/ASSET_EXTRACTION_MAP.md - docs/BUILD_TARGET_POLICY.md - docs/AGENT_PROTOCOL.md

⚠️ Pre-realignment (reference only): - BUILD_VERIFICATION.md (2026-05-09) - BUILD_STATUS.md (2026-05-10)

Documentation Gaps

  1. No step-by-step asset extraction guide for private D2 material
  2. No visual reference in repo (only path to external PNG)
  3. No current validation checklist for Flycast image

Recommendations

Immediate Actions (T1)

  1. Asset Extraction: Extract title-menu PVMs/PVRs from private D2 disc image
  2. Manifest Update: Run discovery and update title_menu_manifest.json
  3. Asset Generation: Run make d2-assets
  4. Rendering Update: Update src/d3tui_main.c for title menu composition

Validation Improvements

  1. Create visual validation checklist based on D2_TITLE_MENU_TARGET.md
  2. Document Flycast validation procedure
  3. Add smoke test for asset extraction

Build System Improvements

  1. Wire test suite into root Makefile
  2. Add make test target that compiles and runs host tests
  3. Add asset extraction validation step

Conclusion

The D3-TUI build system is functional but blocked on asset extraction. The primary blockers are:

  1. Private D2 assets not available in repo
  2. Title-menu PVM/PVR files not extracted
  3. Manifest contains placeholder entry names

Once assets are extracted and the manifest is updated, the build pipeline should produce a Flycast-compatible ELF that can be validated against the D2 title menu target.

Next Steps: - Extract D2 title-menu assets from private staging - Update manifest with discovered entry names - Generate C assets via make d2-assets - Update rendering code - Validate against docs/D2_TITLE_MENU_TARGET.md

Survey Complete: 2026-05-11T01:45:00Z Status: Read-Only Proto-Run Complete Next Phase: Awaiting lead dispatch for implementation

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