Xevious

An unfinished 2017 Scratch interpretation of Namco's arcade game Xevious, being restored through reviewable, reproducible changes.

Original public project: https://scratch.mit.edu/projects/195680409/

Current controls

• Green flag: load the title screen
• Space: start from title; fire the blaster while playing
• Arrow keys: move the Solvalou while playing
• B: drop a bomb while playing
• D: run the temporary death-and-respawn fixture
• G: run the temporary terminal-death and game-over fixture

READY, death, respawn, and GAME OVER suppress gameplay input. Green flag can be pressed from any state to perform the same cold reset and return to title.

The current project is a proof of concept. It has scrolling terrain, movement, weapons, music, a death animation, and restart behavior, but no enemies, scoring, lives, or progression yet. The arcade game has no conventional win screen: after area 16, play returns to area 7.

The dependency-ordered restoration work is defined in the end-to-end build plan, with individual behaviors tracked in the mechanics catalog. Gameplay-ready Solvalou and Toroid costumes are generated by the first sprite extraction proof.

Repository layout

• assets/original/Xevious.sb3 — immutable historical archive and baseline asset store
• src/xevious/project.json — canonical, order-preserving Scratch structure
• src/xevious/assets/ — only new or modified asset overlays, each with provenance
• docs/ASSET_CREDITS.md — sources, credits, and license status for imported third-party media
• docs/BUILD_PLAN.md — ordered implementation slices and acceptance gates
• docs/MECHANICS_CATALOG.md — normal-game mechanic inventory and source locators
• docs/SPRITE_EXTRACTION.md — deterministic sprite-derivative design
• assets/sprite-extraction/ — versioned crop manifest, schema, and generated source-to-derivative provenance
• dist/Xevious.sb3 — generated playable build; ignored by Git
• tools/scratch_project.py — import, build, validation, and reproducibility boundary
• tools/game_director.py — deterministic slice-2 state/reset block generator and drift check
• tools/sprite_extractor.py — deterministic sprite extraction and generated output check
• harness/ — headless scratch-vm runtime regression net; a pre-playtest tripwire with its own pinned Node/JS toolchain (not a gameplay gate)

Build and validate

Python 3.12 is used in CI and no third-party Python packages are required.

python3 tools/sprite_extractor.py check
python3 tools/game_director.py check
python3 tools/scratch_project.py verify
python3 tools/scratch_project.py build

The build uses stored ZIP entries with fixed metadata, so identical source produces identical output across supported systems.

The runtime harness under harness/ is a separate Node/JavaScript toolchain — its one dependency is a pinned scratch-vm with a committed lockfile. It builds the .sb3 and runs headless scenarios (and their negative fixtures) against the game's logic layer:

harness/run.sh   # or: cd harness && npm ci --ignore-scripts && node --test

It is a pre-playtest regression tripwire that observes internal state only, never the game on screen — not a gameplay gate. See harness/README.md.

When the sprite manifest changes, regenerate its costumes, provenance, Scratch costume records, and review contact sheet, then run both checks:

python3 tools/sprite_extractor.py generate
python3 tools/sprite_extractor.py check
python3 tools/scratch_project.py verify

Bring visual-editor changes back into Git

Always start the editor from the current generated build, not the historical archive or public Scratch project:

1. Confirm src/xevious/ has no uncommitted work.
2. Run python3 tools/scratch_project.py build.
3. Load dist/Xevious.sb3 in Scratch 3 or TurboWarp.
4. Edit, then export a new .sb3.
5. Import that export through the guarded boundary.
6. Add or update its mechanics record.
7. Run python3 tools/scratch_project.py verify and review the Git diff.

python3 tools/scratch_project.py import path/to/edited.sb3 --force

--force authorizes replacing the existing canonical source, but the importer still refuses when src/xevious/ has visible uncommitted work. Commit or stash first. Every successful replacement also retains the complete prior source tree under ignored dist/import-backups/ and prints its path, covering local files Git may not report.

For slice 2, tools/game_director.py is the exclusive source of truth for the block maps of Stage, Solvalou, blaster, bomb, both terrain sprites, both target sprites, the title sprite, and the death sprite. After importing an editor export, commit the recoverable import before doing anything else, inspect its diff, and port intended block changes for those targets into the generator. generate refuses to run while src/xevious/project.json has staged or unstaged edits, so it cannot silently erase a fresh editor import. Costumes, sounds, target properties, and blocks on other sprites remain editor-owned.

If the export adds or changes media, also provide its origin and license:

python3 tools/scratch_project.py import path/to/edited.sb3 --force \
  --asset-origin "Created for this project" \
  --asset-license "CC0-1.0"

That shorthand applies one origin and license to every new media file. For mixed sources or licenses, pass --asset-provenance path/to/provenance.json instead. The file uses the same version 1 shape as src/xevious/assets/provenance.json, with one origin and license record for each asset filename the import reports.

The importer accepts PNG, WAV, MP3, and sanitized SVG media. SVG scripts, event handlers, embedded content, and external references are rejected.

Importing preserves the relative order of existing block-map entries because Scratch uses that order when scheduling top-level scripts. New blocks are appended in the editor's order.

Any change to src/xevious/project.json must also add or update a structured record under docs/mechanics/. The required project check enforces that the mechanic, provenance, implementation evidence, and attestations are present. Copy the mechanics record template, then check it locally:

python3 tools/check_mechanics_record.py origin/main

Runtime comparison

For the current game-director slice, load the rebuilt archive in Scratch 3 and check:

1. Green flag shows the title.
2. Space shows READY for one second, then music and terrain scrolling begin.
3. Arrow keys, Space firing, and B bombing work only while playing.
4. D plays one death animation, shows respawn READY, preserves terrain position, and resumes once.
5. G plays one death animation, holds GAME OVER for two seconds over the final terrain, then returns to a freshly rewound title state.
6. Inputs during title, READY, death, respawn, and GAME OVER do nothing.
7. Repeated controls do not duplicate music, terrain loops, transitions, shots, or bombs.
8. Green flag from each state returns to the identical title; Stop halts all activity.

Record the tested commit, archive SHA-256 values, date, runtime versions or dated web URLs, and each result in the pull request.

Arcade reference boundary

The restoration targets normal Namco arcade behavior. The pinned public jotd666/xevious source snapshot may provide mechanics, constants, timing, scores, formations, schedules, collision rules, and tables with exact commit/file/label provenance. Scratch code is independently expressed; arcade ROM files are not acquired, opened, extracted, or distributed. Separately supplied third-party media requires per-file provenance and honest license status. See the reference policy and asset credits.