goon-game/README.md

Project Sacrifice — Android vertical slice

An original landscape puzzle-platformer prototype inspired by the broad “death changes the puzzle” genre formula. It does not reuse the title, art, audio, text, characters, or level layouts of any commercial game.

Project documents:

• docs/DEVELOPMENT_PLAN.md — approved GDD + TDD + production roadmap;
• docs/CURRENT_ROADMAP.md — execution roadmap for the existing vertical slice;
• docs/LEVEL_SOLUTION_GRAPHS.md — source-backed intended solution graph for every current level;
• docs/STAGE4_CONTENT_FORMAT.md — versioned JSON contract, validator, preview, and bot-trace format;
• docs/STAGE5_ART_BIBLE.md — original visual language and articulated volunteer contract;
• docs/STAGE5_PERFORMANCE_BUDGETS.md — physics, replay, frame, memory, and complexity ceilings;
• docs/STAGE5_QA_REPORT.md — exact Vertical Slice candidate evidence;
• docs/STAGE5_HUMAN_PLAYTEST.md — required external acceptance protocol;
• docs/STAGE_REGISTRY.md — mandatory Stage 0–10 ownership for every Bead;
• docs/BEADS_WORKFLOW.md — local backlog structure and daily Beads commands.

Playable content

The APK contains ten sequential levels:

1. movement and jumping;
2. bodies covering a spike lane;
3. a corpse holding a pressure plate and door;
4. a toggle-controlled moving lift;
5. a saw launching a corpse onto a remote plate;
6. a frozen corpse becoming a stable step;
7. an electrified corpse completing a relay;
8. a timed switch and moving platform;
9. a two-signal door requiring weight and electricity;
10. a mastery level combining saw, freeze, electricity, pressure plate, pit, moving lift, and final gate.

Death does not reset the level. A new volunteer respawns after a short delay while retained bodies stay in the simulation. The restart button deliberately clears the puzzle state. Progress, best time, and lowest volunteer count are stored locally.

Controls

• Hold the left/right arrows to move.
• Hold a direction and tap jump simultaneously; multitouch is supported.
• Restart restores the current level.
• II pauses the game and exposes level selection.
• Settings on the level-select screen cycles three control sizes, three opacity presets, vibration on/off, Standard/Large text, high contrast, and English/Russian, reduced motion, and independent Music/Effects/Voice volumes. Changes persist across app restarts without resetting progress.

The first level includes a three-step, non-blocking tutorial for movement, multitouch jumping, and using retained bodies. Completion shows the current run, saved best, targets, a next goal, and Level select/Replay/Next level routes. Critical signal, door, and respawn state remains visible when vibration is disabled.

The movement constants include 130 ms coyote time and 140 ms input buffering.

Build

Requirements: JDK 17 and Android SDK Platform/Build Tools 34.

./gradlew testDebugUnitTest assembleDebug

Level content is stored in level-format/src/main/resources/levels. Android and the desktop tools use the same dependency-free parser and validator. Android packaging automatically depends on validation. To validate explicitly or export deterministic SVG/TSV previews:

./gradlew :level-format:validateLevels
./gradlew :level-format:previewLevels

Previews are written to level-format/build/level-previews. Invalid geometry, versions, moving-platform destinations, switch parameters, or signal references fail the build with a JSON path diagnostic.

All ten levels have device-level acceptance bots. They drive the production GameView through the same movement and jump inputs as the touch controls and run each intended solution three times. Level 8 also has a dedicated recovery scenario for an expired timer on the far side of the pit. Stage 2 additionally checks clean restart and long-term stability of the saw-delivered body on the level 10 lift plate. The final Stage 2 build passed all 16 instrumentation methods (36 gameplay executions plus lifecycle and restart) on Android 16 in a single unfiltered run. With an emulator or phone connected, run the complete matrix with:

./gradlew connectedDebugAndroidTest

The Stage 3 device suite additionally checks persisted controls, RU/EN copy, accessibility presets, tutorial/result navigation, Back behavior, and safe viewports on 20:9, 16:9, and 16:10 tablet-sized displays.

Stage 4 keeps the same gameplay and UI matrix after migrating all ten levels to JSON. Its final unfiltered Android 16 run passed all 30 instrumentation methods in one process (OK (30 tests), 1,096.448 seconds). Acceptance bots now attach a versioned deterministic input/checkpoint trace and SHA-256 trace ID to their result diagnostics.

Stage 5 replaces the prototype knight with an original articulated clockwork volunteer rig and three data-driven skins, adds procedural audio, camera focus and shake with reduced motion, save version 2 and active-session restoration. Its exact Android 16 candidate passed all 35 instrumentation methods in one unfiltered run (493.521 s) plus 72 JVM tests. Deterministic tapes replay all ten levels three times with identical state signatures. The product owner confirmed completion of external testing on 19 August 2026; the evidence boundary is recorded without invented session data in docs/STAGE5_HUMAN_PLAYTEST_RESULT.md. Stage 5 is accepted.

The debug APK is written to app/build/outputs/apk/debug/app-debug.apk. It is signed with Android's standard debug key and can be installed with:

adb install -r app/build/outputs/apk/debug/app-debug.apk

Scope

This is a dependency-free vertical slice rendered through a custom Android Canvas view. It is intended for gameplay evaluation on phones and tablets, not as a content-complete commercial release.