UE5-Modular-Game-Framework/docs/blueprints/TEMPLATE.md

# Blueprint Spec Template v2.0

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

**v2.0 Changes:** Added Section 11 (Manual Implementation Guide) and Section 12 (Build Checklist) for human implementers building Blueprints manually in UE5. Each function now has node-by-node logic with specific UE5 Blueprint node names.

---

# {{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}}

---

## 11. Manual Implementation Guide

> **This section is for a human implementer building the Blueprint manually in UE5.**
> 
> Follow these steps in order. Each function is broken down into specific UE5 Blueprint nodes.
> Variable names in `code font` refer to variables defined in Section 3.
> References to other systems (e.g., `BPC_HealthSystem`) mean "get the component and call its function."

### 11.1 Class Setup

1. Create a new Blueprint Class:
   - Parent Class: `{{ParentClass}}`
   - Name: `{{AssetType}}_{{Name}}`
   - Path: `Content/Framework/{{Category}}/`
2. Add all variables from Section 3 to the Class Defaults.
   - Configuration variables: set `Instance Editable` ✓ and `Expose on Spawn` ✓ (if marked).
   - Internal variables: set to `Private` (no expose).
3. If the class implements interfaces, add them in `Class Settings → Implemented Interfaces`.

### 11.2 Variable Initialization (Construction Script / BeginPlay)

```
Event BeginPlay
  ├─ Set {{VarName}} = {{Default}}   // For each internal variable with a default
  ├─ Get Owner → Cast to {{ExpectedOwnerType}} → Store as CachedOwner
  ├─ Get Component by Class ({{RequiredComponent}}) → Store reference
  │    └─ If NOT valid → Print Warning: "{{Component}} missing on {{Owner}}"
  ├─ [If replicating] Check HasAuthority → if server, initialize replicated vars
  └─ Fire initialization-related dispatchers
```

### 11.3 Function Implementations

#### `{{FunctionName}}`

**Input Pins:** `{{Param1}}` ({{Type1}}), `{{Param2}}` ({{Type2}})
**Output Pins:** `{{ReturnValue}}` ({{ReturnType}})

**Node-by-Node Logic:**
```
[Function: {{FunctionName}}]
  Step 1: {{First thing to do — get a reference, check a condition}}
  Step 2: Branch on {{Condition}}
    True →
      Step 2a: {{Action for true branch}}
      Step 2b: {{Next action}}
    False →
      Step 2c: {{Action for false branch}}
  Step 3: {{Continuation after branch}}
  Step 4: Fire dispatcher: Call {{OnEventName}}({{Params}})
  Step 5: Return {{ReturnValue}}
```

**Nodes Used:** {{List of UE5 Blueprint nodes the implementer should search for}}

**Things to Watch:**
- {{Gotcha 1}}
- {{Gotcha 2}}

#### `{{NextFunction}}`

*(Repeat the same detailed format for every public and protected function)*

### 11.4 Event Dispatcher Bindings

List every dispatcher this system binds TO (inbound listeners) and what to do:

| Bind to Dispatcher (on which system) | Custom Event to Create | What it Does |
|--------------------------------------|------------------------|--------------|
| `{{Component}}.On{{EventName}}` | `On{{EventName}}Handler` | {{Brief logic}} |

### 11.5 Networking Setup (if applicable)

- In `Class Settings`, enable `Replicates` ✓
- For each replicated variable, set `Replication` to `Replicated` or `Replicated Using OnRep_{{VarName}}`
- Create `OnRep_{{VarName}}` functions that fire the same dispatchers as single-player
- Add `Switch HasAuthority` before all state-changing logic
- Add `Run on Server` RPC functions with `Server_` prefix

### 11.6 Quick Node Reference

Common UE5 Blueprint nodes used in this system:
| Node | Where to Find | Used For |
|------|---------------|----------|
| `{{NodeName}}` | Right-click → "{{search term}}" | {{Purpose}} |

---

## 12. Blueprint Build Checklist

Complete these steps in order when implementing this system:

- [ ] Create Blueprint class with correct parent
- [ ] Add all variables with correct types and defaults
- [ ] Implement interface functions (if any)
- [ ] Build `BeginPlay` / `OnPossess` / initialization event
- [ ] Implement each function from Section 4 following the step-by-step guide
- [ ] Create all event dispatchers from Section 5
- [ ] Bind to inbound dispatchers (Section 11.4)
- [ ] Add networking logic (HasAuthority gates, RPCs, RepNotify)
- [ ] Test with validation checklist (Section 9)
- [ ] Place in level or attach to character as appropriate

---

*Template version 2.0 — Includes Manual Implementation Guide for human implementers.*