Vania Forge

Quick start

1. Start the app with npm run dev, or open the deployed site.
2. Click Open ROM and choose a compatible .smc, .sfc, .rom, or .bin file.
3. Select a stage from the level tabs: Levels 1–6 or Dracula.
4. Use the GROUPS or TILES browser in the left sidebar.
5. Edit the layout, groups, tile pixels, or palettes.
6. Use Export ROM for an edited ROM copy or Export Source for a portable ZIP.

Interface overview

Levels and layout editing

Each stage is represented as vertical strips. A strip contains six stacked 32×32-pixel tile groups. A group is a 4×4 arrangement of 8×8 tiles.

Select a placed group

Right-click a group on the center canvas. The group is selected in the inspector and group browser.

Replace a placed group

1. Select a group in the group browser.
2. Left-click a group position on the level canvas.
3. That position changes to the selected group.

Layout changes are history edits and can be undone. Use the canvas footer as a reminder of the active mouse interactions.

Tile groups

A tile group is a reusable 4×4 arrangement containing 16 tile IDs and four 2×2-quadrant palette assignments.

Group browser

Groups are labeled in hexadecimal, such as G00, G04, or G7F. Click a card to select it. When a tile is selected, every group containing that tile gets a subtle accent border; this includes groups not currently visible on the map.

Group editor

Click EDIT beside the group preview to open the larger group editor below the canvas.

• Left-click a cell to place the selected tile.
• Right-click a cell to select its existing tile.
• Click BACK TO LEVEL to close the editor.

Quadrant palettes

The four selectors—TOP LEFT, TOP RIGHT, BOTTOM LEFT, and BOTTOM RIGHT—choose P0 through P3 for each 2×2 quadrant.

Tiles

Tile IDs are shown in hexadecimal. Each tile is an 8×8 image with 64 indexed pixels and standard SNES 4bpp planar storage.

Tile browser

Click TILES, then click a tile card to select it. Local tiles are editable. Shared tiles are marked SHARED, can be used in groups, and are read-only.

SOLID BLOCKS · T60–T67
T60  T61  T62  T63  T64  T65  T66  T67
OTHER TILES

The separators are based on tile IDs and do not indicate whether a tile is currently used on the map.

Solid blocks

Tile IDs 0x60 through 0x67, displayed as T60 through T67, are treated as solid-block tiles.

Map highlighting

1. Enable HIGHLIGHT SOLID BLOCKS in the canvas toolbar.
2. Each placed group is examined tile by tile.
3. Only the individual 8×8 cells containing T60–T67 receive a translucent fill and thin gold outline.

The surrounding 32×32 group border is not changed by this option. The selected group retains its stronger selection border.

Painting tile pixels

The selected-tile inspector contains an enlarged 8×8 pixel editor.

• Left-click a pixel to paint it.
• Hold the button and move to paint a stroke.
• Right-click a pixel to pick its color index.
• The active palette and selected color determine the paint color.
• Shared tiles cannot be painted.

Tile copy and paste

The tile inspector has a session-local clipboard for copying one tile’s indexed pixels to another tile.

1. Select the source, for example T67.
2. Click COPY T67.
3. Select the destination, for example T04.
4. Click PASTE TO T04.

• The clipboard stores an independent snapshot of all 64 pixel indexes.
• Tiles can be copied from local or shared tiles.
• Pasting is allowed only into editable local tiles.
• Paste is disabled when the destination already matches the copied pixels.
• Paste is one undoable project edit.
• This is an editor clipboard, not the operating system clipboard.

Palettes

Each stage has four palettes, P0 through P3, with 16 colors each. Colors use native SNES BGR555 words.

Edit a color

1. Click a palette row or swatch.
2. Use the browser color picker.
3. RGB channels are quantized to five bits.
4. The palette and paint indicators update immediately.

Changing a palette color changes every pixel using that palette/color index. Changing a group quadrant assignment changes which palette a region uses.

Undo, redo, and timing

Layout changes, group edits, palette changes, tile pastes, and committed paint strokes participate in history. A new edit after undo clears the redo branch.

ROM export

Export ROM downloads a patched copy with a name such as:

castle.sfc → castle.edited.sfc

Pending paint changes are included. Metadata-defined palette, layout, and group ranges are written back. Configured local tile ranges are written as SNES 4bpp tiles; shared data is not overwritten.

Source ZIP export

Export Source downloads a package named like castle.source.zip. It contains level data, selected graphics banks, and manifest.json.

manifest.json
level-1/palette.bin       level-1/level-layout.bin       level-1/tile-groups.bin
level-2/palette.bin       level-2/level-layout.bin       level-2/tile-groups.bin
level-3/palette.bin       level-3/level-layout.bin       level-3/tile-groups.bin
level-4/palette.bin       level-4/level-layout.bin       level-4/tile-groups.bin
level-5/palette.bin       level-5/level-layout.bin       level-5/tile-groups.bin
level-6/palette.bin       level-6/level-layout.bin       level-6/tile-groups.bin
dracula/palette.bin       dracula/level-layout.bin       dracula/tile-groups.bin
16bit-tiles/tiles-16bit-0.bin
16bit-tiles/tiles-16bit-1.bin
16bit-tiles/tiles-16bit-2.bin
16bit-tiles/tiles-16bit-3.bin
16bit-tiles/tiles-16bit-6.bin

Local edited graphics are overlaid into the appropriate bank before extraction. Importing a source package is not currently implemented.

Binary format reference

Palette

Layout

Tile groups

16-bit tile banks

Each bank is 0x8000 bytes and contains 1024 32-byte SNES 4bpp tiles.

ROM metadata and addressing

The authoritative metadata table begins at raw file offset 0x100000. It has seven records of five 3-byte little-endian addresses:

1. Palette start
2. Layout start
3. Layout end
4. Tile-group start
5. Tile-group end

Layout and group ends are exclusive. Palette ranges are 128 bytes. Metadata-defined layout data has no terminator.

The normal load path uses literal file offsets and detects a 512-byte copier header when the ROM size indicates one. Explicit LoROM conversion support is retained in the adapter for format-specific use.

Common use cases

Rearrange a level section

1. Open a ROM and choose a stage.
2. Select a group.
3. Left-click map positions to replace them.
4. Export and test the edited ROM.

Find all groups containing a tile

1. Select a tile.
2. Open the group browser.
3. Look for the subtle highlighted group cards.

Copy one tile to another

1. Select the source and click COPY.
2. Select an editable destination and click PASTE.
3. Undo if needed.

Inspect solid tiles

1. Enable HIGHLIGHT SOLID BLOCKS.
2. Inspect the individual highlighted T60–T67 cells.
3. Select a solid tile to find every group containing it.

Share edited source data

1. Finish or flush active painting.
2. Export the source ZIP.
3. Send the ZIP and its manifest to the collaborator or external tool.

Troubleshooting

Export buttons are disabled

Load a ROM first. Preview mode intentionally disables export.

The ROM will not load

Confirm that it is the expected Castlevania SNES ROM, is not truncated, and matches the adapter’s header/address assumptions.

A tile cannot be painted

Shared tiles are read-only. Choose a local tile. Shared tiles can still be copied and placed in groups.

Paste is disabled

Copy a source tile, select an editable destination, and ensure the destination differs from the copied pixels.

Painting is marked pending

Wait two seconds, select another asset, use a command, or export to commit the stroke.

The source ZIP has no per-level tile files

This is intentional. The package exports the selected complete 16-bit banks instead of local tile files per level.

Current limitations

• Source ZIP packages can be exported but not imported.
• The UI supports Levels 1–6 and Dracula.
• ROM-format configuration is not exposed through the UI.
• Shared graphics are read-only and preserved during source extraction.
• Tile copy/paste uses an in-editor session clipboard.
• The editor does not launch an emulator or provide an in-app test runner.

Development commands

npm install
npm run dev       # Start the Vite development server
npm test          # Run tests
npm run build     # Type-check, bundle, and copy public files to dist

The manual is available at public/documentation.html during development and is copied to dist/documentation.html by the production build. With the configured deployment base it is available at /vania-forge/documentation.html.