UTTORI ASM · IN DEVELOPMENT

SNES CLI workflows

Build SNES source, import evidence and integrate verified generations with native Git.

On this page

The bundled SNES plugin supplies the default snes.sfc assembly target. Core has no default target. Project configuration overrides host defaults, and explicit CLI options override configuration. Other installed target plugins change assembly choices; the ROM-analysis and Git source commands below currently support SNES.

Assemble and patch

npx uttori-asm main.asm
npx uttori-asm patch.asm patched.sfc --base-image original.sfc --debug

An omitted output uses the selected target's extension. Patching preserves unwritten bytes and permits growth; SNES finalization normally updates the checksum. Set the SNES plugin's checksumEnabled: false to preserve checksum fields. Mapper addresses refer to headerless ROM content.

Git source workflow

Requires Node.js 26+, Git with a configured author, and an original ROM you can use. Create a new source project:

npx uttori-asm source init game-source game.sfc --mapper lorom
# Optional creation import: --dizraw research.dizraw
npx uttori-asm source import game-source capture.act2
npx uttori-asm source analyze game-source
npx uttori-asm source prepare game-source
npx uttori-asm source preview game-source <candidate-commit>
git -C game-source add <reviewed-paths>
git -C game-source commit -m "Checkpoint source edits"
npx uttori-asm source apply game-source <candidate-commit>
# Resolve conflicts with Git or VS Code and stage the intended result.
npx uttori-asm source finish game-source
npx uttori-asm source build game-source

prepare returns the candidate commit used by preview and apply. Preparation generates an immutable incoming tree and proves that it rebuilds the original ROM. Preview includes current uncommitted edits and preserves the working tree and index. Apply requires a saved, clean committed checkpoint and the matching preview. Finish validates the staged merge result before committing it. If an already accepted candidate needs no merge, inspect status instead of finishing a nonexistent merge.

Assembly, assets, maps and .uttori/research/ are ordinary editable Git inputs. A build of current source may intentionally differ from the original ROM and requires no commit. Regeneration integrates new evidence through a native three-way Git merge. It does not replace your edited source directory.

Source command	Purpose
`init`	Create a new project, privately copy the ROM, analyze and adopt a verified initial generation
`status`	Inspect accepted generation, current inputs and pending merge
`import`	Import a matching instruction or bus ACT2/JSON capture and update its portable catalog
`catalog`	Reconcile retained capture identities without reimporting evidence
`index`	Synchronize tracked research into the SQLite evidence index
`analyze`	Synchronize research and analyze retained evidence
`prepare`	Produce and verify an immutable pure generation
`preview`	Review the candidate against current source, including supported editor overlays
`apply`	Start the previewed native merge from a clean committed checkpoint
`finish`	Validate the resolved staged result and commit the merge
`abort`	Abort the active regeneration merge back to its checkpoint
`discard`	Release a selected candidate without applying it
`clean`	Reclaim proven-owned abandoned temporary data and pins
`build`	Build saved current source and publish its ROM/debug-map receipt
`research`	Inspect research or prepare content-checked symbol/analysis JSON edits
`relocate`, `expand`	Propose checked edits using explicit object, reference, free-space and capacity contracts

source research returns proposals; saving those files is a separate source edit. Relocation needs declared movable objects, complete references and proven free space. Expansion takes an explicit supported capacity in bytes. See source projects in VS Code and the runnable library workflow.

Project files and original identities

New projects put assembly under source/. .uttori/project.json selects source/research roots, the build configuration, layout and capture catalog. .uttori/generation.json identifies the adopted generation. .uttori/generation-inputs.json names recipes and pristine assets. Ignored .uttori-local/project.json binds the private original ROM and SQLite evidence directory. A clone needs a valid local binding and retained evidence before preparing a generation.

Pristine assets normally come from the accepted pure generation. A new original asset may declare either a bounded romRange or an immutable Git originalBlob, together with the exact SHA-256. Mutable working assets do not become the next pristine baseline. Research retains original ROM coordinates and record IDs through renames and relocation. Build checks include declared CPU state, layout, references and asset consumption.

Standalone evidence projects

Use these commands when you need an analysis database without a Git source workspace:

npx uttori-asm disassemble game.sfc game.analysis --mapper lorom
npx uttori-asm project-validate game.analysis --rom game.sfc
npx uttori-asm evidence-import game.analysis --rom game.sfc --instruction-trace capture.json
npx uttori-asm analyze game.analysis --rom game.sfc --entry='$008000'
npx uttori-asm evidence-report game.analysis report.json
npx uttori-asm project-storage game.analysis
npx uttori-asm project-compact game.analysis

Creation defaults to <rom stem>.analysis, detects mapper/copier header conservatively, accepts --header-size 0|512 and optional uncompressed --dizraw, and refuses an occupied directory. Ambiguous mapper detection requires --mapper. Compressed .diz input and .dizraw export are unsupported. analyze accepts repeatable 24-bit CPU --entry addresses, positive --max-work-items (default 1,000,000) and nonnegative --max-call-depth (default 16). An explicitly incomplete result still returns success; inspect its status and reasons.

Instruction imports stream through SQLite and default to full indexing, retaining every supplied register, fetched byte, qualified PC and bus observation. --trace-index full is the only supported profile. --trace-max-mib defaults to 2048; use 4096 for a 4 GiB recording. SQLite-backed indexing has no fixed 8M fact ceiling, while in-memory library imports default to 8,000,000 records. Input-byte and storage budgets still apply. Exact reimports preserve counts. Keep original archives for ordered history and replay.

project-storage accepts --cache-max-mib (default 256) and --storage-max-mib (0 disables the live-page ceiling); evidence-import also accepts those budget options. project-compact checkpoints WAL, prunes unused dictionary entries and runs VACUUM with a temporary-space check. It preserves logical records and revision. See trace import and backup and recovery.

Saved asset editing

uttori-asm asset export, review, apply, recover and cleanup operate on saved asset documents in Git source projects. Apply requires the exact review ID and unchanged dependencies. See saved asset editing for Aseprite/PNG presentations, shared owners and interrupted application.