patapon-pac-tools

PAC bytecode decompiler/recompiler for Patapon 2 & Patapon 3 (PSP)

---

pactool converts PAC binary files into an editable text format (.pacs) and back. It uses symbolic labels instead of raw byte offsets, so you can freely insert or remove instructions without manually fixing jump targets.

vscode-pacs is a VSCode extension with syntax highlighting, diagnostics, formatting, hover docs, autocomplete, and go-to-definition for .pacs files.

Both raw and HL text formats achieve byte-exact roundtrip on all 204 Patapon 2 and 74 Patapon 3 PAC files.

Prerequisites

• Python 3.12+
• uv
• just
• Node.js 18+ and pnpm (for the VSCode extension)

Setup

just setup          # Install Python dependencies
just vscode-install # Build & install VSCode extension (optional)
just lint           # Lint Python + TypeScript
just lint-fix       # Lint and auto-fix

Usage

All commands accept a single file or a directory. Pass any pactool flags after the path.

just decompile input/p2                       # All P2 files, raw format
just decompile input/p2 -f hl -o output/p2    # All P2 files, HL format with output dir
just decompile input/p3 -g p3                 # All P3 files
just decompile input/p2/actor.pac -f hl       # Single file

just compile output/p2                        # Compile all .pacs back to PAC
just compile output/p2/actor.pacs             # Single file

just roundtrip input/p2                       # Verify byte-exact roundtrip
just roundtrip input/p3 -g p3 -f hl          # P3 HL format roundtrip

Or call pactool directly:

cd pactool
uv run pactool decompile <path> [-o output] [-g p2|p3] [-f raw|hl] [-r] [-j N]
uv run pactool compile <path> [-o output] [-r] [-j N]
uv run pactool roundtrip <path> [-g p2|p3] [-f raw|hl] [-r] [-j N]

Options

Option	Description
-o, --output	Output file or directory
-g, --game	Game version: p2 (default) or p3
-f, --format	Text format: raw (default) or hl
-r, --recursive	Recurse into subdirectories
-j, --jobs	Parallel workers (default: CPU count)
--alias-min	Min variable uses to generate aliases in HL (default 3, 0=disable)
--alias-scope	Alias placement: top or auto (default, locals near usage)
--show-offsets	Show byte offsets as comments on labels

Text Formats

Raw

Assembly-like, one-to-one mapping to binary instructions:

.script "actor.pac"
.game p2
.instructionset "auto"
.format raw

@label_01:
    setScriptLabelTable jump_destination=@label_04
    cmd_waitFrame frames_to_wait=i:1

@label_02:
    cmd_waitFrame frames_to_wait=i:1
    cmd_jmp address=@label_02

HL (high-level)

Control flow keywords, variable aliases, and syntactic sugar:

.script "actor.pac"
.game p2
.instructionset "auto"
.format hl

.define $health il[10]
.define $speed fl[5]

@label_01:
    setScriptLabelTable(jump_destination=@label_04)
    WAIT_FRAME(1)

@label_02:
    WAIT_FRAME(1)
    IF ($health == 0) GOTO @label_03
    $speed += 0.5
    GOTO @label_02

@label_03:
    RETURN

HL sugar includes IF/GOTO/CALL/RETURN, SWITCH-CASE, FLAGS[...] operations, INDEX_JMP inline, assignment operators (+=, -=, ++, --), function assignment ($x = func(args)), tuple assignment (($x, $y) = func(args)), and math functions (SIN, COS, ABS, etc.).

VSCode Extension

Features

• Syntax highlighting for raw and HL formats
• Diagnostics: unknown instructions, wrong param count, undefined/duplicate labels, undefined aliases, header validation
• Formatter (Shift+Alt+F): indentation, spacing, trailing whitespace
• Go to Definition (F12): @labels, $aliases, variable refs
• Hover: instruction docs with parameters, HL keyword mapping, alias resolution
• Autocomplete: instructions with signatures, HL keywords, @labels, $aliases, directives with value choices

Install

just vscode-install

Reload VSCode after install (Ctrl+Shift+P -> Reload Window).

Settings

Setting	Default	Description
pacs.diagnostics.enabled	true	Enable/disable diagnostics
pacs.formatter.indentSize	4	Indentation spaces under labels

Project Structure

patapon-pac-tools/
  pactool/                # Decompiler/recompiler (Python, uv)
    src/pactool/
      cli.py              # CLI (typer)
      models.py           # Data models
      instruction_db.py   # Instruction set loader
      binary/             # PAC binary reader/writer
      script/             # Text emitter/parser, Lark grammars
      res/                # Instruction set definitions
  vscode_pacs/            # VSCode extension (TypeScript, pnpm, esbuild)
    src/                  # Extension source
    syntaxes/             # TextMate grammar
    data/                 # Bundled instruction CSVs + docs JSON
  justfile                # Task runner

Acknowledgments

PAC format research and documentation by:

• kanelikki
• Nemoumbra
• owodzeg
• The Patapon Modding Discord community

Built by efonte.

License

MIT