# [GAME TITLE] - Systems Bible

**Version:** [X.Y]
**Engine:** Godot [Version]
**Language:** GDScript / C# / etc.
**Last Updated:** [Date]

---

## TABLE OF CONTENTS

1. [Project Architecture](#project-architecture)
2. [Core Systems](#core-systems)
3. [Managers & Autoloads](#managers--autoloads)
4. [Data Systems](#data-systems)
5. [System Interactions](#system-interactions)
6. [Performance Considerations](#performance-considerations)
7. [Debugging & Tools](#debugging--tools)
8. [Common Patterns](#common-patterns)

---

## PROJECT ARCHITECTURE

### Directory Structure

### Naming Conventions

**Files:**
- Scenes: `PascalCase.tscn` (e.g., `Player.tscn`)
- Scripts: `snake_case.gd` (e.g., `player.gd`)
- Resources: `PascalCase.tres` (e.g., `MachineGun.tres`)

**Code:**
- Classes: `PascalCase` (e.g., `WeaponManager`)
- Variables: `snake_case` (e.g., `current_health`)
- Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_SPEED`)
- Signals: `snake_case` (e.g., `health_changed`)
- Private variables: `_snake_case` (e.g., `_internal_state`)

### Autoload Singletons

**Registered autoloads** (Project → Project Settings → Autoload):
1. **GameState** - Global game state, pause, score
2. **WeaponManager** - Weapon spawning and management
3. **PassiveManager** - Passive ability tracking
4. **DamageNumberManager** - Damage number display
5. **VFXManager** - Visual effects pooling

---

## CORE SYSTEMS

[Document each major system]

### System: Player Movement & Combat

**Purpose:** Handle player-controlled mech movement, collision, and weapon management

**File:** `scripts/systems/player.gd`

**Architecture:**

**Key Properties:**
```gdscript
@export var max_health: int = 100
@export var move_speed: float = 200.0
var current_health: int
var velocity: Vector2
var xp: int = 0

signal health_changed(current: int, max: int)
signal died()
signal level_up(level: int)

Input → _physics_process() → velocity → move_and_slide() → position

EnemyBullet → take_damage() → health_changed → HUD update
                            → died → GameState.game_over()

Enemy kill → add_xp() → xp check → level_up → Main.show_level_up_menu()

WeaponManager (Autoload Singleton)
  ├─ Responsibilities:
  │   ├─ Spawn weapons on player
  │   ├─ Store weapon configurations
  │   └─ Provide weapon instances
  │
  └─ Used By:
      ├─ Player (requests weapon spawns)
      ├─ Main (level-up weapon additions)
      └─ LevelUpMenu (weapon upgrade choices)

WeaponBase (Base Class)
  ├─ Properties:
  │   ├─ target_priority: TargetPriority enum
  │   ├─ firing_condition: FiringCondition enum
  │   └─ cooldown: float
  │
  └─ Inherited By:
      ├─ MachineGun
      ├─ Railgun
      ├─ Laser
      ├─ Missiles
      └─ Flamethrower

enum TargetPriority {
    CLOSEST,      # Fire at nearest enemy
    WEAKEST,      # Fire at lowest HP enemy
    STRONGEST,    # Fire at highest HP enemy
    GROUP,        # Fire at clusters (3+ enemies)
    ELITE_ONLY    # Fire only at elite/boss enemies
}

enum FiringCondition {
    ALWAYS,           # Fire whenever loaded
    OPTIMAL_RANGE,    # Only fire within ideal range
    SAVE_FOR_ELITE,   # Don't waste ammo on normal enemies
    HIGH_HEALTH_ONLY  # Only fire if target HP > 50%
}

func _get_best_target() -> Node2D:
    var enemies = get_tree().get_nodes_in_group("enemies")
    var valid_targets = []

    # Filter by firing condition
    for enemy in enemies:
        if _is_valid_target(enemy):
            valid_targets.append(enemy)

    if valid_targets.is_empty():
        return null

    # Sort by target priority
    match target_priority:
        TargetPriority.CLOSEST:
            return _get_closest(valid_targets)
        TargetPriority.WEAKEST:
            return _get_weakest_hp(valid_targets)
        TargetPriority.STRONGEST:
            return _get_strongest_hp(valid_targets)
        TargetPriority.GROUP:
            return _get_clustered(valid_targets)
        TargetPriority.ELITE_ONLY:
            return _get_elite(valid_targets)

    return null

LoadoutScreen → Set weapon rules (target_priority, firing_condition)
                ↓
Player spawns → WeaponManager.add_weapon()
                ↓
Weapon._process() → Query enemies → Filter by condition → Sort by priority
                ↓
_fire(target) → Spawn bullet / raycast / beam / missile
                ↓
Bullet hits enemy → Enemy.take_damage()

Main Scene
  ├─ WaveSpawner (Timer-based)
  │   ├─ Tracks elapsed time
  │   ├─ Reads wave definitions
  │   └─ Spawns enemy instances
  │
  └─ Enemy Pooling (planned)
      └─ Pre-instantiate enemies for performance

func _on_spawn_timer_timeout():
    var elapsed = Time.get_ticks_msec() / 1000.0
    var enemy_type = _determine_enemy_type(elapsed)
    var spawn_pos = _get_random_spawn_position()

    var enemy = enemy_type.instantiate()
    enemy.global_position = spawn_pos
    add_child(enemy)

func _get_random_spawn_position() -> Vector2:
    var player_pos = player.global_position
    var offset = Vector2(randf_range(400, 600), 0).rotated(randf() * TAU)
    return player_pos + offset

Enemy dies → Enemy.queue_free() → emits "died" signal
                ↓
Player.on_enemy_died(xp_value) → player.add_xp(xp_value)
                ↓
Player.add_xp() → check threshold → emit level_up
                ↓
Main._on_player_level_up() → pause game → show LevelUpMenu
                ↓
LevelUpMenu → show 3 random choices (weapon/upgrade/passive)
                ↓
Player selects → apply upgrade → resume game

const XP_THRESHOLDS = [
    100,   # Level 2
    250,   # Level 3
    450,   # Level 4
    700,   # Level 5
    1000,  # Level 6
    # ... continues
]

var is_paused: bool = false
var is_game_over: bool = false
var elapsed_time: float = 0.0
var total_kills: int = 0
var player_level: int = 1

signal game_paused()
signal game_resumed()
signal game_over(stats: Dictionary)

func add_weapon(weapon_type: String, attach_point: Node2D):
    var weapon_scene = WEAPON_SCENES[weapon_type]
    var weapon = weapon_scene.instantiate()
    attach_point.add_child(weapon)
    equipped_weapons.append(weapon)

data/
├── weapons/
│   ├── MachineGun.tres (WeaponData)
│   ├── Railgun.tres
│   └── ...
└── enemies/
    ├── Scout.tres (EnemyData)
    ├── Tank.tres
    └── ...

# scripts/resources/weapon_data.gd
class_name WeaponData
extends Resource

@export var weapon_name: String
@export var damage: int
@export var fire_rate: float
@export var range: float
@export var projectile_scene: PackedScene

# Machine gun script
extends WeaponBase

@export var data: WeaponData

func _fire(target: Node2D):
    var bullet = data.projectile_scene.instantiate()
    bullet.damage = data.damage
    # ...

Player
  ├─ depends on → WeaponManager (to add weapons)
  ├─ depends on → GameState (to report death)
  └─ interacts with → Enemies (collision, damage)

WeaponBase
  ├─ depends on → Enemy group (to query targets)
  └─ spawns → Bullets (projectiles)

Main
  ├─ depends on → GameState (pause, game over)
  ├─ spawns → Player
  ├─ spawns → Enemies (wave system)
  └─ manages → UI (level-up, pause menu)

GameState (Autoload)
  └─ used by → Everything (global state)

Enemy hits Player → Player.take_damage()
                        ↓
Player.current_health <= 0 → Player.die()
                        ↓
emit "died" signal → Main._on_player_died()
                        ↓
GameState.game_over() → pause game → show DeathScreen
                        ↓
DeathScreen displays stats → player clicks Retry → reload scene

# Add to autoload DebugStats
var enemy_count: int
var bullet_count: int
var frame_time: float

const DEBUG_MODE = true
const DEBUG_INVINCIBLE = false
const DEBUG_INFINITE_XP = false

# Use push_warning() for expected issues
if target == null:
    push_warning("Weapon could not find target")

# Use push_error() for unexpected issues
if data == null:
    push_error("WeaponData is null - weapon not configured!")

# Use print() for debug traces (remove before release)
print("Player fired weapon: ", weapon_name)

# Player emits signal
signal health_changed(current: int, max: int)

func take_damage(amount: int):
    current_health -= amount
    health_changed.emit(current_health, max_health)

# HUD listens to signal
func _ready():
    player.health_changed.connect(_on_player_health_changed)

func _on_player_health_changed(current: int, max: int):
    health_bar.value = current / float(max)

# Create resource class
class_name EnemyData
extends Resource

@export var enemy_name: String
@export var max_health: int
@export var move_speed: float

# Use in enemy script
@export var data: EnemyData

func _ready():
    current_health = data.max_health
    speed = data.move_speed

---

## Workflow

### Creating New Systems Bible

1. **Scan codebase:**
   - Use Glob to find all .gd files
   - Identify core systems (player, enemies, weapons, managers)

2. **Ask user about architecture:**
   - Which systems are most important?
   - What are the autoloads/singletons?
   - Are there common patterns to document?

3. **Generate initial bible:**
   - Project architecture and directory structure
   - Core systems documentation (top 3-5 systems)
   - Managers & autoloads section
   - Common patterns

4. **Save to `docs/systems-bible.md`**

---

### Updating Existing Bible

1. **Read current systems bible**

2. **Ask what changed:**
   - New system implemented?
   - System refactored?
   - New pattern introduced?
   - Performance optimization applied?

3. **Update appropriate section:**
   - Add new system documentation
   - Update architecture diagrams
   - Add to changelog

4. **Optionally read code:**
   - Use Read tool to examine implementation
   - Extract key methods, properties, signals

---

## Example Interactions

**User:** "Document the weapon system architecture"

**Skill:**

---

**User:** "Create systems bible for my game"

**Skill:**

---

## Integration with Other Skills

### With `data-refactor`
- After refactoring, update Systems Bible with new data architecture
- Document resource-based patterns

### With `code-reviewer`
- Code quality improvements should update Systems Bible
- Document new patterns introduced

### With `feature-spec-generator`
- Feature specs reference Systems Bible for implementation details
- Systems Bible documents HOW feature was implemented

### With `gdd-generator`
- GDD describes WHAT systems do
- Systems Bible describes HOW they work

---

## Quality Checklist

Before finalizing systems bible:
- ✅ All core systems documented with architecture diagrams
- ✅ Key methods include purpose, parameters, return values
- ✅ Data flows are clear (arrows showing dependencies)
- ✅ Performance considerations noted for hot paths
- ✅ Code examples are accurate (match actual implementation)
- ✅ Directory structure reflects actual project
- ✅ Autoloads/singletons all documented

---

## Example Invocations

User: "Create systems bible"
User: "Document the [system] architecture"
User: "Update systems bible - we refactored the weapon system"
User: "How does the targeting system work?"
User: "Add the new enemy AI system to systems bible"

---

## Workflow Summary

1. Check if `docs/systems-bible.md` exists
2. If new: Scan codebase for core systems, ask about architecture
3. If exists: Read current bible
4. Ask what needs documenting/updating
5. Optionally read code files to extract details
6. Update appropriate section(s) with:
   - Architecture diagrams
   - Key methods and properties
   - Data flows
   - Dependencies
   - Performance notes
7. Add changelog entry
8. Save updated systems bible
9. Confirm changes to user

---

This skill ensures technical knowledge is captured, enabling effective onboarding, debugging, and system evolution.