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

```txt
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`:

```yaml
# .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

```bash
# 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.