Stellar Ambitions 🚀

An incremental space idler built in Godot 4.7.1 stable (Mono / .NET, C# only), drawing its core mechanical inspiration from the highly physical, synergistic prestige loops of The Gnorp Apologue, translated into a 2D zero-gravity space setting — with a limited retro color palette but much higher-fidelity ships, backgrounds, and effects.

🤖 AI agents: read AGENTS.md first. It contains the hard rules (C# only, mandatory MCP usage, test commands) and the documentation map.

Start by manually commanding your Mothership to fire on the mysterious Anomaly, breaking off shards and tractoring them in. Commission Habitat Barges into your fleet to expand pilot capacity and recruit idle pilots over time (Gnorp-style!). Commission carrier-class ships (Extraction Carrier, Logistics Carrier, Escort Carrier, Science Vessel, Merchant Flagship) from the screen-space Shipyard (B) — fabricator drones build them at station slots near the Mothership. Watch as shards accumulate into a massive Accretion Pile floating in space.

Compaction is an automatic mid-run event: when ungathered Accretion Pile worth reaches the target threshold (600 C base * 1.5^(tier-1)), the Anomaly sucks pile chunks back into its core, advances Tier, and awards Alien Resources. Your corporate empire (carriers, ships, Creds) remains completely intact!

Prestige is the run reset loop: driven by Income Per Minute (IPM) milestones or holding the 5-second Prestige button, Prestige liquidates all active carriers and ships into material streams back to the Anomaly, blips the screen shut with a retro CRT monitor collapse, resets session state back to Tier 1, and warps the Mothership in with permanent Prestige Skill Points (SP) retained!

Press ESC at any time to bring up the Settings & Dev Console: adjust volume, toggle window modes and the post-process CRT shader, or open the Dev/Cheat window to add Creds/SP/Alien Resources/Pilots, commission all carriers, max talents, spawn hostile fleets or traders, scale simulation speed (1x-10x), force prestige, or hard-reset your save data.

---

📖 Project Documentation Index

To facilitate both human collaboration and autonomous AI-driven development and testing, the core specifications, architecture, and guides are organized under the docs/ folder:

• AGENTS.md: The AI contributor guide — hard rules, commands, doc map, known code↔design gaps. Start here if you are an AI.
• Overview: The single source of truth for the project, linking to the split GDD documents.
• GDD 01–05: Core Loop & Visuals, Progression & Tech, Carriers & Ships, Synergies & Build Archetypes, Combat & Threats.
• Incremental Design Principles: The tuning bible — pacing curves, prestige math, gray-bar carryover, variable rewards, the anti-idle paradox.
• Roadmap: The progression of features from early alpha to release, including known code↔design gaps.
• Technical Architecture & State Management: Defines the Godot C# node structure, scene configurations, global event bus, data saving/loading, and state management flow.
• AI Testing Guide: Specifications for building, running, and asserting headless automated integration tests in Godot 4 .NET / C#.
• Pixel Art & Asset Pipeline: Guidelines for Aseprite MCP asset generation, palette quantization, dithering, and Godot export.
• Audio: Music & SFX direction — Strudel REPL patterns rendered to OGG (placeholder until tracks land).

---

🤖 AI-Driven Development & Testing Philosophy

Stellar Ambitions is designed from the ground up to be developed, refactored, and tested by AI agents using C#. To maintain consistency and quality:

1. Read First: Before editing any code, the AI must read the Technical Architecture to align with design patterns.
2. Test-Driven Execution: Any new gameplay feature or mechanic should have corresponding automated headless C# tests, as described in the AI Testing Guide.
3. Strict Compilation & Clean Code: AI agents must adhere to modern C# 12 / .NET 8 best practices, static typing, and signal-based decoupling. Compile via dotnet build stellar-ambitions.csproj.

AI Art Generation

The project uses diivi/aseprite-mcp for all asset generation and modification.

• Prerequisites: Python 3.13+, the uv package manager, and Aseprite installed and available in the system PATH.
• MCP Registration: The MCP servers are registered with Cursor via .cursor/mcp.json (mirrored in mcp.json / .antigravity.json for other clients). If the Aseprite MCP tools do not appear in the agent's toolset, check that file first — do NOT fall back to writing one-off Python sprite generator scripts.
• Automated Pipeline: AI agents automatically handle palette-snapping (quantize_to_palette), dithering (apply_dither_gradient using 2x2/4x4 Bayer matrices), and exporting spritesheets directly into res://assets/sprites/ and updating corresponding .tscn scene files. See docs/art_pipeline.md for full details.

---

⚙️ Project Setup & Prerequisites

• Engine: Godot Engine 4.7.1 stable, .NET / Mono edition (godot on PATH)
• SDK: .NET 8.0 SDK (project targets net8.0 via Godot.NET.Sdk/4.7.1)
• Language policy: C# only. All former GDScript has been migrated; do not add new GDScript game code.
• Building: dotnet build stellar-ambitions.csproj
• Testing: godot --headless --path . -s test/TestRunner.cs
• Art Generation Tools: Python 3.13+, uv, and Aseprite.
  • If installed via Steam, symlink aseprite into ~/.local/bin/:

    mkdir -p ~/.local/bin
    ln -sf ~/.local/share/Steam/steamapps/common/Aseprite/aseprite ~/.local/bin/aseprite
    

• Git LFS: Large File Storage (LFS) is configured via .gitattributes to handle texture maps, font files, and audio assets. Ensure LFS is installed locally:

  git lfs install
  

---

🗄️ Repository Hosting & Backups

• Remote: self-hosted Forgejo at git.unclelukie.com (not GitHub — don't assume GitHub tooling such as gh or GitHub Actions).
• Backups: the Forgejo repository is backed up to Google Drive on a 4-day cadence.