Uttori View on GitHub Install Uttori ASM
Topics

UTTORI ASM ยท IN DEVELOPMENT

Git source projects in VS Code

Edit source and research, preview regeneration and integrate evidence with the native Git merge editor.

On this page

In a trusted local workspace, run Assembly: Create Git Source Project (asm.source.init) or Assembly Source: Create Git Source Project from Diz Research (asm.source.initDiz). Select an original ROM and a new output folder. Creation checks mapper/header identity, stores private inputs in ignored .uttori-local/, analyzes evidence and verifies an initial pure generation before adopting it. Uncompressed .dizraw choices become tracked research; compressed .diz is unsupported.

Project layout

New projects place main.asm, mapper banks, raw assets, RAM/structure maps and assembler configuration under source/. .uttori/project.json selects source/research roots, layout, build configuration and capture catalog. .uttori/generation.json identifies the accepted generation. .uttori/generation-inputs.json declares recipes and immutable original assets. .uttori/research/ contains human decisions with original ROM coordinates and IDs. .uttori-local/project.json binds the private ROM and evidence directory. Builds and editor state stay local.

Select the working checkout with Assembly: Select Source Project (asm.source.select). A linked worktree or clone needs its own valid local binding. The selected binding takes precedence over copied analysis-project settings; a broken binding reports an error rather than selecting an unrelated database.

Update source from evidence

The Source Project tree shows Next and an ordered update flow:

  1. Import a capture with Import Capture into Source Project, or save research changes.
  2. Analyze Source Project Evidence synchronizes research and runs conservative analysis.
  3. Prepare Regeneration creates a verified immutable candidate.
  4. Preview Regeneration with Current Edits includes supported unsaved text and native binary edits without changing saved source or staging.
  5. Save files and commit the reviewed checkpoint in Source Control, then Apply Previewed Generation.
  6. Resolve conflicts in the native Merge Editor and stage the intended result.
  7. Validate and Finish Regeneration builds and validates that result before committing the merge.

If retained captures are absent from the tracked catalog, Next offers Refresh Capture Catalog first. This records identities without reimporting or regenerating. Reloading with a pending candidate requires a fresh preview before Apply. Finish clears completed candidate state. Use Abort Regeneration, Discard Generated Candidate or Clean Abandoned Source Temporary Data for the corresponding recovery action.

Build and run current edits

Build Current Source requires saved inputs and no Git commit. It does not incorporate new evidence. If an input changes during the build, the diagnostic names the file and offers Save All and Rebuild. Build & Run, Build & Debug and Watch use the selected source project and its matching ROM/debug-map receipt. A failed build cancels a new launch and preserves an existing running session during watch.

For F5, set "sourceProject": true in an uttori-asm launch configuration with the selected backend/runtime. The extension builds the selected source project and supplies the verified artifact pair. Fixed program and debugMap paths are unnecessary for this mode.

Research and assets

Assembly, maps and assets are ordinary editable files. F2 updates supported symbol uses together with tracked research identity. Edit Symbol Research and Edit Analysis Research open normal JSON files with native Undo, Save and Git diffs. Research addresses keep their original ROM identity through relocation. Edit RAM/structure maps directly and include them in the next generation recipe/merge when their rendered definitions change.

Indexed PNG and palette editors share VS Code's save/undo/recovery lifecycle. Supported unsaved drafts participate in preview; Apply requires a saved committed checkpoint. Opaque drafts from unsupported custom editors block a source operation rather than silently using stale saved bytes. See saved asset editing for external Aseprite/PNG editing and SNES source export for maps and generation inputs.