From 126b6fdd58017d5c9a6af9500ff7748530ea0933 Mon Sep 17 00:00:00 2001
From: Frank Tovar <mail@franktovar.de>
Date: Tue, 21 Apr 2026 17:02:03 +0200
Subject: [PATCH] Add side-scrolling shooter systems design

---
 DESIGN.md | 530 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 530 insertions(+)
 create mode 100644 DESIGN.md

diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..540dd62
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,530 @@
+# Side-Scrolling Shooter Systems Design
+
+This document captures systems that can be prepared before the game jam topic is known. It avoids theme, story, enemy names, weapon names, and visual commitments. All content-specific choices should live in data files, scene resources, or exported Godot properties so the final topic can reskin and rebalance the game without changing core systems.
+
+## Design Goals
+
+- Keep gameplay systems modular and data-driven.
+- Separate content from behavior wherever practical.
+- Allow each mission to define its own visual layers, music, enemy waves, boss, shop offer, rewards, and choreographed sequences.
+- Support a fixed side-scrolling camera path with authored speed changes.
+- Preserve enough flexibility for a serious, comic, abstract, horror, cute, mechanical, biological, fantasy, or surreal jam theme.
+
+## Project Organization
+
+Use the repository root as a Godot 4 .NET project.
+
+- `project.godot` is the Godot project entrypoint.
+- `scenes/` contains playable and reusable Godot scenes.
+- `scripts/` contains C# scripts paired with scenes.
+- `assets/` contains sprites, audio, fonts, tile sets, particles, and animation data.
+- `addons/` contains third-party Godot plugins if needed.
+- `build/` contains local export output and should stay uncommitted unless a release workflow requires it.
+
+Recommended scene and script pairs:
+
+- `scenes/game/GameRoot.tscn` with `scripts/game/GameRoot.cs`
+- `scenes/level/LevelRunner.tscn` with `scripts/level/LevelRunner.cs`
+- `scenes/hero/Hero.tscn` with `scripts/hero/HeroController.cs`
+- `scenes/enemies/EnemyActor.tscn` with `scripts/enemies/EnemyActor.cs`
+- `scenes/weapons/Projectile.tscn` with `scripts/weapons/Projectile.cs`
+- `scenes/collectibles/Collectible.tscn` with `scripts/collectibles/Collectible.cs`
+- `scenes/ui/Shop.tscn` with `scripts/ui/ShopController.cs`
+
+## Data-Driven Content
+
+Prefer Godot resources or plain C# definition classes for tunable game content. The final jam topic should mainly add or edit these definitions.
+
+- `MissionDefinition`: level route, parallax sets, encounter schedule, boss, music, intro/outro choreographies, victory type rules, shop options.
+- `LevelLayerDefinition`: texture set, scroll factor, repeat mode, transition rule, visibility window, optional animation.
+- `CameraPathDefinition`: path points, speed curve, easing, gameplay bounds, boss lock behavior.
+- `EnemyTypeDefinition`: composed sprite parts, health, collision bounds, score, behaviors, projectile patterns, collectible drop table.
+- `EnemyClusterDefinition`: enemy type references, spawn timings, spawn anchors, cluster completion reward.
+- `CollectibleDefinition`: category, pickup behavior, value, visuals, sound, persistence rule.
+- `WeaponDefinition`: firing cadence, projectile count, damage, speed, collision behavior, seeking rules, level scaling.
+- `SquadronMateTypeDefinition`: formation rule, spacing, movement smoothing, targeting behavior, visuals.
+- `SpecialWeaponDefinition`: initial ammo, ammo pickup amount, projectile behavior, damage rule, invulnerability or pull effects.
+
+## Level System
+
+The level is a timeline-driven side-scrolling space. The camera follows a fixed authored path while the world layers, enemy spawns, and choreographies react to mission time and camera progress.
+
+### Layers
+
+Use separate layer groups:
+
+- Background parallax layers without collision.
+- Interactive elements layer with enemies, hazards, boss parts, destructible objects, collectible spawns, and terrain used by special weapons.
+- Foreground parallax layers without collision.
+
+Each parallax layer should support:
+
+- Independent scroll factor.
+- Repeating textures or scene chunks.
+- Optional animation.
+- Optional transition into a different layer set as the mission progresses.
+- Visibility windows based on mission progress.
+
+Layer transitions should support crossfade, slide-in replacement, hard cut during choreo, or hidden swap behind foreground cover. The transition type should be data, not hardcoded.
+
+### Repeating Level Content
+
+Parallax layers may repeat indefinitely. Interactive content should not repeat blindly; it should be scheduled by the mission definition so enemy clusters and pickups stay intentional.
+
+Reusable repeating layer options:
+
+- Texture-based repeat for simple skies, stars, clouds, tunnels, smoke, speed lines, or abstract fields.
+- Chunk-based repeat for large authored sections.
+- Procedural variation by selecting from a small set of compatible chunks.
+
+### Camera Path
+
+The player does not control camera movement. The mission controls:
+
+- Path position over time.
+- Speed changes.
+- Gameplay bounds around the camera.
+- Slowdowns or stops for boss intros.
+- Acceleration during escape or chase sections.
+- Transition windows for layer changes and music cues.
+
+The hero should move inside a camera-relative play area. Enemy spawns can be anchored to the camera, world path, screen edges, or authored scene markers.
+
+## Enemy Types
+
+An enemy type is a reusable actor definition. It may be a free-moving spawned enemy or a level-attached interactive element.
+
+Enemy types consist of composed sprite parts. Each part may define:
+
+- Local offset and orientation.
+- Sprite or animation.
+- Optional hitbox.
+- Optional hurtbox.
+- Optional weapon mount.
+- Optional destruction effect.
+- Optional behavior track.
+
+The whole enemy owns shared state:
+
+- Health.
+- Score value.
+- Cluster membership.
+- Drop table.
+- Death behavior.
+- Whether it is free-moving or attached to the level layer.
+
+### Enemy Behaviors
+
+A behavior is one serial sequence or many parallel sequences of timed events.
+
+Supported event categories:
+
+- Traverse a position path.
+- Traverse an orientation path.
+- Wait.
+- Fire projectile pattern.
+- Change speed.
+- Change animation.
+- Enable or disable hitboxes.
+- Spawn child enemy or projectile.
+- Move relative to camera.
+- Move relative to level path.
+- Trigger VFX or SFX.
+- Signal cluster state.
+
+Behavior authoring should allow both:
+
+- Serial tracks where event B starts after event A.
+- Parallel tracks where movement, aiming, firing, animation, and part transforms run together.
+
+This can be implemented as composable behavior nodes, C# definition data, Godot animation tracks, or a hybrid. The key rule is that content creators can assemble behavior without rewriting the enemy runtime.
+
+## Enemy Clusters
+
+An enemy cluster is a mission-scheduled encounter group. It contains several instances of one or more enemy types spawned at different intervals.
+
+A cluster definition should include:
+
+- Cluster id.
+- Spawn schedule.
+- Enemy type references.
+- Spawn positions or anchors.
+- Optional path references.
+- Optional shared behavior parameters.
+- Completion reward.
+
+Destroying all enemies in a cluster awards points. Enemies that leave the play area without being destroyed should follow a cluster-specific rule:
+
+- Count as escaped and prevent completion reward.
+- Count as resolved and still allow completion reward.
+- Respawn or loop until destroyed.
+
+Default rule: escaped enemies prevent the cluster completion reward. This keeps cluster rewards meaningful, but the mission can override it for casual or cinematic waves.
+
+## Collectibles
+
+Collectibles are spawned by enemies, clusters, scripted mission events, hidden triggers, or boss phases. Pickups should use a shared collection interface so hero, inventory, score, and mission systems are not tightly coupled to pickup scenes.
+
+Collectible categories:
+
+- Points.
+- Primary weapon.
+- Secondary weapon.
+- Clear screen.
+- Shield charge.
+- Special weapon ammunition.
+- Squadron mate of a specific type.
+
+Primary weapon pickup rule:
+
+- Fill an empty primary weapon slot if one exists.
+- Otherwise replace the currently selected primary weapon slot.
+
+Secondary weapon pickup rule:
+
+- Replace the current secondary weapon.
+
+Clear screen pickup rule:
+
+- Destroy or neutralize normal enemy projectiles.
+- Damage or destroy eligible non-boss enemies.
+- Avoid deleting bosses unless a specific boss phase says it can.
+
+Persistent pickup rule:
+
+- The hero keeps collectibles at mission end.
+- The hero loses all collectibles on death.
+
+## Hero
+
+The hero is the player's main actor. It owns mission-persistent inventory and mission-local survival state.
+
+Hero state:
+
+- Level.
+- Points.
+- Point thresholds for level up.
+- Fixed number of primary weapon slots.
+- Current primary weapon slot.
+- Current secondary weapon.
+- Current special weapon and ammo.
+- Shield charges.
+- Squadron mate list.
+- Retry count.
+
+Default survival rules:
+
+- The hero starts with 3 shield charges.
+- Getting hit consumes 1 shield charge.
+- Leveling up adds 1 shield charge.
+- A hit with 0 shield charges kills the hero.
+- The hero starts with 3 retry counts.
+- Rebirth consumes 1 retry.
+- Game over occurs when retries are exhausted.
+- Death removes all collectibles and squadron mates.
+- Mission victory persists kept collectibles into the next mission.
+
+Point thresholds should be configurable per game mode or mission set. The jam topic may change score pacing, so level-up curves should not be hardcoded.
+
+## Squadron Mates
+
+Squadron mates are support actors owned by the hero.
+
+Rules:
+
+- Maximum active squadron mates: 4.
+- All active mates use the same type.
+- The type is determined by the last collected squadron mate pickup.
+- Mates maintain relative position according to type.
+- Mates collide with and consume enemy particles.
+- Mates take no damage from consuming enemy particles.
+
+Changing squadron mate type should preserve count and replace formation behavior. The visual style can change with the final topic.
+
+### Squadron Mate Types
+
+Hug:
+
+- Mates stay close together on the hero's nose.
+- Useful for high forward damage and focused defense.
+
+Orbit:
+
+- Mates orbit around the hero.
+- Mate id determines phase offset.
+- Useful for defensive coverage.
+
+Line-Formation:
+
+- Mates form equidistant positions above and below the hero.
+- Useful for vertical coverage.
+
+V-Formation:
+
+- Mates form equidistant positions behind and above or behind and below the hero.
+- Useful for broad forward coverage.
+
+Follow:
+
+- Mates fly toward the front of the oldest enemy on screen.
+- Useful for aggressive targeting.
+
+## Hero And Squadron Firing
+
+The hero and all squadron mates:
+
+- Fire the current primary weapon forward.
+- Fire the secondary weapon in its configured direction.
+
+Firing ownership matters for balance. Each shot should know whether it came from the hero or a squadron mate so damage, effects, score credit, and visual scale can be tuned separately.
+
+## Primary Weapons
+
+Primary weapons have infinite ammo and are influenced by hero level.
+
+Primary weapon families:
+
+- Ballistic many-fast-weak shots.
+- Ballistic few-slow-strong shots.
+- Forward-only projectiles.
+- Seeking projectiles that target the nearest enemy.
+- Laser beams that appear and disappear while filling an entire row.
+- Grenade clusters that launch fast, slow down, then create a large explosion when stopped.
+- Projectile-consuming shots that collide with and consume enemy projectiles.
+
+Primary weapon level scaling may affect:
+
+- Damage.
+- Fire cadence.
+- Projectile count.
+- Projectile spread.
+- Projectile size.
+- Seeking strength.
+- Projectile lifetime.
+- Ability to consume enemy projectiles.
+
+## Secondary Weapons
+
+Secondary weapons have infinite ammo and always fire from the hero and squadron mates. Their projectiles do not collide with enemy projectiles.
+
+Secondary weapon types:
+
+- Vertical: fire upward when on the top half of the screen, or downward when on the bottom half.
+- Diagonal: fire toward the positive diagonal when on the top half of the screen, or toward the negative diagonal when on the bottom half.
+- Backward: fire backward.
+
+Secondary weapons should support additional projectile counts depending on type. The final topic can turn these into exhaust blasts, magic sparks, drones, thrown tools, sound waves, or any other theme.
+
+## Special Weapons
+
+Special weapons are chosen in the shop before a mission. They have initial ammo and may be replenished by collectibles.
+
+Special weapon types:
+
+- Bomb: gravity affects it; it explodes once on impact; lots of ammo.
+- Crawler: gravity affects it; it crawls forward following terrain contour; it explodes once on enemy impact; moderate ammo.
+- Napalm: gravity affects it; it creates a huge horizontal spread and 1 second burn on impact; moderate ammo.
+- Black Hole: grants 3 seconds of invulnerability, pulls enemies, and is destroyed upon player impact; few ammo.
+
+Terrain interaction should be optional per mission. Missions without solid terrain can still use Bomb and Napalm with screen-bound impact rules, while Crawler may be disabled in that mission's shop.
+
+## Enemy Projectiles And Particles
+
+Enemy offensive objects should be separated by gameplay role:
+
+- Enemy projectile: damages the hero, may be consumed by eligible primary weapons.
+- Enemy particle: can be consumed by squadron mates without damaging them.
+- Enemy hazard: part of interactive level content, may damage the hero and may ignore projectile-clear effects.
+
+This separation allows the final topic to change visuals without changing collision rules.
+
+## Shop
+
+The shop appears before each mission. Its required function is choosing one special weapon type for the next mission.
+
+The shop can later support:
+
+- Previewing ammo count.
+- Showing mission hint text.
+- Showing currently kept collectibles.
+- Locking special weapons that do not fit the mission.
+- Secret victory requirements.
+
+The first implementation should stay small: choose one special weapon, confirm, enter mission intro.
+
+## Game Loop
+
+Top-level flow:
+
+1. Logo.
+2. Intro choreography, skippable.
+3. Menu with start and controls.
+4. Mission loop.
+5. Rebirth retry, game over, normal victory, or secret victory choreography.
+6. Highscore.
+
+Choreography means an authored non-interactive or lightly interactive sequence. It may move actors, play animations, change music, show text, or transition scenes. Choreography should be skippable where appropriate.
+
+## Mission Loop
+
+Per-mission flow:
+
+1. Open shop for choosing one special weapon type for the next mission.
+2. Queue mission-specific music.
+3. Play mission-specific intro choreography.
+4. Fade to actual gameplay.
+5. Run camera path, level timeline, enemy clusters, collectibles, and player control.
+6. Queue boss music.
+7. Play boss-specific intro choreography.
+8. Run boss fight.
+9. Mute music and play boss destruction VFX.
+10. Queue victory music.
+11. Play generic mission outro choreography.
+12. Fade out.
+
+Mission results should determine:
+
+- Continue to next mission.
+- Trigger rebirth retry.
+- Trigger game over.
+- Trigger normal victory.
+- Trigger secret victory.
+- Submit or display highscore.
+
+## Bosses
+
+Bosses are specialized enemy clusters with stronger choreography and phase control.
+
+Boss design should support:
+
+- Composed sprite parts.
+- Separate health pools per part or shared health.
+- Phase transitions.
+- Destructible mounts.
+- Attached projectiles or hazards.
+- Boss-specific intro.
+- Boss-specific destruction VFX.
+- Boss music queue.
+
+Bosses should use the same behavior event model as enemies where possible. Add boss-specific code only for phase orchestration that normal enemies cannot express cleanly.
+
+## Collision Model
+
+Recommended collision categories:
+
+- Hero body.
+- Squadron mate body.
+- Hero projectile.
+- Hero projectile that consumes enemy projectiles.
+- Enemy body.
+- Enemy weak point.
+- Enemy projectile.
+- Enemy particle.
+- Interactive hazard.
+- Collectible.
+- Terrain contour for special weapons.
+
+Keep parallax background and foreground layers collision-free.
+
+## Scoring
+
+Scoring sources:
+
+- Point collectibles.
+- Enemy destruction.
+- Cluster completion.
+- Boss phases.
+- Mission victory.
+- Secret victory.
+
+The score system should publish events for UI, highscore, level-up thresholds, and mission results.
+
+## Persistence
+
+Persist only what needs to survive across missions or game sessions.
+
+Mission-to-mission state:
+
+- Hero level.
+- Points.
+- Primary weapon slots.
+- Current primary weapon slot.
+- Current secondary weapon.
+- Current special weapon ammo if the game mode keeps it.
+- Shield charges.
+- Squadron mate count and type.
+- Retry count.
+
+Run-ending highscore state:
+
+- Player name or initials.
+- Score.
+- Mission reached.
+- Victory type.
+- Optional modifiers.
+
+## Testing Strategy
+
+For a one-month jam, keep tests focused on systems that can break content quickly.
+
+High-value unit tests:
+
+- Level-up thresholds add shield charges.
+- Primary weapon pickup fills empty slot before replacing current slot.
+- Secondary weapon pickup replaces current weapon.
+- Squadron mate pickup changes type while preserving count up to 4.
+- Death clears collectibles and consumes retry when available.
+- Game over triggers when retry count is exhausted.
+- Cluster reward is awarded only when completion rules are satisfied.
+- Special weapon ammo pickups replenish the selected special weapon.
+
+High-value play tests:
+
+- Start game and enter first mission.
+- Pick a special weapon in the shop.
+- Complete a small enemy cluster and receive points.
+- Collect each collectible type.
+- Die with shield charges and without shield charges.
+- Rebirth and game over.
+- Reach boss intro, boss destruction VFX, and mission outro.
+
+## Open Topic Customization Points
+
+When the jam topic is announced, decide these late:
+
+- Visual identity of hero, enemies, projectiles, collectibles, and UI.
+- Names and flavor text.
+- Mission count and mission themes.
+- Enemy sprite composition style.
+- Background and foreground layer art.
+- Music style.
+- Sound effect vocabulary.
+- Exact weapon names.
+- Special victory requirement.
+- Score balance.
+- Difficulty curve.
+- Boss concepts.
+
+Do not decide these early unless they help prove a system.
+
+## First Implementation Slice
+
+The first playable slice should be intentionally small:
+
+1. One mission definition.
+2. One repeating background layer.
+3. One repeating foreground layer.
+4. One fixed camera path with speed changes.
+5. One hero with movement, shield charges, points, and primary fire.
+6. One primary weapon.
+7. One secondary weapon.
+8. One special weapon selected through a minimal shop.
+9. One enemy type with a serial behavior.
+10. One enemy type with parallel movement and firing behavior.
+11. One enemy cluster with completion reward.
+12. One collectible for points.
+13. One collectible for squadron mate.
+14. One boss placeholder with intro and destruction sequence.
+15. One mission outro and highscore entry.
+
+This slice proves the game loop and leaves almost all theme content open.