zfxaction26_1/DESIGN.md

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.

Squadron mate rule:

• If the collectible matches the current type, increase mate count (capped at max)
• Otherwise change the current type

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 projectiles.
• Mates take no damage from consuming enemy projectiles.

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 tight maneuvers.

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 properties:

• 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 which are destroyed upon player impact; few ammo.

Enemy Projectiles

Enemy offensive objects should be separated by gameplay role:

• Enemy projectile: damages the hero, may be consumed by eligible primary weapons or 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.

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 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. Show next mission details and 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.

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.