Semi-Vibed Game

A top-down twin-stick survival game with an incremental upgrade loop. Each run is a short, intense session where you race to outscale an ever-approaching doomsday before time runs out.

Concept

The round timer is a doomsday clock — it counts down, and when it hits zero, something catastrophic happens. The goal isn't to survive until zero: it's to grow powerful enough to overcome doomsday itself. The core gameplay loop is:

1. Fight — kill enemies using twin-stick shooter controls
2. Upgrade — spend resources on a deep, branching upgrade tree
3. Outscale — become strong enough that the doomsday event is no longer a threat

Upgrades are not incremental tweaks — they are dramatic, build-defining power spikes. The upgrade tree should reward creative combinations and snowballing power.

Gameplay

• Genre: Top-down twin-stick survival / incremental
• Session length: Short loops (minutes per run)
• Controls: WASD to move, mouse to aim, left click to attack
• Win condition: Survive and overpower the doomsday event before or when the clock expires
• Lose condition: Die before you've scaled enough to face doomsday

Development

Tech Stack

• Engine: Godot 4.6 (GDScript)
• Physics: Jolt Physics
• Renderer: Forward Plus

Dev Environment

nix develop

Provides godot_4 (4.6-stable) and gdtoolkit_4 (gdlint / gdformat).

Running the Game

Open project.godot in Godot 4.6+ and press F5, or run headless:

godot_4 --headless --path . [scene]

Project Structure

entities/        # Paired .tscn + .gd files for each game entity
environment/     # Scene files for levels and test environments
  test_scene_1.tscn   # Main development/test scene
project.godot    # Engine configuration, input map

---

Instructions for Coding Agents

This section is specifically for AI coding agents implementing features in this project.

Role

You are implementing technical features and systems as directed by the project lead. The project lead handles design direction, art, and game design decisions. Your job is to build things that work correctly and match the specification given to you.

Priorities

1. Make the feature work first. A correct, functional implementation beats a polished but broken one.
2. Use placeholder assets freely. If a feature needs a sprite, sound, or scene that doesn't exist yet, create a simple placeholder (colored rectangle, default shape, etc.) and note what the real asset should be.
3. Don't design — implement. If a specification is ambiguous, make the minimal reasonable assumption and note it. Don't invent new game design.
4. Test what you build. Verify that your implementation actually works. See testing guidance below.

Testing

Always verify features using Godot's headless mode — do not assume the game runs correctly without checking:

# Run the main scene headless (boots, runs one frame, exits cleanly if no errors)
godot_4 --headless --path . --quit-after 100

# Run a specific scene
godot_4 --headless --path . scenes/my_scene.tscn --quit-after 100

# Check for script errors / parse errors without running
godot_4 --headless --path . --check-only

Watch stdout/stderr for errors and warnings. A clean run with no script errors is the baseline for "it works."

For logic that can't be verified visually in headless mode, add temporary print() statements or use assert() to validate state, then clean them up.

Code Style

• GDScript only — no C# or GDExtension unless explicitly requested
• Follow existing conventions in the codebase (see entities/player.gd and entities/ball_enemy.gd for reference)
• Keep scripts focused: one script per entity/system
• Run gdlint on any .gd files you create or modify

What to Avoid

• Don't refactor or "improve" code outside the scope of your task
• Don't add features not in the specification
• Don't make art or design decisions — create placeholders and flag them
• Don't leave the project in a broken state; if something is incomplete, note it clearly