# Blueprint Spec Template

Use this template for every system file in `docs/blueprints/`. Replace all `{{placeholders}}` with system-specific values.

---

# {{System Number}} — {{System Name}} (`{{AssetType}}_{{Name}}`)

## Purpose
{{1-2 sentences describing what this system does and why it exists.}}

## Dependencies
- **Requires:** {{other systems this directly depends on}}
- **Required By:** {{which systems depend on this}}
- **Engine/Plugin Requirements:** {{e.g. GameplayTags, GASP, DeveloperSettings}}

## Class Info
| Property | Value |
|----------|-------|
| **Parent Class** | `{{ParentClassName}}` |
| **Class Type** | {{Blueprint, BlueprintComponent, Widget, etc.}} |
| **Asset Path** | `Content/Framework/{{Category}}/{{FileName}}` |
| **Implements Interfaces** | `{{I_Interfaces}}` |

---

## 1. Enums

```text
Enum Name: {{E_EnumName}}
(DisplayName = "{{Display Name}}")

Values:
  {{Value1}} = 0    // Description
  {{Value2}} = 1    // Description
  {{Value3}} = 2    // Description
```

*List each enum the system defines or uses.*

---

## 2. Structs

### `{{S_StructName}}`
| Field | Type | Description |
|-------|------|-------------|
| `{{Field1}}` | `{{Type}}` | {{Description}} |
| `{{Field2}}` | `{{Type}}` | {{Description}} |

*List each struct the system defines. Include all fields with types and descriptions.*

---

## 3. Variables

### Configuration (Instance Editable, Expose On Spawn)

| Variable | Type | Default | Category | Description |
|----------|------|---------|----------|-------------|
| `{{VarName}}` | `{{Type}}` | `{{Default}}` | `{{Category}}` | {{Description}} |

### Internal (Private / Protected, No Expose)

| Variable | Type | Default | Category | Description |
|----------|------|---------|----------|-------------|
| `{{VarName}}` | `{{Type}}` | `{{Default}}` | `{{Category}}` | {{Description}} |

### Replicated (if multiplayer)

| Variable | Type | Condition | Description |
|----------|------|-----------|-------------|
| `{{VarName}}` | `{{Type}}` | `{{RepCond}}` | {{Description}} |

---

## 4. Functions

### Public Functions

#### `{{FunctionName}}` → `{{ReturnType}}`
- **Description:** {{What this function does}}
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `{{ParamName}}` | `{{Type}}` | {{Description}} |
- **Blueprint Authority:** {{Client / Server / Multicast / Any}}
- **Flow:** {{brief description of logic flow}}

### Protected / Private Functions

#### `{{FunctionName}}` → `{{ReturnType}}`
- **Description:** {{What this function does}}
- **Parameters:**
  | Param | Type | Description |
  |-------|------|-------------|
  | `{{ParamName}}` | `{{Type}}` | {{Description}} |
- **Flow:** {{brief description of logic flow}}

---

## 5. Event Dispatchers

| Dispatcher | Parameters | Bind Access | Description |
|------------|-----------|-------------|-------------|
| `On{{EventName}}` | `{{Type1}}`, `{{Type2}}` | `{{Public/Private}}` | {{When this fires}} |
| `On{{OtherEvent}}` | `{{Type1}}` | `{{Public/Private}}` | {{When this fires}} |

---

## 6. Overridden Events / Custom Events

### Event: `{{EventName}}`
- **Description:** {{What triggers this event and what it does}}
- **Flow:**
  1. {{Step 1}}
  2. {{Step 2}}
  3. {{Step 3}}

---

## 7. Blueprint Graph Logic Flow

```mermaid
flowchart TD
    A[BeginPlay / Initialize] --> B{Check Condition}
    B -->|True| C[Do Action]
    B -->|False| D[Alternate Path]
    C --> E[Fire Dispatcher]
    D --> F[Log Warning]
```

*Describe the main execution flow using a Mermaid flowchart.*

---

## 8. Communication Matrix

| Who Talks | How | What Is Sent |
|-----------|-----|-------------|
| `{{Source}}` | `{{I_Interface / Dispatcher / Direct}}` | `{{Data}}` |
| `{{Source}}` | `{{I_Interface / Dispatcher / Direct}}` | `{{Data}}` |

*List every other system this one talks to and the mechanism used.*

---

## 9. Validation / Testing Checklist

- [ ] {{Check 1}}
- [ ] {{Check 2}}
- [ ] {{Check 3}}
- [ ] Edge case: {{Edge case description}}

---

## 10. Reuse Notes

- {{Any notes about reusing this component in other contexts}}
- {{Things to watch out for during implementation}}

---

*Template version 1.0 — Reference file for all docs/blueprints/ specifications.*