GOALS.md

Project Goals

This document defines what BulletHeaven is trying to achieve, how success will be evaluated, and which tempting directions are outside the initial scope. It governs product decisions across design, implementation, content, and release.

Decision Status

Goals are labeled to distinguish established direction from assumptions that require validation.

• Committed: Part of the project's current identity. Changing it requires an explicit design decision.
• Proposed: A working target that enables development and should be validated through prototypes or playtesting.
• Deferred: Intentionally undecided until the named development tier.

Product Vision

Committed: BulletHeaven is a fast-paced Java action game that combines bullet-heaven escalation with direct multidirectional combat. The player moves, turns, aims, fires, and strafes deliberately while navigating dynamic arenas filled with geometric enemies, projectiles, hazards, pickups, and arena-wide forces.

The game should produce spectacular interactions from understandable rules. Its depth comes from player execution, five interacting schools of upgrades, captured enemy abilities, composable enemies, and environments that affect every entity consistently.

Non-Negotiable Product Pillars

1. Direct, expressive control

Committed: Movement and aim are independently controlled. The player can turn the firing angle and strafe while shooting.

• Positioning and accuracy matter throughout a run.
• Automated effects may support the player but do not replace deliberate aiming and movement.
• Controls must remain responsive during visually and mechanically dense encounters.

2. Systemic interaction

Committed: Enemies, projectiles, familiars, pickups, hazards, and arena effects share consistent simulation rules.

• Gravity, shock waves, time effects, duplication, shields, and other mechanics should interact through reusable components.
• The player can exploit effects that initially appear dangerous.
• New combinations should emerge without requiring bespoke code for every pairing.

3. Distinct build identities

Committed: The five schools create recognizable but compatible approaches to play.

• Mercury emphasizes movement.
• Jupiter emphasizes strength.
• Janus emphasizes duplication.
• Minerva emphasizes defense.
• Diana emphasizes familiars.

Enemy ability drops provide a second progression axis. They adapt a build to the current run without replacing school progression.

4. Readable spectacle

Committed: The screen can become intense without becoming unintelligible.

• Vector forms, motion, shape, and color communicate identity and intent.
• Friendly and hostile effects remain distinguishable.
• Telegraphs retain priority over decorative effects.
• Visual intensity scales down gracefully when required for accessibility or performance.

5. Replayable mastery

Committed: Repeated runs reward both mechanical improvement and experimentation.

• Better aiming, movement, threat assessment, and use of environmental forces improve results.
• Upgrade and ability combinations create meaningfully different builds.
• Randomness changes available opportunities but does not decide whether a run is functional.

Player Experience Goals

The player should regularly experience the following:

• The satisfaction of threading through danger while maintaining accurate fire.
• The decision to hold a strong firing position or move before an arena effect changes it.
• Recognition of an enemy by silhouette and movement before reading a label.
• A meaningful choice between strengthening an existing build and changing direction.
• Surprise when two familiar mechanics interact in a useful but understandable way.
• A visible transition from vulnerable survivor to powerful geometric force.
• Defeat that can be attributed to a readable decision, missed telegraph, or execution error.
• Immediate desire to try another school combination, captured ability, or tactical response.

Target Audience

Committed: BulletHeaven is intended for players who enjoy action roguelites, twin-stick shooters, bullet-heaven games, build crafting, and short repeatable sessions.

• The base controls should be understandable within one short encounter.
• Completing a run should require active engagement rather than passive build execution.
• Early difficulty should welcome players familiar with either bullet-heaven or twin-stick games.
• Advanced difficulty may demand precise movement, aiming, build knowledge, and environmental manipulation.
• Deep systems should be discoverable through play rather than requiring external guides.

This audience definition should be tested during the combat prototype and vertical slice.

Intended Tone and Identity

Committed: The game is energetic, abstract, luminous, and mythic rather than grim or realistic.

• Geometry supplies the visual language.
• The five Roman deities supply thematic structure for upgrades.
• Effects should feel powerful, clean, and kinetic.
• Minimal narrative context may support the action, but the initial release is not driven by dialogue or plot.
• The visual identity may take inspiration from the clarity and energy of Geometry Wars, but all assets, shapes, interface treatments, audio, names, encounters, and presentation must be independently designed.

Platform and Input Targets

Initial platform

Proposed: The initial release targets desktop computers, with Windows as the first supported and tested operating system.

• The architecture should avoid unnecessary platform-specific dependencies.
• Additional desktop operating systems may be supported after the release build is stable.
• Console and mobile releases are outside the initial development commitment.

The final operating-system list is Deferred until Tier 8.

Input

Committed: The game supports both:

• Keyboard and mouse.
• Twin-stick gamepad.

Both methods must support independent movement and aiming, firing, strafing, dashing or activated movement when present, upgrade selection, menus, and pause. Full remapping is a release goal.

Run Structure Targets

Proposed: A standard successful run should last approximately 20 minutes, excluding pauses and upgrade decisions.

• The opening minutes establish control and an initial build direction.
• The middle of the run introduces specialists, arena effects, and cross-school interactions.
• The final portion tests the completed build through elite encounters and an apex enemy.
• Defeat returns the player to a new run quickly.
• A shorter ten-minute format remains the development target through Tier 5.

Exact release run length and alternate modes are Deferred until vertical-slice playtesting.

Performance and Responsiveness Targets

Frame rate

Committed: The game should sustain 30 rendered frames per second and a stable fixed-step simulation during the densest intended release encounters on minimum supported hardware.

• Frame pacing matters in addition to average frame rate.
• Mechanical results must not depend on rendering frame rate.
• Input response must remain consistent under load.
• Cosmetic effects simplify before mechanical entities or telegraphs are removed.

Entity scale

Deferred until Tier 2: Establish measured budgets for enemies, projectiles, familiars, pickups, structures, and particles through ECS benchmarks.

The benchmark must represent a real worst-case build and encounter rather than an artificial population of inert entities.

Display

Proposed: The first release supports common desktop aspect ratios and remains readable at 1920×1080. Rendering and UI coordinates must be resolution-independent.

Minimum hardware, additional resolutions, and recommended specifications are Deferred until the ECS benchmark and vertical slice exist.

Initial Release Scope

The initial release aims to include the following, subject to validation and content budgeting before Tier 7.

Committed systems

• Independent movement and aiming with strafing.
• Keyboard/mouse and gamepad play.
• ECS-driven enemies, projectiles, pickups, familiars, hazards, and environmental forces.
• XP progression and upgrade selection during a run.
• Five schools with cross-school combinations.
• Enemy ability cores with adaptation slots and duplicate handling.
• Challenge-rated enemies and elite modifiers.
• Arena-wide effects including Gravity Spiral and Epoch Wave.
• A complete run with victory, defeat, and immediate restart.
• Settings for controls, audio, display, visual intensity, and accessibility.

Proposed content target

• At least five meaningful upgrades per school, plus advanced upgrades and a capstone path.
• Enemies from all five challenge ratings.
• At least one ability drop associated with every release enemy.
• At least six arena-wide effects, including supported combinations.
• At least two apex encounters.
• At least one complete arena theme with enough variation to sustain the standard run.

Final content counts are Deferred until the vertical slice establishes production cost and replay value.

Explicit Non-Goals for the Initial Release

The following are not required for the initial release unless this document is deliberately revised:

• Online multiplayer, competitive multiplayer, or networked cooperation.
• A persistent online service, account system, or mandatory connection.
• User-generated content or an in-game level editor.
• Mod support as a release requirement.
• Mobile or console versions.
• Photorealistic graphics, skeletal character animation, or asset-heavy cinematic presentation.
• A large narrative campaign, branching dialogue, or extensive voice acting.
• An open world or free-roaming level structure.
• Hundreds of minor upgrades whose primary purpose is increasing content count.
• Permanent progression that invalidates skill-based difficulty or makes early runs intentionally weak.
• Perfect simulation of physics when a simpler, readable rule creates better play.

These exclusions protect the core experience and can be reconsidered after a successful initial release.

Fairness and Randomness Goals

Committed: Randomness supplies variety, not hidden failure.

• Every run offers at least one viable path through school upgrades.
• XP is the dependable progression resource.
• Ability drops are exciting but not required for baseline viability.
• Dry-streak protection limits prolonged absence of ability cores.
• Upgrade prerequisites and incompatibilities are visible.
• Enemy and environment combinations are validated to preserve reasonable counterplay.
• Seeded runs allow difficult or surprising results to be reproduced.

Accessibility Goals

Committed for release: Important information is communicated through more than color alone.

The release should provide:

• Full control remapping for supported input devices.
• Adjustable screen shake, flashing, glow, particles, and motion intensity.
• Color-vision-friendly palettes or configurable ownership colors.
• Visual equivalents for gameplay-critical audio cues.
• Scalable interface text and readable contrast.
• Separate volume controls.
• Pause behavior that is consistent and immediately available during solo play.

Aim assistance, configurable game speed, and additional difficulty assists are Proposed and should be evaluated during vertical-slice accessibility testing.

Quality Goals

• A clean checkout builds, tests, and runs through the checked-in Gradle wrapper using documented commands.
• The main development branch remains runnable.
• Content definitions use stable identifiers and fail early when invalid.
• Important simulation behavior is deterministic under a known seed and recorded input.
• Every enemy, upgrade, captured ability, and arena effect has an isolated test scenario.
• Critical game state is never communicated only through decorative effects.
• Save corruption or version mismatch fails safely without preventing the application from starting.
• Release builds do not require development tools or an installed IDE.

Milestone Success Criteria

Combat prototype success

The Tier 1 prototype succeeds when:

• At least 80% of a small structured playtest group describes movement and aiming as responsive after five minutes of play.
• Players can move in one direction and accurately fire in another without instruction after learning the controls.
• Players deliberately strafe or reposition while maintaining fire rather than treating shooting as automatic.
• Deaths in the test arena can normally be explained by a visible threat or control decision.
• Moderate projectile and enemy density does not obscure player position or projectile ownership.

Failure to meet these criteria means control feel and presentation are revised before broader content work.

ECS benchmark success

The Tier 2 benchmark succeeds when:

• A documented worst-case representative scene meets the chosen simulation and rendering budgets.
• Entity creation, removal, collision, and neighborhood queries do not produce visible stalls.
• Repeated seeded simulations produce equivalent important outcomes.
• At least three behaviors can be recombined through components to produce a new enemy variant without creating a new concrete enemy class.

Playable-run success

The Tier 3 run succeeds when:

• A player can begin, progress, win or lose, view the outcome, and restart without developer intervention.
• Every school creates a noticeable change in play within its first two upgrades.
• Upgrade descriptions match observed behavior and stacking rules.
• XP pacing produces repeated choices without interrupting combat excessively.
• Multiple builds can complete the run.

Vertical-slice success

The Tier 6 vertical slice succeeds when:

• New players understand movement, aiming, strafing, XP, schools, and ability cores through play.
• At least 80% of structured playtest participants elect to begin another run after finishing or losing their first full run.
• Players can identify meaningful differences among all five schools.
• At least three substantially different builds can defeat the apex encounter.
• Gravity Spiral and Epoch Wave are understood well enough that players intentionally exploit them.
• The densest encounter meets the performance target on reference hardware.
• No critical accessibility, readability, progression, or run-blocking issue remains open.

Initial-release success

The initial release succeeds when:

• Every committed system is present and works in a packaged build.
• The release candidate passes the acceptance and soak tests defined in DEVPLAN.md.
• Supported controls, resolutions, settings, saves, victory, defeat, and restart flows pass release testing.
• No known critical defect remains.
• Players demonstrate multiple viable school and adaptation combinations rather than converging on one mandatory build.
• Difficulty data shows that defeat sources are distributed among execution, build decisions, and encounter knowledge rather than dominated by unreadable or unavoidable damage.
• Post-release feedback can be tied to reproducible seeds, builds, encounters, or performance data.

Commercial targets, audience size, pricing, and sales expectations are Deferred until a vertical slice can be evaluated honestly.

Decision Rules

When goals compete, use the following order:

1. Preserve responsive control and fair player agency.
2. Preserve mechanical and visual readability.
3. Preserve systemic consistency.
4. Preserve build diversity and replayability.
5. Preserve performance.
6. Add breadth, spectacle, and content volume.

If a feature is impressive but harms the first five priorities, simplify or remove it.

Validation and Revision

This document should be reviewed at the beginning and completion of every development tier.

• Convert proposed goals to committed goals when evidence supports them.
• Revise targets when measurements contradict an assumption.
• Record why a non-negotiable goal changed.
• Do not quietly expand initial-release scope through implementation.
• Keep GOALS.md, DEVPLAN.md, and the system design documents aligned.