This plan divides BulletHeaven development into capability tiers. Each tier ends in a playable or objectively verifiable milestone and builds only on systems proven in earlier tiers. Tiers describe dependency order rather than calendar estimates.
The project currently contains an empty Java 22 Maven placeholder and no implementation code. Tier 0 replaces that placeholder with the committed libGDX Gradle-wrapper structure defined in TECHNICAL.md.
- Prove that aiming, strafing, and shooting feel good before producing content.
- Prove that the entity component system can sustain the intended entity counts before relying on it for game design.
- Build every major mechanic first in a minimal playable form, then deepen content.
- Preserve visual clarity and stable performance as entity counts increase.
- Keep data and behavior composable so enemies, upgrades, drops, and environments can interact without extensive special cases.
- End every tier with a runnable build and documented acceptance results.
Create a reproducible Java application with the minimum technical structure required for rapid gameplay iteration.
- Select and document the windowing, rendering, input, audio, and testing libraries.
- Confirm Java 22 as the desktop development requirement and migrate the placeholder Maven build to the committed Gradle-wrapper structure.
- Establish the application lifecycle, game loop, fixed simulation step, and interpolated rendering.
- Create a resizable game window with resolution-independent coordinates.
- Add keyboard, mouse, and gamepad input abstractions.
- Establish deterministic random-number streams for repeatable simulations.
- Add logging, configuration, automated tests, and a development diagnostics overlay.
- Define package boundaries for the simulation, ECS, rendering, input, content, and application shell.
- Establish automated build and test commands suitable for continuous integration.
A runnable empty arena that displays frame time, simulation time, entity count, and active input devices.
- A clean checkout builds, tests, and runs through the checked-in Gradle wrapper using documented commands.
- The simulation rate remains stable when rendering rate changes.
- Keyboard/mouse and a gamepad can produce the same abstract movement and aim actions.
- Automated tests run without opening a visible window.
Implementation status: Combat sandbox implemented; automated verification and structured control/readability playtesting remain milestone gates.
Validate the defining player controls and vector presentation before committing to broader architecture or content.
- Implement independent movement and aim directions.
- Allow the player to turn, aim the firing angle, fire continuously, and strafe.
- Support equivalent mouse/keyboard and twin-stick gamepad controls.
- Implement basic projectiles, collision, damage, health, death, and arena boundaries.
- Add one simple pursuing enemy based on the Mote.
- Render geometric shapes, glow, trails, impact flashes, and readable friendly/hostile colors.
- Add camera behavior and limited, configurable screen shake.
- Tune acceleration, deceleration, rotation, strafe speed, fire rate, projectile speed, and knockback.
- Create a small test arena and a repeatable combat sandbox.
A five-minute combat prototype in which the player can move, aim, strafe, shoot, defeat Motes, take damage, die, and restart immediately.
- Aiming never changes movement direction unless the chosen control scheme requests it.
- Strafing and turning remain responsive while firing.
- Targets, projectiles, impacts, and damage ownership remain readable under moderate load.
- Playtesting confirms that the core control scheme is enjoyable before upgrades are introduced.
Implementation status: ECS migration, deferred mutation, spatial partitioning, deterministic checks, population budgets, and the headless benchmark are implemented. The milestone remains open until the benchmark and playability checks pass on the reference machine.
Build and validate the entity component system that will support dynamic enemies, projectiles, familiars, pickups, and environments.
- Define entity identity, component storage, queries, systems, creation, and destruction.
- Represent position, velocity, mass, shape, health, damage, faction, lifetime, collision, rendering, and status through components.
- Use command buffers or equivalent deferred mutation so systems can safely create and remove entities.
- Add spatial partitioning for collision and neighborhood queries.
- Separate simulation state from rendering state.
- Define tags and shared components for anchoring, environmental resistance, ownership, copying, and eligibility for arena forces.
- Add object/entity pooling only where measurement shows a benefit.
- Build headless simulation benchmarks and deterministic replay tests.
- Add entity budgets and graceful degradation for particles and secondary effects.
A benchmark arena that produces large mixed populations of enemies, projectiles, particles, and pickups while exercising movement, collision, damage, spawning, and removal.
- The target entity count and frame-time budget are documented and met on the reference machine.
- Entity creation and destruction do not cause visible stalls during stress tests.
- A recorded input stream produces the same important simulation results across repeated runs.
- Systems can combine behavior through components without depending on concrete enemy classes.
- Motes: 2,500 active entities.
- Projectiles: 5,000 active entities.
- Cosmetic sparks: 3,000 active entities; excess effects degrade by being omitted.
- Representative benchmark load: 1,500 Motes, 3,000 projectiles, and 1,500 sparks.
- Simulation target: the 95th-percentile fixed-step time remains below 8.333 milliseconds, leaving half of a 60 Hz frame for rendering and platform work.
- Acceptance commands:
gradlew test,gradlew :core:tier2Benchmark, andgradlew lwjgl3:run(usegradlew.baton Windows).
On 2026-08-23, the representative 6,001-entity load completed with a 0.482 millisecond median and 0.641 millisecond 95th-percentile simulation step on the development machine using OpenJDK 22.0.2. The automated suite passed all 22 tests, including deterministic repeated simulation, spatial-grid behavior, and population-budget checks. The milestone still requires an interactive check that combat behavior and presentation remain correct after the migration.
Implementation status: Feature-complete and ready for acceptance playtesting. ECS-backed XP shards, attraction and consolidation, deterministic paused level-up choices, at least two upgrades per school, upgrade ranks, keyboard/gamepad choice input, progression HUD, rechargeable shields, pause/build summary, final-wave victory, defeat, and fresh-run restart are implemented. Automated tests and the ECS benchmark pass; a successful interactive two-minute run remains the final acceptance check.
Tier 3 intentionally uses Motes as its sole enemy type while the run loop is validated. At 01:30 ordinary spawning stops and a finite 40-Mote final wave begins; victory requires clearing it. The first additional enemy types begin in Tier 4.
Turn the combat prototype into a complete short run with progression, choices, victory, and defeat.
- Implement timed spawning, escalating waves, encounter completion, and run state.
- Add XP drops, shard collection, shard consolidation, levels, and upgrade choices.
- Implement health, shield, damage feedback, pause, restart, victory, and defeat flows.
- Add a run timer and basic difficulty curve.
- Implement a small first set of school upgrades:
- Mercury: Winged Sandals and Sidestep.
- Jupiter: Thunderbolt and Relentless Volley.
- Janus: Twin Shot and Echo Shot.
- Minerva: Aegis and Guardian Pulse.
- Diana: Hunting Hound and Marked Prey.
- Add upgrade ranks, prerequisites, and data-driven definitions.
- Add a minimal HUD for health, shield, XP, level, timer, and current upgrades.
- Record run statistics needed for balancing.
A two-minute run with escalating enemies, meaningful upgrade choices, a final wave, and explicit victory or defeat.
- Every school supports at least one recognizable early build direction.
- All offered upgrades apply correctly, stack predictably, and appear in the HUD.
- A complete run can be played repeatedly without restarting the application.
- XP collection and upgrade selection remain functional under stress-load entity counts.
Implementation status: Complete for the planned baseline. The CR 1–4 roster has distinct ECS-composed movement, telegraphs, silhouettes, and counterplay. Deterministic challenge-budget spawning introduces the CR 1–3 roster during the first arena and CR 4 elites in continued arenas. Bastions have breakable rotating armor, Architects build anchored barriers, Predators cloak and lunge, and Replicators create fragile archetype-preserving copies. Fortified, Massive, and Volatile modifiers add visible, budgeted elite variations. Gravity Spiral and Epoch Wave affect movable entities according to mass while respecting anchored entities. Authored Replicator-escalation and Warden–Sniper–Epoch-Wave encounters verify bounded growth and a viable survival route. Further roster entries remain content expansion rather than Tier 4 blockers.
Encounter CR now scales from player progression level and continued-arena level. Clearing an arena allows the player to preserve the build and advance into a harder, higher-reward arena or explicitly start fresh.
Prove that composable enemy behaviors and arena-wide effects create dynamic, readable encounters.
- Implement representative enemies from each ordinary challenge rating:
- CR 1: Mote, Dart, and Popper.
- CR 2: Rammer, Spinner, and Splitter.
- CR 3: Sniper, Warden, and Mine Layer.
- CR 4: Bastion, Architect, and Predator; Replicator next.
- Implement reusable behavior components for pursuit, charge, orbit, firing patterns, splitting, shielding, construction, and formation control.
- Extend spawn requests with source-archetype and maturation metadata before implementing Replicator copies; copies must begin fragile and stabilize without becoming generic Motes.
- Add spawn budgets based on challenge rating rather than enemy count alone.
- Implement elite modifiers using composable components.
- Implement Gravity Spiral and Epoch Wave as the first arena-wide effects.
- Apply environment forces consistently to the player, enemies, projectiles, familiars, pickups, and movable hazards.
- Add mass, resistance, and anchoring behavior.
- Create telegraphs, warnings, and diagnostics for enemy attacks and environment timing.
- Build authored encounter tests for individual enemies and dangerous combinations.
A rotating set of encounters featuring mixed enemy roles, elite variants, Gravity Spiral, and Epoch Wave.
- Each enemy is identifiable by silhouette, motion, and telegraph without explanatory text.
- Challenge-rating budgets create a measurable progression from simple to demanding encounters.
- Gravity Spiral produces controllable orbital motion rather than arbitrary displacement.
- Epoch Wave affects each eligible entity once per pass and can be deliberately used against enemies.
- No tested encounter combination removes all reasonable counterplay.
Implementation status: Complete for the vertical-slice breadth. Physical ability cores, source-weighted deterministic drops, elite weighting, eighteen-kill dry-streak protection, and a guaranteed apex reward are implemented. Collection immediately learns or ranks an ability without pausing; ranks stop at three and later duplicates convert to 100 XP. Gathering Mass, Vector Charge, Concussive Charge, Penetrating Line, Layered Armor, and Living Swarm cover CR 1–5; each uses shared combat state and has tested interactions with at least two schools. Allied entities are capped and time-limited.
Deliver the project's second progression axis: learning abilities from defeated enemies and combining them with the five schools.
- Implement ability-core drops, pickup presentation, immediate learning/improvement, ranks, maximum-rank conversion, and duplicate handling.
- Implement a representative ability from each challenge band.
- Guarantee an ability reward from apex encounters.
- Allow school upgrades to modify eligible captured abilities through shared components and tags.
- Add drop weighting, dry-streak protection, and run-safe random selection.
- Preserve visual ownership when abilities copy, reflect, split, replay, or summon entities.
- Add a build summary showing school upgrades, adaptations, ranks, triggers, and synergies.
- Add metrics for offered, accepted, replaced, ranked, and converted abilities.
A complete run in which enemy abilities can redirect a build and visibly combine with investments in multiple schools.
- Captured abilities visibly resemble their source enemies while remaining safe for player use.
- Every implemented ability interacts correctly with at least two relevant schools.
- A run remains viable if few ability cores drop.
- Rank limits prevent uncontrolled scaling without interrupting combat to resolve a pickup.
- Duplicated and summoned entities remain within performance and readability budgets.
Implementation status: In progress. The Swarm Heart is the first CR 5 apex encounter. It enters continued-run final waves from arena 3 onward, deploys breakable orbiting shield cells, produces fodder pressure, exposes its core when the ring breaks, later rebuilds a smaller ring, and guarantees Living Swarm. Its sandbox and glossary entries use the same runtime rendering logic. Every school now has at least three implemented upgrades; Minerva's Rapid Repair completes the initial breadth and requires Aegis. Gravity Spiral, Epoch Wave, Rotating Current, and Polarity Cycle provide four distinct ECS-driven arena effects, and the sandbox includes the explicitly supported Gravity Spiral + Epoch Wave combination. Current and polarity forces also deform the responsive grid. A context-sensitive first-run guide now teaches movement, independent aiming and fire, XP collection, and the first boon through demonstrated actions. Victory, pause, and defeat reports preserve school/adaptation summaries; defeat also reports arena, survival time, kills, level, and the reproducible run seed. The first audio slice routes semantic menu, combat, pickup, damage, death, and victory cues through a project-owned procedural audio bus with a generative arena bed. The Settings menu provides separate effects/music levels and mute; authored assets, state-reactive music, persistence, and the broader accessibility mixer remain pending.
Produce a polished, representative slice containing the complete intended experience at limited content breadth.
- Implement one cohesive arena theme with final-quality vector art direction.
- Implement at least three upgrades per school, including prerequisites and one advanced choice per school.
- Include enemies from CR 1 through CR 4 and a single CR 5 apex encounter.
- Include at least four arena effects, with one safe two-effect combination.
- Include a curated set of enemy ability drops covering offense, movement, defense, duplication, and allies.
- Add final-form menus, HUD, settings, control remapping, audio, music, and accessibility options for the slice.
- Add a guided first-run experience that teaches movement, independent aiming, strafing, XP, schools, and ability cores through play.
- Add seeded runs and a post-run report.
- Conduct structured playtests and balance passes.
A distributable vertical-slice build that demonstrates the game's combat, progression, ECS-driven interactions, art direction, and one complete boss encounter.
- New players can understand the controls and progression without external instructions.
- Players can describe meaningful differences between the five schools.
- Multiple viable builds can complete the slice.
- The full run meets the established frame-time target during its densest intended encounter.
- Critical bugs, unreadable effects, and run-blocking states have been resolved.
Expand the proven vertical slice into the full planned game and make every documented system available for testing.
- Implement the complete initial school-upgrade catalogue, including capstones.
- Implement the initial enemy roster across all five challenge ratings.
- Implement the documented enemy ability catalogue.
- Implement the planned arena-wide effects and supported combinations.
- Add additional arenas or arena phases using the same systemic rules.
- Complete difficulty progression, encounter scheduling, bosses, and run length.
- Add save data for settings, unlocks, records, and any approved persistent progression.
- Add content validation so malformed definitions fail early with actionable errors.
- Add automated simulations that detect impossible encounters, runaway entity production, and invalid upgrade combinations.
- Freeze major feature additions at the end of the tier.
A feature- and content-complete alpha build playable from beginning to end.
- Every item promised for the initial release exists in playable form.
- Every enemy, upgrade, ability, and environment effect has an isolated test scenario.
- All planned runs can reach a valid victory or defeat state.
- Save data survives upgrades and handles invalid or older data safely.
- No known issue prevents extended balance and usability testing.
Stabilize, balance, package, and release the game without expanding its feature set.
- Run broad playtests across hardware, control schemes, display sizes, and player skill levels.
- Balance enemy budgets, XP curves, school choices, ability drops, bosses, and environment intensity using collected data.
- Profile CPU, GPU, memory, garbage collection, loading, and startup behavior.
- Improve readability for color-vision differences, reduced motion, photosensitivity concerns, screen shake, and high visual density.
- Verify keyboard/mouse and gamepad navigation throughout every screen.
- Harden crash reporting, recovery, save migration, and safe defaults.
- Create platform packages and validate installation, launch, updates, and uninstallation.
- Complete credits, licenses, release notes, and player-facing documentation.
- Maintain a release-candidate checklist and resolve every release-blocking issue.
A signed, packaged release candidate followed by the initial public release.
- The release candidate completes a defined soak-test period without a release-blocking failure.
- Performance targets are met on minimum and recommended reference hardware.
- All supported controls, resolutions, settings, save flows, and packaged builds pass acceptance testing.
- No known critical defects remain, and lower-severity issues are documented and triaged.
These requirements begin in Tier 0 and remain active throughout development.
- The main branch should produce a runnable build.
- Temporary development shortcuts must not silently become permanent game rules.
- New mechanics require a sandbox or reproducible scenario for isolated testing.
- Unit-test deterministic calculations and data validation.
- Integration-test ECS system interactions, run transitions, drops, and upgrade application.
- Use replay or seeded simulation tests for regressions involving large numbers of entities.
- Keep rendering tests separate from headless simulation tests where practical.
- Measure before optimizing and retain representative benchmarks.
- Establish explicit budgets for simulation, rendering, particles, projectiles, enemies, familiars, pickups, and temporary structures.
- Prefer graceful simplification of cosmetic effects over changing mechanical outcomes.
- Define enemies, upgrades, drops, waves, and environment settings as validated data where behavior permits.
- Give every content item a stable identifier independent of its display name.
- Record prerequisites, incompatibilities, tags, and balance values explicitly.
- Keep README.md, SCHOOLS.md, ENEMIES.md, DROPS.md, ENVIRONMENTS.md, and this plan aligned with implemented behavior.
- Record important architectural decisions and rejected alternatives.
- Document build, run, test, benchmark, and packaging commands as soon as they exist.
The following decisions should be resolved in the tier where they first become necessary:
- Rendering, windowing, input, audio, and UI libraries: Tier 0.
- Reference hardware, target frame rate, and entity budgets: Tier 2.
- Exact run duration, XP curve, and school-upgrade cadence: Tier 3.
- Numerical challenge-rating budgets and elite modifier costs: Tier 4.
- Adaptation-slot count and ability-drop probabilities: Tier 5.
- Custom GPU shader for responsive-grid mass and environment deformation: profile and schedule during Tier 6 or later; preserve a CPU fallback.
- Snail enemy with fading, spatially indexed slowing-trail fields affecting both players and enemies: future enemy-content pass after the Tier 4 baseline roster is balanced.
- Full release content counts and persistent progression: before Tier 7 begins.
- Supported operating systems and distribution targets: before Tier 8 begins.
Deferring these choices is deliberate, but each must be documented when its tier begins so later work is not built on an unstated assumption.