T2 Design: Asset Extraction Readiness

# D2 Title-Menu Asset Extraction Workflow

## Overview

This guide explains how to extract D2 Disc 1 title-menu assets for D3-TUI validation when private D2 source material is available.

## Prerequisites

### Required Tools
- Python 3.8+
- D3-TUI repository cloned
- Private D2 assets staged at expected location

### Expected Asset Location

Private D2 material should be staged at:

Inside agent containers:

### Directory Structure

Recommended structure for private assets:

## Phase 1: Discovery

### Step 1: Verify Asset Availability

Check that private assets are available:
```bash
ls -la /from/assets/private/d2-title/extracted/

cd /work/repo
python3 tools/extract_d2_menu_assets.py \
    --discover \
    --d2-dir /from/assets/private/d2-title/extracted

cat tools/title_menu_manifest.json

{
  "version": "1.0.0",
  "target": "D2 Disc 1 Title Menu",
  "assets": [
    {
      "symbol": "d2_asset_title_bg",
      "source_file": "Q_TITLEBGMT0.PVM",
      "source_entry": "TITLEBGMT0",  // Update with actual entry name
      "decoder": "auto",
      "role": "background",
      "description": "Snowy mountain background layer 0"
    }
    // ... other assets
  ]
}

python3 tools/extract_d2_menu_assets.py \
    --manifest tools/title_menu_manifest.json \
    --dry-run

make d2-assets

python3 tools/extract_d2_menu_assets.py \
    --manifest tools/title_menu_manifest.json \
    --d2-dir /from/assets/private/d2-title/extracted

ls -la src/d3tui/assets/d2_menu_assets.*
head -20 src/d3tui/assets/d2_menu_assets.h

grep "d2_asset_title_" src/d3tui/assets/d2_menu_assets.h

// Replace draw_frame() with title-menu composition:
static void draw_title_menu_frame() {
    // Draw background layers
    blit_scaled(&d2_asset_title_bg, 0, 0, SCREEN_W, SCREEN_H);
    blit_scaled(&d2_asset_title_bg1, 0, 0, SCREEN_W, SCREEN_H);
    blit_scaled(&d2_asset_title_bg2, 0, 0, SCREEN_W, SCREEN_H);

    // Draw D2 logo (with translucency)
    blit_scaled(&d2_asset_title_logo, 100, 50, 440, 200);

    // Draw menu stack
    blit_scaled(&d2_asset_title_menu, 250, 250, 300, 150);

    // Draw snow particles (animated)
    draw_snow_particles();

    // Draw copyright
    blit_scaled(&d2_asset_comtit, 200, 450, 240, 30);
}

make flycast-image

python3 tools/extract_d2_menu_assets.py --discover --d2-dir /from/assets/private/d2-title/extracted

grep "extern const d2_menu_asset_t" src/d3tui/assets/d2_menu_assets.h

python3 --version

python3 tools/extract_d2_menu_assets.py \
    --manifest custom_manifest.json \
    --out-h custom_header.h \
    --out-c custom_source.c \
    --d2-dir /path/to/assets

Offset | Size | Description
0x00   | 4    | Magic: "PVMH"
0x04   | 4    | TOC size
0x08   | 2    | Unknown (usually 0x0100)
0x0A   | 2    | Entry count
0x0C   | var  | TOC entries (34 bytes each)

Offset | Size | Description
0x00   | 4    | Magic: "PVRT"
0x04   | 4    | Chunk size
0x08   | 1    | Pixel format
0x09   | 1    | Data format
0x0A   | 2    | Unknown (usually 0x0000)
0x0C   | 2    | Width
0x0E   | 2    | Height
0x10   | var  | Pixel data

## 2. Tooling Improvements

### Enhancement: Better Error Handling

**Current Issues**:
- Generic "File not found" errors don't suggest solutions
- Manifest validation errors aren't clear about what's wrong
- Discovery mode output could be more structured

**Proposed Improvements**:

1. **File Not Found Error**:
```python
# Before:
print(f"SKIP {symbol}: {source_path} not found ({notes})", file=sys.stderr)

# After:
print(
    f"ERROR: Asset file not found: {source_path}",
    f"  Expected location: {source_path}",
    f"  Check that private D2 assets are staged at:",
    f"    /from/assets/private/d2-title/extracted/",
    f"  Or custom location specified with --d2-dir",
    file=sys.stderr
)

# Before:
print(f"SKIP {symbol}: entry '{entry}' not in {source}. Available: {available}", file=sys.stderr)

# After:
print(
    f"ERROR: PVM entry not found: {source}:{entry}",
    f"  Available entries in {source}:",
    file=sys.stderr
)
for available_entry in sorted(entries.keys()):
    print(f"    - {available_entry}", file=sys.stderr)
print(
    f"  SUGGESTION: Run discovery mode to see all available entries:",
    f"    python3 tools/extract_d2_menu_assets.py --discover --d2-dir {args.d2_dir}",
    file=sys.stderr
)

# Before:
raise ValueError(f"{source_name} is not RGB565 square twiddled")

# After:
raise ValueError(
    f"Unsupported PVRT format in {source_name}: "
    f"pixel_format=0x{pixel_format:02x}, data_format=0x{data_format:02x}"
    f"\nSupported formats:"
    f"  RGB565 square twiddled (PF=0x01, DF=0x01)"
    f"  ARGB4444 square twiddled (PF=0x02, DF=0x01)"
    f"  ARGB1555 square twiddled (PF=0x03, DF=0x01)"
    f"  RGB565 VQ (PF=0x01, DF=0x03)"
    f"  RGB565 SMALLVQ (PF=0x01, DF=0x10)"
    f"\nIf you need support for this format, file an issue with:"
    f"  - Source file name"
    f"  - Discovery mode output"
    f"  - Visual target description"
)

def validate_manifest_only(d2_dir: Path, manifest: dict) -> None:
    """Validate manifest schema and logic without extracting assets."""
    errors = []
    warnings = []

    # Schema validation
    if "assets" not in manifest:
        errors.append("Manifest missing 'assets' key")
        return errors, warnings

    for idx, item in enumerate(manifest["assets"]):
        if "symbol" not in item:
            errors.append(f"Asset {idx}: missing 'symbol' key")
        if "source_file" not in item and "source" not in item:
            errors.append(f"Asset {idx} ({item.get('symbol', 'unnamed')}): missing 'source_file' or 'source' key")

        # Check for PVM files without entry names
        source = item.get("source_file", item.get("source", ""))
        if source.upper().endswith(".PVM"):
            if "source_entry" not in item and "entry" not in item:
                warnings.append(f"Asset {idx} ({item.get('symbol', 'unnamed')}): PVM file without entry name")

    return errors, warnings

# In main():
if args.dry_run:
    errors, warnings = validate_manifest_only(args.d2_dir, manifest)
    if errors:
        print("MANIFEST VALIDATION ERRORS:", file=sys.stderr)
        for error in errors:
            print(f"  - {error}", file=sys.stderr)
        sys.exit(1)
    if warnings:
        print("MANIFEST VALIDATION WARNINGS:", file=sys.stderr)
        for warning in warnings:
            print(f"  - {warning}", file=sys.stderr)
    print("Manifest validation passed. Assets that would be extracted:")
    for item in manifest.get("assets", []):
        print(f"  - {item.get('symbol', 'unnamed')}: {item.get('source_file', item.get('source', 'unknown'))}")
    sys.exit(0)

def discover_improved(d2_dir: Path) -> None:
    """Improved discovery mode with structured output and guidance."""

    print("=" * 70)
    print("D2 ASSET DISCOVERY REPORT")
    print("=" * 70)
    print(f"Scan directory: {d2_dir}")
    print(f"Generated: {datetime.datetime.now().isoformat()}")
    print()

    all_paths = sorted(
        p for p in d2_dir.rglob("*")
        if p.is_file() and p.suffix.upper() in (".PVM", ".PVR", ".CTS")
    )

    if not all_paths:
        print("⚠️  NO ASSETS FOUND")
        print()
        print("Expected assets should be staged at:")
        print("  /from/assets/private/d2-title/extracted/")
        print()
        print("Or specify custom location with --d2-dir")
        print()
        print("Expected files:")
        for expected in EXPECTED_ASSETS:
            print(f"  - {expected}")
        return

    print(f"Found {len(all_paths)} asset files:")
    print()

    for path in all_paths:
        rel = path.relative_to(d2_dir)
        print(f"─" * 70)
        print(f"File: {rel}")

        if path.suffix.upper() == ".PVM":
            try:
                blob = path.read_bytes()
                entries = pvm_entries(blob)
                print(f"Type: PVM container")
                print(f"Entries: {len(entries)}")
                print()
                print("  Entry Name          Offset    Format          Size")
                print("  " + "-" * 54)

                for name, offset in sorted(entries.items()):
                    try:
                        _, pf, df, w, h = parse_pvrt_header(blob, offset)
                        pf_label = PF_LABELS.get(pf, f"0x{pf:02x}")
                        df_label = DF_LABELS.get(df, f"0x{df:02x}")
                        print(f"  {name:20s} 0x{offset:06x} {pf_label}/{df_label:8s} {w:4d}x{h:3d}")
                    except ValueError as e:
                        print(f"  {name:20s} 0x{offset:06x} [ERROR: {str(e)[:30]}]")

                cts_path = path.with_suffix(".CTS")
                if cts_path.exists():
                    print(f"  [CTS companion: {cts_path.name}]")

            except Exception as e:
                print(f"  [ERROR reading file: {e}]")

        elif path.suffix.upper() == ".PVR":
            try:
                blob = path.read_bytes()
                offset = 16 if blob.startswith(b"GBIX") else 0
                _, pf, df, w, h = parse_pvrt_header(blob, offset)
                pf_label = PF_LABELS.get(pf, f"0x{pf:02x}")
                df_label = DF_LABELS.get(df, f"0x{df:02x}")
                print(f"Type: PVR texture")
                print(f"Format: {pf_label}/{df_label}")
                print(f"Size: {w}x{h}")
            except Exception as e:
                print(f"  [ERROR reading file: {e}]")

        elif path.suffix.upper() == ".CTS":
            print(f"Type: CTS animation sequence")
            print(f"Status: Not yet decoded (file issue if needed)")

        print()

    print("=" * 70)
    print("NEXT STEPS")
    print("=" * 70)
    print()
    print("1. Compare discovered assets with expected title-menu assets")
    print("2. Update tools/title_menu_manifest.json with correct entry names")
    print("3. Run extraction: make d2-assets")
    print("4. Update src/d3tui_main.c to use title-menu assets")
    print()
    print("For more information:")
    print("  docs/ASSET_EXTRACTION_WORKFLOW.md")
    print("  docs/D2_TITLE_MENU_TARGET.md")

{
  "symbol": "d2_asset_title_bg",
  "source_file": "Q_TITLEBGMT0.PVM",
  "source_entry": "TITLEBGMT0",
  "status": "speculative",  // "confirmed" or "speculative"
  "decoder": "auto",
  "role": "background",
  "description": "Snowy mountain background layer 0",
  "notes": "Entry name not yet validated against actual file"
}

{
  "version": "1.0.0",
  "target": "D2 Disc 1 Title Menu",
  "validation_status": "unvalidated",
  "validation_date": null,
  "validated_by": null,
  "description": "Asset manifest for D2 title menu. Entry names are speculative and must be validated by running --discover against actual private assets.",
  "assets": [...]
}

{
  "expected_assets": [
    "Q_TITLEBGMT0.PVM",
    "Q_TITLEBGMT1.PVM", 
    "Q_TITLEBGMT2.PVM",
    "Q_DMTITLE.PVM",
    "Q_TITLEMENU.PVM",
    "Q_DJSNOW.PVM",
    "SAKA_MNSNOW1A.PVM",
    "SAKA_MNSNOW1B.PVM",
    "SAKA_MNSNOW1C.PVM",
    "P_COMTIT.PVR"
  ],
  "assets": [...]
}