AFTERIMAGES: VRANOV

A psychological action thriller about a mind you cannot trust — including yours.

Top-down 2D action thriller (Godot 4.3). You are an undercover officer inside a criminal intelligence firm in Vranov, 2004. The engine simulates the true world on one layer and renders only what your character believes on another — and after every mission, a replay theater shows you both, side by side.

Title note: the game is titled Afterimages: Vranov (the plural + place-name resolves the working title's collision with an unrelated, already-released 2023 metroidvania called Afterimage, flagged as a risk in master_plan.md §12). The in-fiction replay mechanic keeps its original singular name, the Afterimage — see master_plan.md §4.12/§4.19.

Status: in development, and playable — there is a real, runnable graybox slice (scenes/main.tscn) driven end to end by the actual systems, not a mockup: you walk a room simulated by the deterministic TruthSim, the renderer shows you only the percept layer, a real DistortionDirector buys distortions out of real mission content against a real budget, the Ground verb resolves them, and reaching the exit opens the Afterimage — a disclosure panel backed by a genuine re-simulation of your own recorded session. See Playing it below.

Planning is complete and ratified (docs below); the 20-pass engineering arc is complete (docs/dev_log.md for pass-by-pass progress, docs/roadmap.md for the milestone backlog), and post-arc work has since closed most of the review's blank-spot findings and delivered Phases A–B of docs/forward_dev_plan.md: all eleven DistortionOp classes, the OpFactory content bridge, MissionRuntime, and the wiring that makes the playable slice run on real content instead of hardcoded script. 609 tests, all green in CI, plus lint/format/architecture-boundary/content-schema/dialogue-compile gates on every push. What remains is real production — art, audio, mission content, playtesting — plus the remaining Phases C–G. Nothing is decided on the go: every system is built to the locked specs in the document set.

Playing it

Locally (needs Godot 4.3.x — docs/ENGINE_VERSION pins the exact build):

godot --headless --path . --editor --quit   # one-time on a fresh clone: builds the class cache
godot --path .                              # or: open in the editor and press F5

(The first line is the same one-time import pass the test suite needs — .godot/ is gitignored, so class_name types aren't resolvable until something triggers that scan.)

Controls: WASD/arrows move · Shift sprint · hold Space to Ground · Enter to replay after the reveal.

What to actually do: walk toward the teal door at the bottom-right — that's the exit, and reaching it ends the run. Take your time getting there. While you walk, the Distortion Director is spending budget on ops drawn from content/missions/m00_stub/mission.json; when something is active, the HUD says "reality feels off right now" (that's Clarity Mode, Fairness Charter rule 6 — flagging that you're being lied to, never what the lie is). Holding Space runs the reality test: the screen brightens as the hold charges, and on completion every active distortion resolves to the truth at once. Grounding costs you nothing here yet, so try both — ground the moment you feel wrong, or refuse to and see what you were carrying. Either way the Afterimage discloses all of it at the exit, because the Charter says everything is disclosable. Restart a few times: the deck draws differently each run.

In a browser: it's live at https://danieldmas.github.io/Afterimage/ — every merge to main rebuilds and redeploys it automatically (.github/workflows/export-web.yml). Every push (any branch) also uploads the build as a downloadable afterimage-web-build workflow artifact; if you grab that to run it yourself, serve the folder over HTTP (python3 -m http.server from inside it) — opening index.html from file:// won't work, browsers block the WASM fetch. (The deploy step only runs on main; the live site is verified to boot, load its mission content, purchase a distortion, and resolve it on Ground — see docs/dev_log.md's post-release entry.)

Caveat, stated honestly: this is a graybox slice — colored rectangles, no art, no audio, one room. Only two of the eleven distortion classes can actually reach your senses here: SubtitleDrift (the line at the bottom of the screen) and PhantomEntity (the figure that shouldn't be there). AudioSwap and PhantomAudio are real and really purchased, but there's no audio system yet to hear them through. The remaining seven operate on truth-layer concepts this room doesn't have — HUD elements, props, geometry, journal entries, jump-cuts, or other actors to mask and mis-face. Every one of them is still disclosed by name in the Afterimage when the Director buys it, rather than quietly omitted: Fairness Charter rule 5 has no exception for "the demo can't render this one yet." The thesis is playable; the game is not built.

Running the tests

This is a Godot 4.3.x project (docs/ENGINE_VERSION pins the exact build). On a fresh clone, run an import pass once first — .godot/ (the class-name cache Godot builds by scanning the project) is gitignored, so class_name types like AfterimageTestRunner aren't resolvable until something triggers that scan:

godot --headless --path . --editor --quit   # one-time: builds the class cache
godot --headless --path . --script res://tests/run_tests.gd

(Opening the project in the editor UI at least once does the same thing — the explicit command above is just the headless/CI equivalent.) Exit code 0 from the second command = all tests passed. CI (.github/workflows/ci.yml) runs both steps on every push, plus gdlint/gdformat --check for style. See docs/tech_guidelines.md §9 and §12 for why this project uses a small custom GDScript test harness (tests/framework/) instead of GUT for now.

The document set

Document	What it governs
docs/master_plan.md	The master development plan: design pillars, story bible, all systems (distortions, mind model, combat, debrief), architecture, milestones M0–M7, testing, risks
docs/tech_guidelines.md	Locked technology decisions — engine pinning, determinism contract, data formats, audio/input/UI tech, CI, performance budgets. Change-controlled
docs/foundation_blueprints.md	Full specification of the foundation layer: EventBus, GameStateStore, predicate language, dialogue DSL, NPC minds, claims/provenance, validators & bots
docs/art_direction.md	The beauty bible: sodium light and carbon paper — palette, lighting, pixel-art specs, distortion VFX grammar, typography, motion
docs/ux_charter.md	Player-experience standards: onboarding contract, respect-for-time rules, quality-of-life inventory, testable enjoyability metrics
docs/story_bible.md	Spoiler-complete narrative canon: fixed timeline (1993–2004), character voice sheets, gazetteer, ground-truth outlines for prologue + slice missions
docs/roadmap.md	The development backlog: milestone work items with acceptance criteria, and the definition-of-ready-to-code checklist
docs/dev_log.md	Pass-by-pass engineering log: what was built, how it was verified, what's deferred
docs/review_and_forward_plan.md	Post-arc code review: the F1–F13 blank-spot findings (most now closed) between individually-green systems
docs/forward_dev_plan.md	The living forward plan (v2): the north-star playable-loop goal and the in-sandbox-buildable phases (A–G) toward it, with an explicit blocked-list

Reading order for a newcomer: this README → master_plan.md §0–§3 → ux_charter.md → the rest as needed. For "what's next," read forward_dev_plan.md. (story_bible.md spoils the entire game — read deliberately.)

Ground rules (from the plans, binding)

1. Determinism is law — the truth simulation replays tick-perfect, always (it's the save format, the bug report, and the Afterimage Theater).
2. Fairness is auditable — the distortion system obeys a hard charter, enforced by tooling, and every lie is disclosed after the run.
3. Missions must be fun sober — with distortions off, or they're rejected.
4. Content is data — no mission logic in engine code.
5. Cruel game, kind product — all friction is authored; none is accidental.

Current progress

All 20 passes of the planned engineering effort are complete: the repo scaffold, the deterministic core (FixedMath, Xoshiro128StarStar PRNG, EventBus, the Predicate language + WorldQuery), GameStateStore/SaveSystem with a real schema migration, the fixed-tick harness (InputFrame/ReplayLog/FixedTickClock), a determinism-corpus mechanism, TruthSim — entity-ID'd actors, a sparse collision grid, swept circle-vs-AABB collision, Bresenham line-of-sight, room/portal sound propagation, angular vision cones, utility-scored Sentry/Professional AI, a WitnessSystem, combat verbs v1 (movement modes, a weapon/ammo state machine, fire/takedown/throw resolution, a Focus resource gate, a lean/peek offset, InputMap actions), Pass 7's wiring (AI actors that perceive and fight back for real, a code-defined graybox room, a bot harness soak-testing a full deterministic encounter), Pass 8's percept/truth split (a read-only snapshot export from TruthSim, a PerceptOp/PerceptRenderer decorator pipeline, a CI-enforced static lint proving nothing under src/percept/ can reference a truth-layer class by name), Pass 9's first four DistortionOp classes (SubtitleDrift, AudioSwap, PhantomAudio, PhantomEntity), Pass 10's Ground verb and Clarity Mode stub, Pass 11's four-variable Mind Model (AcuteStressState, FatigueState, MoralInjuryState, IdentityStrainState composed by MindModel), Pass 12's DistortionDirector and FairnessAuditor v1 (all 8 Fairness Charter rules, each with its own failing fixture), Pass 13's content pipeline (a versioned JSON Schema, a dependency-free tools/content_validator.py, and a MissionLoader/MissionPackage that loads real mission JSON straight into DistortionDirector), Pass 14's Replay Theater v0 data model (ReplayTheater/OpTimelineSpan), Pass 15's Dialogue DSL pipeline (tools/dlgc.py compiler, a real compiled prologue Sova scene, and a new src/dialogue/ runtime with symmetric interrupt-memory contradiction detection), Pass 16's Argus social graph data spine (NPC/SuspicionLedger/SuspicionGraph/GossipSim in a new src/social/), Pass 17's Claims/Provenance and DebriefLedger (a new src/debrief/ directory, a liar-bot smoke test), Pass 18's Safehouse Hub skeleton (HubCalendar/MindDashboard/Loadout in a new src/hub/), Pass 19's UI shell data layer (ThemePalette/MotionConstants/AccessibilitySettings/ScreenSpec in a new src/ui/, deliberately not a hand-authored .tscn/.tres file), and — as of Pass 20 — the integration capstone: src/integration/prologue_stub.gd plays a full scripted scenario end to end (a Ground tutorial, one real scripted SubtitleDrift against actual dialogue-shaped data, a mini-Theater reconstruction, and a trivial debrief submission that comes back false even though the player told the truth as they believed it) — tying together nearly every system the previous 19 passes built (all verified against Python references, hand-traced tick-by-tick, or a deliberately-reintroduced violation before porting/committing). Post-arc work (each entry in docs/dev_log.md has the full account, including the wrong turns): an independent bug audit and the §4.4.5 substance model (src/sim/substance_model.gd); the first playable scene and a real Web export pipeline; a full code review whose F1–F13 blank-spot findings are recorded in docs/review_and_forward_plan.md and mostly now closed — OpFactory (F1) so real mission content builds real ops and the fairness auditor finally runs against committed content (which immediately caught two real, previously-invisible Charter-tag bugs), the determinism corpus re-pointed off its Pass 2 stub onto real TruthSim (F9), and GroundObservationBridge (F5) connecting Ground-observed → suspicion ledger → gossip for the first time; then Phase A of the forward plan — the remaining seven DistortionOp classes, making Charter rules 2 and 4 structurally enforceable instead of merely declared; a player-experience pass over the demo (a second distortion, a chosen exit, onboarding, Ground feedback, a restart loop); and Phase B — MissionRuntime + MindModelEventBridge, retiring the hand-scripted encounters so the playable slice runs on the real content pipeline. 609 tests, all green in CI, clean against every lint/format/boundary/schema gate. Full detail in docs/dev_log.md; what's next is docs/forward_dev_plan.md (Phases C–G) and the live backlog is docs/roadmap.md.