add blueprints

docs/blueprints/TEMPLATE.md

@@ -0,0 +1,164 @@
+# 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.*