Dispel Extractor Implementation Skill

Overview

This skill enables an AI agent to execute, debug, and validate the Dispel Game File Extractor (dispel-extractor) during implementation. It provides structured workflows for running the extractor, patching game files, and understanding its architecture.

Purpose

• Automate the execution of dispel-extractor during development.
• Validate file parsing, extraction, and output generation.
• Patch (modify) game files from JSON for modding purposes.
• Provide debugging support for format compliance and error handling.
• Ensure adherence to the project's legal guidelines.

Running the Tool

Build

bash
1cargo build --release

Common Commands

bash
1# Extract game files to JSON (auto-detects type by filename)
2cargo run -- extract -i <file> [-o <output.json>] [--pretty]
3cargo run -- extract -i fixtures/Dispel/CharacterInGame/WeaponItem.db
4cargo run -- extract -i fixtures/Dispel/MonsterInGame/Monster.db -o monsters.json
5cargo run -- extract -i fixtures/Dispel/Map/cat1.map --pretty
6
7# Extract with type override (for ambiguous files)
8cargo run -- extract -i unknown_file --type weapons
9
10# Patch game files from JSON
11cargo run -- patch -i <input.json> -t <target-file> [--in-place] [--dry-run] [--no-backup]
12cargo run -- patch -i weapons.json -t weaponItem.db --in-place
13cargo run -- patch -i monsters.json -t Monster.db --dry-run
14
15# Validate JSON against file format
16cargo run -- validate -i <input.json> --type <type> [--verbose]
17cargo run -- validate -i weapons.json --type weapons
18
19# List supported file types
20cargo run -- list
21cargo run -- list --format json
22cargo run -- list --filter monster
23
24# Get JSON schema for a file type (AI-friendly)
25cargo run -- schema --type weapons
26
27# Get record template for a file type
28cargo run -- template --type weapons [--pretty]
29
30# Map operations
31cargo run -- map tiles <input.gtl> [--output <dir>]
32cargo run -- map atlas <input.gtl> <output.png>
33cargo run -- map render --map <map> --btl <btl> --gtl <gtl> --output <output>
34cargo run -- map from-db --map-id <id> --gtl-atlas <path> --btl-atlas <path> --output <out>
35cargo run -- map to-db --database <db> --map <map.file>
36cargo run -- map to-json --input <map.file> [--output <out.json>] [--pretty]
37cargo run -- map sprites <input.map> [--output <dir>]
38
39# Database operations
40cargo run -- database import <game_path> <db_path>
41cargo run -- database dialog-texts <game_path> <db_path>
42cargo run -- database maps <game_path> <db_path>
43
44# Sprite extraction
45cargo run -- sprite <input.spr>
46cargo run -- sprite <input.spr> --mode animation
47cargo run -- sprite <input.spr> --info
48
49# Extract sprite info via unified extract command (auto-detected by .spr extension)
50cargo run -- extract -i <input.spr> [--pretty]
51
52# Audio conversion
53cargo run -- sound <input.snf> <output.wav>
54
55# Test
56cargo run -- test --message "hello"

Deprecated Commands

The ref command is deprecated but still works with a migration hint:

bash
1# Old (deprecated, shows hint)
2cargo run -- ref weapons fixtures/Dispel/CharacterInGame/weaponItem.db
3
4# New (preferred)
5cargo run -- extract -i fixtures/Dispel/CharacterInGame/weaponItem.db --type weapons

Architecture

Command Pattern (src/commands/mod.rs)

All commands implement the Command trait:

rust
1pub trait Command: Send + Sync {
2    fn execute(&self) -> Result<(), Box<dyn Error>>;
3    fn name(&self) -> &'static str;
4    fn description(&self) -> &'static str;
5}

A CommandFactory provides dependency injection for creating commands.

Module Structure

Supported File Formats

Maps: .map, .gtl (ground tiles), .btl (building tiles) Sprites: .spr (static or animated) Audio: .snf (raw PCM) Reference Files: .ini, .db, .ref, .dlg, .pgp, .scr

Supported Reference File Types (31 total)

Auto-Detection

File types are detected by filename (case-insensitive). For example:

• WeaponItem.db → weapons
• Monster.db → monsters
• Store.db → store
• cat1.map → map_file
• cat1.gtl → gtl
• PartyRef.ref → party_ref

Use --type <key> to override auto-detection.

Adding New Features

Adding a new reference parser

1. Create parser struct in src/references/ implementing Extractor trait (read_file + save_file)
2. Add Deserialize derive to the struct (required for patch support)
3. Add entry to FILE_TYPES in src/commands/registry.rs with DetectKind for auto-detection
4. Add SQL templates in src/queries/ (optional, for database import)
5. No changes needed in main.rs — the registry handles routing automatically

Adding a new map subcommand

1. Add variant to MapCommands enum in src/main.rs
2. Add variant to MapSubcommand in src/commands/map.rs
3. Implement in src/map/ modules
4. Wire up in main.rs match statement

Adding a new extract-only file type (no patch)

1. Add entry to FILE_TYPES in src/commands/registry.rs
2. Use patch_not_supported as the patch_fn
3. Implement a custom extract_fn that returns serde_json::Value

Testing

bash
1cargo test

Error Handling

References

• Extractor CLI: cargo run -- --help
• File Formats: docs/file_formats.md
• Cross-Reference Guide: CROSS_REFERENCES.md
• INI Files:
  • AllMap.ini.md
  • Event.ini.md
  • Extra.ini.md
  • Npc.ini.md
  • Wave.ini.md
• Database Files:
  • CharacterInGame/
    • ChData.db.md
    • EditItem.db.md
    • EventItem.db.md
    • HealItem.db.md
    • MiscItem.db.md
    • Monster.ini.md
    • Store.db.md
    • WeaponItem.db.md
  • Ref/
    • DrawItem.db.md
    • Magic.db.md
    • Map.ini.md
    • PartyRef.ref.md
  • MonsterInGame/
    • MondunMonmap.ref.md
    • Monster.db.md
  • NpcInGame/
    • DlgMapFiles.dlg.md
    • Eventnpc.ref.md
    • NpcMapFiles.ref.md
    • PgpMapFiles.pgp.md
    • PrtLevel.db.md
  • ExtraInGame/
    • Extra.ref.md
    • Message.scr.md
    • Quest.scr.md
  • Map/
    • Map.btl.md
    • Map.gtl.md
    • Map.map.md
    • MapModule.md
    • Sprites.spr.md

Legal Compliance Checklist

• Test files are synthetic or documented
• Outputs use generic identifiers (e.g., monster_id not "Goblin")
• No copyrighted content in outputs
• Focus on technical specs, not creative works
• Patch operations only modify game files for personal modding — no distribution of modified assets

See AGENTS.md for full guidelines.