chemo-sim/docs/ARCHITECTURE.md

Chemo-Sim – Technical Architecture

Goal: Build once, deploy to Windows/Linux, release on Steam with minimal overhead.

Tech Stack (Lean & Mean)

Component	Choice	Why
Game Engine	Godot 4.x (Open Source)	Free, cross-platform native exports, no fees, great 2D/3D hybrid, minimal learning curve
Language	GDScript	Godot-native; AI tools generate excellent GDScript, no language mixing friction
Build System	GitHub Actions + Godot Export Templates	Automated builds for all platforms, zero cost, versioning out of the box
Version Control	Git (GitHub/GitLab)	Standard; integrates with Steam builds
Audio	Godot's built-in AudioServer	Already integrated, sufficient for ambient + SFX + UI beeps, no licensing cost
Physics/3D	Godot's built-in Bullet Physics	Already integrated, no external dependency
UI/UX	Godot Control nodes + custom shaders	No external framework needed; build once, runs everywhere
Analytics	None initially OR Telemetry to self-hosted server	Consider privacy; avoid Unity/Unreal data-hoarding

Project Structure

chemo-sim/
├── project.godot                 # Godot project config
├── scenes/                       # Game scenes (organized by system)
│   ├── hospital/
│   ├── treatment_ui/
│   ├── symptoms/
│   ├── minigames/
│   └── menus/
├── scripts/                      # GDScript code
│   ├── game_systems/
│   ├── ui_controllers/
│   ├── minigame_logic/
│   └── utils/
├── assets/                       # Art, audio, fonts
│   ├── models/
│   ├── textures/
│   ├── audio/
│   └── fonts/
├── export_templates/             # Godot export configs for each platform
│   ├── windows.export
│   └── linux.export
├── build/                        # Generated build outputs
│   ├── windows/
│   └── linux/
├── ci/                           # CI/CD scripts
│   ├── .gitea/workflows/        # GitHub Actions for auto-builds
│   ├── build.sh
│   └── build.ps1                 # Windows build script
├── docs/
│   ├── DEVELOPMENT_ROADMAP.md
│   ├── STEAM_RELEASE_CHECKLIST.md
│   ├── BUILD_GUIDE.md
│   └── GAME_DESIGN_DOCUMENT.md
└── README.md

Cross-Platform Strategy

Windows (x64)

• Export format: .exe (standalone)
• Runtime: Godot includes all dependencies
• Signing: Optional (self-signed or purchased cert for Steam trust)
• Build time: ~5 minutes

Linux (Portable + AppImage)

• Export format: Portable executable + AppImage (recommended)
• Runtime: Fully portable; ships all libs needed
• No signing required
• Build time: ~5 minutes

Build Pipeline (GitHub Actions)

Automated builds on every commit to main:

# .gitea/workflows/build.yml (pseudocode)
on: [push, pull_request]
jobs:
  build:
    runs-on: [ubuntu-latest, windows-latest]
    steps:
      - uses: actions/checkout@v2
      - uses: chickensoft-games/setup-godot@v2
      - run: godot --export-project YOUR_PLATFORM
      - uses: actions/upload-artifact@v2

Result: Every push generates Windows .exe and Linux .AppImage in GitHub releases.

Steam Distribution

Submission Requirements

• Godot version: Latest stable (currently 4.x)
• Build artifacts: Separate builds for Win/Linux (Steam handles delivery)
• Depot configuration: Steamworks SDK includes per-platform depots
• Build size targets:
  • Windows: ≤500 MB
  • Linux: ≤400 MB

Steam Integration

1. Steamworks SDK integration (optional, recommended for achievements):
   • Godot has GodotSteam plugin (community-maintained, free)
   • Handles achievements, leaderboards, cloud saves, controller support
2. Build upload:
   • Use Steamworks SDK command-line tools
   • OR upload via Steamworks web UI
3. Testing:
   • Steam provides free depot testing tools
   • Beta branch testing before public release

Performance Targets

Metric	Target	Notes
FPS	60 stable	First-person game; smooth matters
Load time	<5 sec	Hospital scenes are relatively simple
Memory	<1 GB	Godot is lean; you'll be fine
CPU	Single-core capable	Most indie devs' machines should run it

Development & Iteration

Local Builds

# Export all platforms locally
godot --export-release Windows "build/windows/chemo-sim.exe"
godot --export-release Linux "build/linux/chemo-sim.x86_64"

Rapid Testing

• Run in Godot editor for quick iteration
• Export to single platform while developing
• Test cross-platform before final builds (use GitHub Actions for CI/CD)

Known Gotchas

1. Linux distros: Test on Ubuntu, Fedora, and Arch—most players use one of these.
2. Controller support: Godot auto-detects; test with a gamepad if you support it.
3. Godot versioning: Lock to a specific Godot 4.x version in your CI/CD. Don't always use "latest."

Cost Breakdown (Minimal)

Item	Cost	Notes
Godot	$0	Open source
GitHub	$0	Free tier supports CI/CD
Steam Submission	$100	One-time per game
Apple Developer	$0	macOS dropped from scope
Steamworks	$0	Free after submission fee
Total	~$100	One-time; no recurring fees

Next Steps

1. Install Godot 4.x
2. Initialize GitHub repo with structure above
3. Set up GitHub Actions for CI/CD (see BUILD_GUIDE.md)
4. Export templates locally to verify each platform works
5. Create Steamworks account, reserve app ID
6. Begin development

See DEVELOPMENT_ROADMAP.md for phased shipping strategy.