Refactor GameplayTag documentation and implementation
- Updated references from GI_GameTagRegistry to DA_GameTagRegistry in architecture overview and implementation patterns documentation. - Added new Blueprint specification for GI_StarterGameInstance, detailing its purpose, configuration, and integration pattern. - Introduced DA_GameTagRegistry Blueprint specification, centralizing GameplayTag management and providing functions for tag validation and logging. - Created documentation for the Starter GameInstance, outlining its role in the project setup and how other systems can integrate with it.
This commit is contained in:
Lefteris Notas
@@ -12,7 +12,7 @@ This document catalogs all UE5 engine functions that are C++ only (not exposed t
|
|||||||
|
|
||||||
**Engine Function:** `UGameplayTagsManager::Get().RequestAllGameplayTags()`
|
**Engine Function:** `UGameplayTagsManager::Get().RequestAllGameplayTags()`
|
||||||
**UE5 Node:** Does NOT exist in Blueprint
|
**UE5 Node:** Does NOT exist in Blueprint
|
||||||
**Files Affected:** `01_GI_GameTagRegistry.md`, any system that needs to enumerate all tags
|
**Files Affected:** `01_DA_GameTagRegistry.md`, any system that needs to enumerate all tags
|
||||||
|
|
||||||
**Blueprint Workaround — Data Table Proxy (Multi-Table):**
|
**Blueprint Workaround — Data Table Proxy (Multi-Table):**
|
||||||
|
|
||||||
@@ -72,7 +72,7 @@ OR create a Blueprint Macro Library with a macro that wraps the subsystem lookup
|
|||||||
### 3.1 `OnAssetLoaded` / `BeginPlay` on Data Assets (Not Available)
|
### 3.1 `OnAssetLoaded` / `BeginPlay` on Data Assets (Not Available)
|
||||||
|
|
||||||
**Engine Behavior:** `UPrimaryDataAsset` does not have `BeginPlay`, `Tick`, or event graphs. It's a pure data container.
|
**Engine Behavior:** `UPrimaryDataAsset` does not have `BeginPlay`, `Tick`, or event graphs. It's a pure data container.
|
||||||
**Files Affected:** `01_GI_GameTagRegistry.md`, all DA_* specs
|
**Files Affected:** `01_DA_GameTagRegistry.md`, all DA_* specs
|
||||||
|
|
||||||
**Blueprint Workaround:** Move initialization and validation logic to an owning system:
|
**Blueprint Workaround:** Move initialization and validation logic to an owning system:
|
||||||
|
|
||||||
|
|||||||
@@ -452,7 +452,7 @@ HasActionFlag(Tag: GameplayTag) → Boolean
|
|||||||
4. Populate default `GatingRules` from `DA_StateGatingTable` if assigned
|
4. Populate default `GatingRules` from `DA_StateGatingTable` if assigned
|
||||||
5. Bind to `GI_GameFramework.OnGamePhaseChanged` (for game-phase-gated rules)
|
5. Bind to `GI_GameFramework.OnGamePhaseChanged` (for game-phase-gated rules)
|
||||||
6. Bind to `BPC_HealthSystem.OnDeath` (auto-call `ForceStateChange(Dead)`)
|
6. Bind to `BPC_HealthSystem.OnDeath` (auto-call `ForceStateChange(Dead)`)
|
||||||
7. Register with `GI_GameTagRegistry` for tag-based queries
|
7. Register with `DA_GameTagRegistry` for tag-based queries
|
||||||
8. Bind to `BPC_HealthSystem.OnHealthChanged` → call `EvaluateInjuryState()`
|
8. Bind to `BPC_HealthSystem.OnHealthChanged` → call `EvaluateInjuryState()`
|
||||||
9. Bind to `BPC_StressSystem.OnStressTierChanged` → recalculate heart rate
|
9. Bind to `BPC_StressSystem.OnStressTierChanged` → recalculate heart rate
|
||||||
10. Bind to `BPC_StaminaSystem.OnExhaustionStateChanged` → recalculate heart rate
|
10. Bind to `BPC_StaminaSystem.OnExhaustionStateChanged` → recalculate heart rate
|
||||||
|
|||||||
@@ -88,7 +88,7 @@ This means UI widgets, audio, and effects need **zero changes** for multiplayer
|
|||||||
| `GI_GameFramework` | Server sets GamePhase; clients read | Dispatchers broadcast to all |
|
| `GI_GameFramework` | Server sets GamePhase; clients read | Dispatchers broadcast to all |
|
||||||
| `GM_CoreGameMode` | Server-only; spawns players, routes death | Extends replicated GameMode |
|
| `GM_CoreGameMode` | Server-only; spawns players, routes death | Extends replicated GameMode |
|
||||||
| `GS_CoreGameState` | Server sets all state | **Full replication** — 5 vars with OnRep |
|
| `GS_CoreGameState` | Server sets all state | **Full replication** — 5 vars with OnRep |
|
||||||
| `GI_GameTagRegistry` | Read-only on all | Identical on all clients (ini-based) |
|
| `DA_GameTagRegistry` | Read-only on all | Identical on all clients (ini-based) |
|
||||||
| `FL_GameUtilities` | Static; no state | No replication needed |
|
| `FL_GameUtilities` | Static; no state | No replication needed |
|
||||||
| `I_InterfaceLibrary` | Contracts; no state | No replication needed |
|
| `I_InterfaceLibrary` | Contracts; no state | No replication needed |
|
||||||
| `DA_ItemData` | Read-only config | Identical on all clients |
|
| `DA_ItemData` | Read-only config | Identical on all clients |
|
||||||
|
|||||||
355
docs/blueprints/00-project-setup/GI_StarterGameInstance.md
Normal file
355
docs/blueprints/00-project-setup/GI_StarterGameInstance.md
Normal file
@@ -0,0 +1,355 @@
|
|||||||
|
# GI_StarterGameInstance — Blueprint Specification
|
||||||
|
|
||||||
|
> **Asset Type:** Game Instance (derives from `UGameInstance`)
|
||||||
|
> **UE Version:** 5.5–5.7
|
||||||
|
> **Category:** 00-Project-Setup / Starter
|
||||||
|
> **Build Phase:** Pre-Phase 0 — Project Initialization
|
||||||
|
> **Dependencies:** `DA_GameTagRegistry` (01), 11 per-category Data Tables, GameplayTags plugin
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Purpose
|
||||||
|
|
||||||
|
A minimal, ready-to-use GameInstance Blueprint that serves as the project's **immediate** entry point. Set this as your `Game Instance Class` in Project Settings to get tag validation and framework bootstrapping working on day one. It loads `DA_GameTagRegistry`, validates that all 11 Data Tables are registered, and broadcasts `OnFrameworkReady` when initialization completes.
|
||||||
|
|
||||||
|
**This is intentionally simple.** As the project matures, replace it with `GI_GameFramework` (04) which adds full game-phase management, subsystem ownership, platform init, and save-slot orchestration. All systems that bind to `OnFrameworkReady` will continue working with either GameInstance.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Class Settings
|
||||||
|
|
||||||
|
| Setting | Value |
|
||||||
|
|---------|-------|
|
||||||
|
| **Parent Class** | `GameInstance` |
|
||||||
|
| **Blueprint Type** | Game Instance |
|
||||||
|
| **Asset Path** | `/Game/Framework/Core/GI_StarterGameInstance` |
|
||||||
|
| **Is Abstract** | No |
|
||||||
|
|
||||||
|
**UE5 Setup:** `Project Settings → Maps & Modes → Game Instance Class` → `GI_StarterGameInstance`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Enums
|
||||||
|
|
||||||
|
None. No custom enums are defined in this system.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Structs
|
||||||
|
|
||||||
|
None. No custom structs are defined in this system.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Variables
|
||||||
|
|
||||||
|
### Configuration (Instance Editable)
|
||||||
|
|
||||||
|
| Name | Type | Default | Category | Description |
|
||||||
|
|------|------|---------|----------|-------------|
|
||||||
|
| `TagRegistry` | `DA_GameTagRegistry` (Object Reference) | *Assigned in Class Defaults* | Config | Hard reference to the `DA_GameTagRegistry` Data Asset |
|
||||||
|
| `bValidateTagsOnInit` | `Boolean` | `true` | Config | If true, calls `DA_GameTagRegistry.GetAllRegisteredTags()` during `Event Init` and logs tag count |
|
||||||
|
| `bLogTagsOnInit` | `Boolean` | `false` | Debug | If true, calls `DA_GameTagRegistry.LogAllTags()` after validation (Editor-only; heavy logging) |
|
||||||
|
|
||||||
|
### Internal (Private)
|
||||||
|
|
||||||
|
| Name | Type | Default | Category | Description |
|
||||||
|
|------|------|---------|----------|-------------|
|
||||||
|
| `bFrameworkInitialized` | `Boolean` | `false` | State | Set to `true` after `Event Init` completes successfully |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Functions
|
||||||
|
|
||||||
|
### Public Functions
|
||||||
|
|
||||||
|
#### `GetTagRegistry()` → `DA_GameTagRegistry` *(Blueprint Pure)*
|
||||||
|
|
||||||
|
- **Description:** Returns the cached `TagRegistry` reference. Returns `None` if not yet loaded.
|
||||||
|
- **Parameters:** None
|
||||||
|
- **Flow:**
|
||||||
|
1. Return `TagRegistry` variable
|
||||||
|
|
||||||
|
#### `IsFrameworkReady()` → `Boolean` *(Blueprint Pure)*
|
||||||
|
|
||||||
|
- **Description:** Returns whether the framework has completed initialization. Systems should check this before querying tag-dependent services.
|
||||||
|
- **Parameters:** None
|
||||||
|
- **Flow:**
|
||||||
|
1. Return `bFrameworkInitialized`
|
||||||
|
|
||||||
|
### Protected / Private Functions
|
||||||
|
|
||||||
|
#### `ValidateFrameworkTags()` *(Blueprint Callable, Private)*
|
||||||
|
|
||||||
|
- **Description:** Loads the tag registry, counts registered tags, and logs warnings if zero tags are found. Called automatically during `Event Init`.
|
||||||
|
- **Parameters:** None
|
||||||
|
- **Flow:**
|
||||||
|
1. `IsValid(TagRegistry)`? → False: Print Error "TagRegistry not assigned!" → Return
|
||||||
|
2. Call `TagRegistry.GetAllRegisteredTags()` → `AllTags` (Array\<GameplayTag\>)
|
||||||
|
3. `Array Length(AllTags) == 0`?
|
||||||
|
- True: Print Warning "No Gameplay Tags registered! Check Project Settings → GameplayTags → Gameplay Tag Table List. All 11 Data Tables must be added."
|
||||||
|
- False: Print String "DA_GameTagRegistry initialized: {Array Length} tags registered across 11 Data Tables."
|
||||||
|
4. If `bLogTagsOnInit`: Call `TagRegistry.LogAllTags()`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Event Dispatchers
|
||||||
|
|
||||||
|
| Dispatcher | Parameters | Bind Access | Description |
|
||||||
|
|------------|-----------|-------------|-------------|
|
||||||
|
| `OnFrameworkReady` | — | Public | Fires after `Event Init` completes and tag validation passes. Other systems bind to this to defer initialization until the framework is ready. |
|
||||||
|
| `OnFrameworkInitFailed` | `ErrorReason: String` | Public | Fires if `TagRegistry` is invalid or zero tags are found during init. Systems should handle gracefully — show error UI, disable gameplay. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Overridden Events
|
||||||
|
|
||||||
|
### Event: `Event Init`
|
||||||
|
|
||||||
|
- **Description:** UE5's GameInstance initialization event. Fires once when the game starts, before any level loads. This is where framework bootstrapping happens.
|
||||||
|
- **Flow:**
|
||||||
|
1. Call `Parent: Event Init` (important — don't skip)
|
||||||
|
2. Print String: "GI_StarterGameInstance: Init started"
|
||||||
|
3. `Branch: bValidateTagsOnInit?`
|
||||||
|
- False → Print String "Tag validation skipped (bValidateTagsOnInit = false)"
|
||||||
|
- True → Call `ValidateFrameworkTags()`
|
||||||
|
4. `Branch: IsValid(TagRegistry)?`
|
||||||
|
- False → Print Error "DA_GameTagRegistry reference is invalid!" → Call `OnFrameworkInitFailed("TagRegistry not assigned or invalid")` → Return
|
||||||
|
- True → Continue
|
||||||
|
5. Set `bFrameworkInitialized = true`
|
||||||
|
6. Call `OnFrameworkReady` (broadcast to all bound listeners)
|
||||||
|
7. Print String: "GI_StarterGameInstance: Init complete — OnFrameworkReady broadcast"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Blueprint Graph Logic Flow
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
A[Event Init] --> B[Call Parent: Event Init]
|
||||||
|
B --> C{ bValidateTagsOnInit? }
|
||||||
|
C -->|True| D[Call ValidateFrameworkTags]
|
||||||
|
C -->|False| E[Skip validation]
|
||||||
|
D --> F{ IsValid TagRegistry? }
|
||||||
|
F -->|False| G[Print Error<br>Broadcast OnFrameworkInitFailed]
|
||||||
|
F -->|True| H[Set bFrameworkInitialized = true]
|
||||||
|
H --> I[Broadcast OnFrameworkReady]
|
||||||
|
I --> J[Print 'Init Complete']
|
||||||
|
```
|
||||||
|
|
||||||
|
### ValidateFrameworkTags Flow
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart TD
|
||||||
|
A[ValidateFrameworkTags] --> B{ IsValid TagRegistry? }
|
||||||
|
B -->|False| C[Print Error: TagRegistry not assigned]
|
||||||
|
B -->|True| D[Call GetAllRegisteredTags → AllTags]
|
||||||
|
D --> E{ Array Length == 0? }
|
||||||
|
E -->|True| F[Print Warning: No tags registered]
|
||||||
|
E -->|False| G[Print: N tags registered]
|
||||||
|
G --> H{ bLogTagsOnInit? }
|
||||||
|
H -->|True| I[Call LogAllTags]
|
||||||
|
H -->|False| J[Return]
|
||||||
|
I --> J
|
||||||
|
F --> J
|
||||||
|
C --> J
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Communication Matrix
|
||||||
|
|
||||||
|
| Source | Target | Method | Direction | Data |
|
||||||
|
|--------|--------|--------|-----------|------|
|
||||||
|
| `GI_StarterGameInstance` | `DA_GameTagRegistry` | Direct function call | Outbound | Calls `GetAllRegisteredTags()`, `LogAllTags()`, `ValidateTag()` |
|
||||||
|
| `GI_StarterGameInstance` | All bound systems | `OnFrameworkReady` dispatcher | Outbound broadcast | No data — listeners query `IsFrameworkReady()` |
|
||||||
|
| `GI_StarterGameInstance` | All bound systems | `OnFrameworkInitFailed` dispatcher | Outbound broadcast | `ErrorReason: String` |
|
||||||
|
| Any system | `GI_StarterGameInstance` | `GetGameInstance()` → Cast | Inbound query | Systems call `IsFrameworkReady()` before initialization |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Validation Checklist
|
||||||
|
|
||||||
|
- [ ] `GI_StarterGameInstance` set as `Game Instance Class` in `Project Settings → Maps & Modes`
|
||||||
|
- [ ] `TagRegistry` variable assigned to `DA_GameTagRegistry` Data Asset in Class Defaults
|
||||||
|
- [ ] All 11 Data Tables registered in `Project Settings → GameplayTags → Gameplay Tag Table List`
|
||||||
|
- [ ] On PIE (Play In Editor): output log shows "N tags registered across 11 Data Tables"
|
||||||
|
- [ ] On PIE with `bLogTagsOnInit = true`: all tag names printed to output log
|
||||||
|
- [ ] If `TagRegistry` is unassigned: error prints and `OnFrameworkInitFailed` fires (test by clearing the variable)
|
||||||
|
- [ ] Other systems successfully bind to `OnFrameworkReady` and defer their init
|
||||||
|
- [ ] Edge case: 0 tags in Data Tables → warning prints, `OnFrameworkInitFailed` does NOT fire (empty tables are a warning, not a failure)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Reuse Notes
|
||||||
|
|
||||||
|
- **Replacement path:** When you are ready for the full `GI_GameFramework` (04), simply change the `Game Instance Class` in Project Settings. All systems that bind to `OnFrameworkReady` on either GameInstance will work — `GI_GameFramework` includes the same dispatcher.
|
||||||
|
- **Project-specific init:** Add custom initialization (achievement platform, analytics, save migration) after the `OnFrameworkReady` broadcast in `Event Init`.
|
||||||
|
- **Tag registry is a Data Asset, not a subsystem:** You must manually assign the `TagRegistry` reference in Class Defaults. It is NOT auto-discovered.
|
||||||
|
- **Multi-platform:** On consoles, `Event Init` fires before any level loads — same as PC. No platform-specific code is needed.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Manual Implementation Guide
|
||||||
|
|
||||||
|
> **For human implementer:** Follow these steps to build `GI_StarterGameInstance` in UE5 Blueprints. This is the FIRST Blueprint you should create — it enables tag validation for all other systems.
|
||||||
|
|
||||||
|
### 13.1 Class Setup
|
||||||
|
|
||||||
|
1. Right-click in Content Browser → **Blueprint Class**
|
||||||
|
2. Search for parent class: `GameInstance`
|
||||||
|
3. Name: `GI_StarterGameInstance`
|
||||||
|
4. Save to: `Content/Framework/Core/`
|
||||||
|
5. Open **Project Settings → Maps & Modes** → Set `Game Instance Class` to `GI_StarterGameInstance`
|
||||||
|
|
||||||
|
### 13.2 Variables
|
||||||
|
|
||||||
|
Add to Class Defaults:
|
||||||
|
|
||||||
|
| Variable | Type | Instance Editable | Default | Category |
|
||||||
|
|----------|------|------------------|---------|----------|
|
||||||
|
| `TagRegistry` | `DA_GameTagRegistry` (Object Reference) | ✓ | *Select `DA_GameTagRegistry` asset* | Config |
|
||||||
|
| `bValidateTagsOnInit` | `Boolean` | ✓ | `true` | Config |
|
||||||
|
| `bLogTagsOnInit` | `Boolean` | ✓ | `false` | Debug |
|
||||||
|
| `bFrameworkInitialized` | `Boolean` | ✗ (Private) | `false` | State |
|
||||||
|
|
||||||
|
**⚠️ Important:** For `TagRegistry`, use the type `DA_GameTagRegistry` (your specific Data Asset Blueprint class, NOT the generic `PrimaryDataAsset`). Compile `DA_GameTagRegistry` first so it appears in the type dropdown.
|
||||||
|
|
||||||
|
### 13.3 Event Dispatchers
|
||||||
|
|
||||||
|
Create two Event Dispatchers in the **My Blueprint** panel:
|
||||||
|
|
||||||
|
1. `OnFrameworkReady` — no parameters
|
||||||
|
2. `OnFrameworkInitFailed` — add one input parameter:
|
||||||
|
- `ErrorReason` (String)
|
||||||
|
|
||||||
|
### 13.4 Override Event Init
|
||||||
|
|
||||||
|
1. In the **My Blueprint** panel, hover over **Functions** → click **Override** → select `Event Init`
|
||||||
|
2. Build the following graph:
|
||||||
|
|
||||||
|
```
|
||||||
|
[Event Init]
|
||||||
|
Step 1: Call "Parent: Event Init" (right-click event node → "Add Call to Parent")
|
||||||
|
Step 2: Print String: "GI_StarterGameInstance: Init started"
|
||||||
|
→ Text (Format Text): "GI_StarterGameInstance: Init started"
|
||||||
|
Step 3: Branch (Condition: bValidateTagsOnInit)
|
||||||
|
True → Call ValidateFrameworkTags (see 13.5)
|
||||||
|
False → Print String: "Tag validation skipped (bValidateTagsOnInit = false)"
|
||||||
|
Step 4: IsValid(TagRegistry) → Branch
|
||||||
|
False:
|
||||||
|
→ Print String: "DA_GameTagRegistry reference is invalid!"
|
||||||
|
→ Call OnFrameworkInitFailed (ErrorReason = "TagRegistry not assigned or invalid")
|
||||||
|
→ Return Node
|
||||||
|
True: Continue
|
||||||
|
Step 5: Set bFrameworkInitialized = true
|
||||||
|
Step 6: Call OnFrameworkReady (no params)
|
||||||
|
Step 7: Print String: "GI_StarterGameInstance: Init complete — OnFrameworkReady broadcast"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Nodes to Search:** `Event Init`, `Add Call to Parent`, `Print String`, `Format Text`, `Branch`, `IsValid`, `Set`, `Call OnFrameworkReady`, `Call OnFrameworkInitFailed`
|
||||||
|
|
||||||
|
### 13.5 Implement ValidateFrameworkTags
|
||||||
|
|
||||||
|
Create a new function: **BlueprintCallable**, Private, named `ValidateFrameworkTags`.
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: ValidateFrameworkTags] (BlueprintCallable, Private)
|
||||||
|
Step 1: IsValid(TagRegistry) → Branch
|
||||||
|
False: Print String "TagRegistry not assigned in GI_StarterGameInstance!" → Return
|
||||||
|
True: Continue
|
||||||
|
Step 2: Call TagRegistry → GetAllRegisteredTags() → store in "AllTags" (Array<GameplayTag>)
|
||||||
|
Step 3: Array Length(AllTags) → store in "TagCount" (Integer)
|
||||||
|
Step 4: Branch (Condition: TagCount == 0)
|
||||||
|
True: Print String (Color: Yellow): "WARNING: No Gameplay Tags registered! Check Project Settings → GameplayTags → Gameplay Tag Table List. All 11 Data Tables must be added."
|
||||||
|
False: Print String (Format Text): "DA_GameTagRegistry initialized: {TagCount} tags registered across 11 Data Tables."
|
||||||
|
Step 5: Branch (Condition: bLogTagsOnInit)
|
||||||
|
True: Call TagRegistry → LogAllTags()
|
||||||
|
False: Continue (no action)
|
||||||
|
Step 6: Return
|
||||||
|
```
|
||||||
|
|
||||||
|
**Nodes to Search:** `IsValid`, `GetAllRegisteredTags`, `Array Length`, `Branch`, `Print String`, `Format Text`, `LogAllTags`
|
||||||
|
|
||||||
|
### 13.6 Implement GetTagRegistry
|
||||||
|
|
||||||
|
Create a new function: **BlueprintPure**, Public, named `GetTagRegistry`.
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: GetTagRegistry] → DA_GameTagRegistry (BlueprintPure)
|
||||||
|
Return TagRegistry
|
||||||
|
```
|
||||||
|
|
||||||
|
### 13.7 Implement IsFrameworkReady
|
||||||
|
|
||||||
|
Create a new function: **BlueprintPure**, Public, named `IsFrameworkReady`.
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: IsFrameworkReady] → Boolean (BlueprintPure)
|
||||||
|
Return bFrameworkInitialized
|
||||||
|
```
|
||||||
|
|
||||||
|
### 13.8 How Other Systems Bind to OnFrameworkReady
|
||||||
|
|
||||||
|
In any other Blueprint that needs framework services (tag validation, subsystems, etc.):
|
||||||
|
|
||||||
|
```
|
||||||
|
[Event BeginPlay]
|
||||||
|
Step 1: Get Game Instance → Cast to GI_StarterGameInstance → Store as "GameInstance"
|
||||||
|
Step 2: Branch: IsValid(GameInstance)?
|
||||||
|
True:
|
||||||
|
→ Branch: GameInstance → IsFrameworkReady()?
|
||||||
|
True: Call "OnFrameworkReadyHandler" immediately (already initialized)
|
||||||
|
False: Bind "OnFrameworkReadyHandler" to GameInstance.OnFrameworkReady
|
||||||
|
False: Print Warning "GI_StarterGameInstance not found!"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Custom Event: OnFrameworkReadyHandler**
|
||||||
|
```
|
||||||
|
[Custom Event: OnFrameworkReadyHandler]
|
||||||
|
Step 1: Unbind from GameInstance.OnFrameworkReady (if bound — prevents double-fire)
|
||||||
|
Step 2: ... proceed with system-specific initialization ...
|
||||||
|
```
|
||||||
|
|
||||||
|
### 13.9 Quick Node Reference
|
||||||
|
|
||||||
|
| Node | Where to Find | Used For |
|
||||||
|
|------|---------------|----------|
|
||||||
|
| `Event Init` | Override in My Blueprint → Functions | GameInstance startup |
|
||||||
|
| `Get Game Instance` | Right-click → "Get Game Instance" | Any Blueprint that needs the GameInstance |
|
||||||
|
| `Cast to GI_StarterGameInstance` | Right-click → "Cast to GI_StarterGameInstance" | Type-safe access to framework functions |
|
||||||
|
| `IsValid` | Right-click → "IsValid" | Null-checking object references |
|
||||||
|
| `Bind Event to OnFrameworkReady` | Right-click on dispatcher → "Bind Event" | Deferred initialization |
|
||||||
|
| `Unbind Event from OnFrameworkReady` | Right-click on dispatcher → "Unbind Event" | Clean up after handler fires |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Blueprint Build Checklist
|
||||||
|
|
||||||
|
- [ ] Create `GI_StarterGameInstance` Blueprint (Parent: `GameInstance`)
|
||||||
|
- [ ] Set as `Game Instance Class` in `Project Settings → Maps & Modes`
|
||||||
|
- [ ] Create `DA_GameTagRegistry` Data Asset first (required for `TagRegistry` variable type)
|
||||||
|
- [ ] Add variable `TagRegistry` (type: `DA_GameTagRegistry`) and assign the Data Asset
|
||||||
|
- [ ] Add variable `bValidateTagsOnInit` (Boolean, default `true`)
|
||||||
|
- [ ] Add variable `bLogTagsOnInit` (Boolean, default `false`)
|
||||||
|
- [ ] Add variable `bFrameworkInitialized` (Boolean, default `false`, Private)
|
||||||
|
- [ ] Create Event Dispatcher `OnFrameworkReady` (no params)
|
||||||
|
- [ ] Create Event Dispatcher `OnFrameworkInitFailed` (1 param: `ErrorReason` String)
|
||||||
|
- [ ] Override `Event Init` — add Call to Parent, validation branch, dispatcher broadcasts
|
||||||
|
- [ ] Implement `ValidateFrameworkTags()` — validate registry, count tags, optional log
|
||||||
|
- [ ] Implement `GetTagRegistry()` (BlueprintPure) — return TagRegistry reference
|
||||||
|
- [ ] Implement `IsFrameworkReady()` (BlueprintPure) — return bFrameworkInitialized
|
||||||
|
- [ ] Compile and test: PIE → output log shows "DA_GameTagRegistry initialized: N tags"
|
||||||
|
- [ ] Test error path: clear `TagRegistry` variable → `OnFrameworkInitFailed` fires
|
||||||
|
- [ ] Test with `bLogTagsOnInit = true` → all tags printed to output log
|
||||||
|
- [ ] Verify other systems can bind to `OnFrameworkReady` and defer init correctly
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Multiplayer Networking
|
||||||
|
|
||||||
|
**Replication: None needed.** The GameInstance is a client-only singleton — each client has its own instance. The `DA_GameTagRegistry` Data Asset loads identically from disk on all clients and servers. Event Dispatchers (`OnFrameworkReady`, `OnFrameworkInitFailed`) fire locally on each instance.
|
||||||
|
|
||||||
|
**Authority: N/A.** No runtime state changes. Tag data is read-only configuration.
|
||||||
|
|
||||||
|
**Multiplayer Note:** In a networked game, `Event Init` fires on both server and each client's GameInstance. Tag validation runs independently on each — which is correct, since Data Tables and GameplayTags must be identical across all instances for networked tag replication to function.
|
||||||
402
docs/blueprints/01-core/01_DA_GameTagRegistry.md
Normal file
402
docs/blueprints/01-core/01_DA_GameTagRegistry.md
Normal file
@@ -0,0 +1,402 @@
|
|||||||
|
# DA_GameTagRegistry — Blueprint Specification
|
||||||
|
|
||||||
|
> **Asset Type:** Data Asset (derives from `UPrimaryDataAsset`)
|
||||||
|
> **UE Version:** 5.5–5.7
|
||||||
|
> **Category:** 01-Core / Foundation
|
||||||
|
> **Build Phase:** Phase 0 — Item 1
|
||||||
|
> **Dependencies:** None (this is the first system)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Purpose
|
||||||
|
|
||||||
|
Centralises every `GameplayTag` namespace used across the framework in a single asset. All other systems reference tags from this registry — never raw strings, never `FName` comparisons, never hardcoded booleans for state.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Class Settings
|
||||||
|
|
||||||
|
| Setting | Value |
|
||||||
|
|---------|-------|
|
||||||
|
| **Parent Class** | `UPrimaryDataAsset` |
|
||||||
|
| **Blueprint Type** | Data Asset |
|
||||||
|
| **Asset Path** | `/Game/Framework/Core/DA_GameTagRegistry` |
|
||||||
|
| **Is Abstract** | No |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Enums
|
||||||
|
|
||||||
|
None. This Data Asset uses only **Gameplay Tags** as the canonical state identifiers. No enums are defined here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Structs
|
||||||
|
|
||||||
|
None. The registry is a flat collection of tag declarations.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Variables
|
||||||
|
|
||||||
|
| Name | Type | Category | Instance Editable | Description |
|
||||||
|
|------|------|----------|-------------------|-------------|
|
||||||
|
| `TagNamespace` | `FText` | Documentation | Yes | Human-readable description of the tag namespace (e.g. "Player.State") |
|
||||||
|
| `bIsFrameworkTag` | `bool` | Documentation | Yes | `true` for framework-defined tags, `false` for project-specific overrides |
|
||||||
|
|
||||||
|
**NOTE:** The tag definitions themselves live in the project's `DefaultGameplayTags.ini` file (or via the **Project Settings → Gameplay Tags** editor). This asset provides a centralised **documentation anchor** for those tags. The Blueprint graph does not hold tag data.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Functions
|
||||||
|
|
||||||
|
### 6.1 Blueprint Pure Functions
|
||||||
|
|
||||||
|
| Name | Inputs | Outputs | Category | Description |
|
||||||
|
|------|--------|---------|----------|-------------|
|
||||||
|
| `GetAllRegisteredTags` | — | `Array<FName>` | Query | Reads tags from all registered per-category Data Tables (see Section 14) |
|
||||||
|
| `GetTagDisplayName` | `Tag: FGameplayTag` | `Text` | Query | Returns the human-readable display name via `Get Tag Display Name` node |
|
||||||
|
| `ValidateTag` | `Tag: FGameplayTag` | `Boolean` | Validation | Returns `true` if the tag is valid via `Is Gameplay Tag Valid` node |
|
||||||
|
|
||||||
|
### 6.2 Blueprint Callable Functions
|
||||||
|
|
||||||
|
| Name | Inputs | Outputs | Category | Description |
|
||||||
|
|------|--------|---------|----------|-------------|
|
||||||
|
| `LogAllTags` | — | — | Debug | Prints all tags (from Data Table) to the output log (Editor-only) |
|
||||||
|
| `ExportTagNamespace` | `NamespacePrefix: String` | `String` | Tooling | Exports all tags matching a namespace prefix as a formatted string | |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Event Dispatchers
|
||||||
|
|
||||||
|
None. This Data Asset is passive — it has no runtime events.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Overridden Events
|
||||||
|
|
||||||
|
**Note:** Data Assets do NOT have `BeginPlay`, `Tick`, or `OnAssetLoaded` in Blueprint. All validation logic should be called externally from a GameInstance or Subsystem during initialization.
|
||||||
|
|
||||||
|
### Initialization Pattern (called externally):
|
||||||
|
```
|
||||||
|
[In GI_GameFramework.Init() or BPC_StateManager.BeginPlay:]
|
||||||
|
├─► Load DA_GameTagRegistry (hard reference or Get Data Asset)
|
||||||
|
├─► Call DA_GameTagRegistry.GetAllRegisteredTags()
|
||||||
|
├─► Array Length == 0?
|
||||||
|
│ ├─► Yes → Print Warning: "No tags in registered Data Tables! Framework tags are unregistered."
|
||||||
|
│ └─► No → Log: "N tags registered."
|
||||||
|
└─► Optional: call LogAllTags() for debug output
|
||||||
|
```
|
||||||
|
|
||||||
|
## 9. Blueprint Graph Logic
|
||||||
|
|
||||||
|
### 9.1 GetAllRegisteredTags (Multi-Table Data Table Proxy)
|
||||||
|
|
||||||
|
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestAllGameplayTags()` is C++ only — not exposed to Blueprints. This function uses a **Data Table proxy** with multiple per-category tables. All tables must be registered in `Project Settings → GameplayTags → Gameplay Tag Table List`.
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: GetAllRegisteredTags] → Array<GameplayTag>
|
||||||
|
Step 1: Create empty Array<GameplayTag> → LocalTags
|
||||||
|
Step 2: ForEachLoop over TagDataTables (outer loop):
|
||||||
|
├─► Branch: IsValid(current table)? → False: skip
|
||||||
|
├─► Get Data Table Row Names (current table)
|
||||||
|
└─► ForEachLoop (RowNames) (inner loop):
|
||||||
|
├─► Get Data Table Row → Break GameplayTagTableRow → get "Tag"
|
||||||
|
└─► Add "Tag" to LocalTags
|
||||||
|
Step 3: Return LocalTags
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Change from v1:** The outer loop iterates `TagDataTables` (Array), not a single `TagDataTable`. This enables tags split across multiple CSV files by category.
|
||||||
|
|
||||||
|
### 9.2 ValidateTag
|
||||||
|
|
||||||
|
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestGameplayTag()` is not a direct Blueprint node. Use `Is Gameplay Tag Valid` instead.
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: ValidateTag(Tag)] → Boolean
|
||||||
|
Step 1: Is Gameplay Tag Valid (Tag)
|
||||||
|
├─► True → Return true
|
||||||
|
└─► False → Print Warning: "Invalid Tag: {Get Tag Name(Tag)}" → Return false
|
||||||
|
```
|
||||||
|
|
||||||
|
**Node Search:** `Is Gameplay Tag Valid`, `Get Tag Name`
|
||||||
|
|
||||||
|
### 9.3 GetTagDisplayName
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: GetTagDisplayName(Tag)] → Text
|
||||||
|
Step 1: Get Tag Display Name (Tag) → Return
|
||||||
|
```
|
||||||
|
|
||||||
|
**Node Search:** `Get Tag Display Name` (Blueprint pure node, available)
|
||||||
|
|
||||||
|
### 9.4 LogAllTags
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: LogAllTags] (Blueprint Callable)
|
||||||
|
Step 1: GetAllRegisteredTags() → Store in LocalTags
|
||||||
|
Step 2: ForEachLoop (LocalTags):
|
||||||
|
├─► Get Tag Name → ToString → Print String
|
||||||
|
Step 3: Print String: "Total tags: {Array Length(LocalTags)}"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9.5 ExportTagNamespace(Prefix: String) → String
|
||||||
|
|
||||||
|
```
|
||||||
|
[Function: ExportTagNamespace]
|
||||||
|
Step 1: GetAllRegisteredTags() → LocalTags
|
||||||
|
Step 2: Create empty String → Output
|
||||||
|
Step 3: ForEachLoop (LocalTags):
|
||||||
|
├─► Get Tag Name → ToString → TagString
|
||||||
|
├─► Branch: Does TagString start with Prefix?
|
||||||
|
│ True → Append TagString + "\n" to Output
|
||||||
|
└─► Continue
|
||||||
|
Step 4: Return Output
|
||||||
|
```
|
||||||
|
[OnAssetLoaded]
|
||||||
|
└─► Call GetAllRegisteredTags()
|
||||||
|
└─► Length == 0?
|
||||||
|
├─► Yes → Print Warning: "No Gameplay Tags registered! /Game/Framework/Core/DA_GameTagRegistry is empty."
|
||||||
|
└─► No → Log: "N tags registered."
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9.2 Validation Function Logic (ValidateTag)
|
||||||
|
|
||||||
|
```
|
||||||
|
[ValidateTag(Tag)]
|
||||||
|
└─► Use GameplayTag::RequestGameplayTag(Tag.TagName)
|
||||||
|
└─► IsValid?
|
||||||
|
├─► Yes → return true
|
||||||
|
└─► No → Print Warning: "Invalid Tag: {Tag}" → return false
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Tag Namespace Reference (Framework Canonical)
|
||||||
|
|
||||||
|
All framework-level tags are defined in per-category Data Tables (CSV format, Row Structure: `GameplayTagTableRow`). These tables are registered in `Project Settings → GameplayTags → Gameplay Tag Table List`. The engine's `UGameplayTagsManager` merges all tables into one master list.
|
||||||
|
|
||||||
|
| Data Table | Namespaces Covered | Example Tags |
|
||||||
|
|------------|-------------------|--------------|
|
||||||
|
| `DT_Tags_Player` | `Framework.Player.State.*`, `*.Stress.*`, `*.Posture.*`, `*.Movement.*`, `*.Camera.*`, `*.Body.*`, `*.Overlay.*`, `*.Vitals.*` | Alive, Dead, Hidden, Sprinting, Crouching, Aiming, FullBody, Blood |
|
||||||
|
| `DT_Tags_Interaction` | `Framework.Interaction.Type.*`, `*.Context.*`, `*.Prompt.*`, `*.HidingSpot.*`, `*.Traversal.*`, `*.Door.*` | Pickup, Door, Container, Locked, OneShot, Vault, Mantle |
|
||||||
|
| `DT_Tags_Item` | `Framework.Item.Type.*`, `*.Slot.*`, `*.Rarity.*`, `*.Context.*` | Weapon, KeyItem, PrimaryWeapon, Legendary, Stackable |
|
||||||
|
| `DT_Tags_Narrative` | `Game.Narrative.Flag.*`, `*.Phase.*`, `*.Choice.*`, `*.Ending.*`, `*.Trial.*`, `*.Cutscene.*`, `*.Lore.*`, `Framework.Objective.*` | Chapter1Complete, Act2, GoodEnding, HospitalEscape, Intro |
|
||||||
|
| `DT_Tags_AI` | `Framework.AI.Alert.*`, `*.Archetype.*`, `*.Stimulus.*`, `*.Behavior.*`, `*.Memory.*` | Alerted, Stalker, Hearing, Aggressive, LastKnownLocation |
|
||||||
|
| `DT_Tags_Save` | `Framework.Save.*`, `*.DeathSpace.*`, `*.Checkpoint.*`, `*.Respawn.*`, `*.RunHistory.*` | Checkpoint, HardSave, Slot.1, Entered, Active, Reached, Start, Death |
|
||||||
|
| `DT_Tags_Environment` | `Game.Environment.Atmosphere.*`, `*.Scare.*`, `*.Light.*`, `*.Pacing.*`, `*.Performance.*` | Tense, MirrorJump, Flicker, Combat, High |
|
||||||
|
| `DT_Tags_Combat` | `Framework.Combat.Damage.*`, `*.Weapon.*`, `*.Ammo.*`, `*.FireMode.*`, `*.HitReaction.*`, `*.Feedback.*`, `*.Shield.*` | Physical, Firearm, Pistol, Flinch, HitMarker, Active |
|
||||||
|
| `DT_Tags_State` | `Framework.State.Action.*`, `*.Overlay.*`, `*.Vital.*`, `*.Gating.*` | Fire, Sprint, Menu, Health, BlockSprint |
|
||||||
|
| `DT_Tags_Audio` | `Framework.Audio.Bus.*`, `*.Room.*`, `*.Parameter.*`, `*.Surface.*` | SFX, Small, HeartRate, Concrete |
|
||||||
|
| `DT_Tags_Achievement` | `Game.Achievement.*` | FirstBlood, Survivor, Pacifist, Ghost, Collector, LoreMaster, TrueEnding, SpeedRunner, WeaponsMaster, Completionist |
|
||||||
|
|
||||||
|
**Usage Rule:** All systems must add the prefix `Framework.` to framework tags in code comments. Project-specific tags use `Game.` prefix. Example: `Framework.Item.Type.Weapon` vs `Game.Narrative.Flag.BasementDoorOpened`.
|
||||||
|
|
||||||
|
**CSV Format:** Each Data Table CSV uses columns: `Name,Tag,DevComment`. Name is a unique row identifier. Tag is the full gameplay tag string. DevComment explains the tag's purpose.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Communication Matrix
|
||||||
|
|
||||||
|
| Target System | Method | Direction | Data |
|
||||||
|
|---------------|--------|-----------|------|
|
||||||
|
| All other systems | `GameplayTag` comparisons | Read-only | Framework-defined tag values |
|
||||||
|
|
||||||
|
This asset does not talk to other systems directly. All communication is passive — other systems read tag values from the project's tag table.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12. Validation Checklist
|
||||||
|
|
||||||
|
- [ ] All namespace prefixes documented in the Data Asset's `TagNamespace` text field
|
||||||
|
- [ ] `bIsFrameworkTag` set to `true` for framework namespaces
|
||||||
|
- [ ] At least one project-specific tag exists (e.g. `Game.Narrative.Flag.PrologueComplete`) to validate the workflow
|
||||||
|
- [ ] `DefaultGameplayTags.ini` contains ALL documented tags
|
||||||
|
- [ ] No duplicate tag names across namespaces
|
||||||
|
- [ ] No raw string comparisons exist in any other system (all must use `HasTag` / `MatchesTag`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 13. Reuse Notes
|
||||||
|
|
||||||
|
- The `Game.` namespace is reserved for **project-specific** tags and is empty in the framework distribution.
|
||||||
|
- To add new tags: edit `DefaultGameplayTags.ini` or use the **Gameplay Tags** editor under **Project Settings**.
|
||||||
|
- The Data Asset is purely documentary — the real tag data lives in the project's tag table. This file exists so systems have a single place to look up "what tags exist in the framework" without reading the `.ini` file directly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 14. Manual Implementation Guide
|
||||||
|
|
||||||
|
> **For human implementer:** Follow these steps to build `DA_GameTagRegistry` in UE5 Blueprints.
|
||||||
|
> **⚠️ UE5 BP Limitation:** `UGameplayTagsManager::RequestAllGameplayTags()` is C++ only. This implementation uses an **Array of Data Tables** (11 per-category tables) as the 100% Blueprint workaround. All tables must be registered in `Project Settings → GameplayTags → Gameplay Tag Table List`.
|
||||||
|
|
||||||
|
### 14.0 Prerequisite: Create the Per-Category Data Tables
|
||||||
|
|
||||||
|
Before implementing the Data Asset, create **11 Data Tables**, one per category. Each follows the same format:
|
||||||
|
|
||||||
|
**Format:** Data Table with Row Structure = `GameplayTagTableRow`
|
||||||
|
**CSV Columns:** `Name,Tag,DevComment`
|
||||||
|
**Location in docs:** `docs/blueprints/01-core/data-tables/DT_Tags_*.csv`
|
||||||
|
**Location in UE5:** `Content/Framework/Core/DataTables/DT_Tags_*`
|
||||||
|
|
||||||
|
1. For each category, right-click in Content Browser → **Miscellaneous → Data Table**
|
||||||
|
2. Row Structure: `GameplayTagTableRow`
|
||||||
|
3. Name: `DT_Tags_{Category}` (e.g., `DT_Tags_Player`)
|
||||||
|
4. Import the corresponding CSV file (Right-click Data Table → Import → CSV)
|
||||||
|
5. **Critical:** Go to `Project Settings → GameplayTags → Gameplay Tag Table List` → click `+` 11 times → assign each table to a slot
|
||||||
|
- This auto-registers ALL tags with the engine's tag manager.
|
||||||
|
|
||||||
|
### 14.1 Class Setup
|
||||||
|
|
||||||
|
1. Right-click in Content Browser → **Miscellaneous → Data Asset**
|
||||||
|
2. Select parent class: `PrimaryDataAsset`
|
||||||
|
3. Name: `DA_GameTagRegistry`
|
||||||
|
4. Save to: `Content/Framework/Core/`
|
||||||
|
|
||||||
|
### 14.2 Variables
|
||||||
|
|
||||||
|
Add to Class Defaults:
|
||||||
|
| Variable | Type | Instance Editable | Default | Category |
|
||||||
|
|----------|------|------------------|---------|----------|
|
||||||
|
| `TagNamespace` | `Text` | ✓ | *"Framework tag namespace documentation"* | Documentation |
|
||||||
|
| `bIsFrameworkTag` | `Boolean` | ✓ | `true` | Documentation |
|
||||||
|
| `TagDataTables` | `Array<Data Table Object Reference>` | ✓ | [DT_Tags_Player, DT_Tags_Interaction, DT_Tags_Item, DT_Tags_Narrative, DT_Tags_AI, DT_Tags_Save, DT_Tags_Environment, DT_Tags_Combat, DT_Tags_State, DT_Tags_Audio, DT_Tags_Achievement] | Config |
|
||||||
|
|
||||||
|
**⚠️ Multi-Table Design:** Tags are split into 11 per-category Data Tables (see Section 10). In UE5 `Project Settings → GameplayTags → Gameplay Tag Table List`, add ALL 11 tables. The engine's `UGameplayTagsManager` merges them automatically.
|
||||||
|
|
||||||
|
### 14.3 Function Implementations
|
||||||
|
|
||||||
|
#### `GetAllRegisteredTags()` → `Array<GameplayTag>` *(Blueprint Pure)*
|
||||||
|
|
||||||
|
**Purpose:** Returns all tags from ALL registered Data Tables. Uses an outer loop over `TagDataTables` array and inner loop over each table's rows.
|
||||||
|
|
||||||
|
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestAllGameplayTags()` is C++ only — not exposed to Blueprints. This function uses the Data Table proxy approach with multiple tables.
|
||||||
|
|
||||||
|
**Node-by-Node Logic:**
|
||||||
|
```
|
||||||
|
[Function: GetAllRegisteredTags] (Pure, no execution pins)
|
||||||
|
Step 1: Create empty Array<GameplayTag> → LocalTags
|
||||||
|
Step 2: ForEachLoop over TagDataTables array (outer loop):
|
||||||
|
├─► Array Element = current Data Table
|
||||||
|
├─► Branch: IsValid(current table)?
|
||||||
|
│ False → Skip to next table
|
||||||
|
│ True → Continue
|
||||||
|
├─► Get Data Table Row Names (current table) → returns Array<Name>
|
||||||
|
└─► ForEachLoop over RowNames (inner loop):
|
||||||
|
├─► Get Data Table Row (current table, Array Element)
|
||||||
|
│ → Struct Pin: Break GameplayTagTableRow
|
||||||
|
│ → Get "Tag" field (type: GameplayTag)
|
||||||
|
└─► Add "Tag" to LocalTags array
|
||||||
|
Step 3: Return LocalTags
|
||||||
|
```
|
||||||
|
|
||||||
|
**Nodes to Search:** `ForEachLoop` (outer over TagDataTables), `ForEachLoop` (inner over row names), `Get Data Table Row Names`, `Get Data Table Row`, `Break GameplayTagTableRow`, `Add`, `Array`, `IsValid`
|
||||||
|
|
||||||
|
**⚠️ Note:** If your UE version doesn't support loops in Pure functions, make this **BlueprintCallable** (impure) instead.
|
||||||
|
|
||||||
|
#### `GetTagDisplayName(Tag: GameplayTag)` → `Text` *(Blueprint Pure)*
|
||||||
|
|
||||||
|
**Node-by-Node Logic:**
|
||||||
|
```
|
||||||
|
[Function: GetTagDisplayName]
|
||||||
|
Input Tag → Get Tag Display Name (Tag) → Return
|
||||||
|
```
|
||||||
|
|
||||||
|
**Node Search:** `Get Tag Display Name` — this IS available in Blueprint (part of GameplayTags plugin).
|
||||||
|
|
||||||
|
#### `ValidateTag(Tag: GameplayTag)` → `Boolean` *(Blueprint Pure)*
|
||||||
|
|
||||||
|
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestGameplayTag()` is not directly available in BP. Use `Is Gameplay Tag Valid` instead.
|
||||||
|
|
||||||
|
**Node-by-Node Logic:**
|
||||||
|
```
|
||||||
|
[Function: ValidateTag]
|
||||||
|
Step 1: Is Gameplay Tag Valid (Tag)
|
||||||
|
├─► True → Return true
|
||||||
|
└─► False → Print Warning: "Invalid Tag: " + Get Tag Name(Tag) → Return false
|
||||||
|
```
|
||||||
|
|
||||||
|
**Node Search:** `Is Gameplay Tag Valid`, `Get Tag Name`
|
||||||
|
|
||||||
|
**⚠️ Note:** `Is Gameplay Tag Valid` returns true only if the tag is registered in the engine's tag table (which the 11 Data Tables populate via Project Settings). Tags NOT in any registered table will return false.
|
||||||
|
|
||||||
|
#### `LogAllTags()` → *(void)* *(Blueprint Callable)*
|
||||||
|
|
||||||
|
**Editor Only.** Prints all tags from all Data Tables to the output log.
|
||||||
|
|
||||||
|
**Node-by-Node Logic:**
|
||||||
|
```
|
||||||
|
[Function: LogAllTags]
|
||||||
|
Step 1: Call GetAllRegisteredTags() → LocalTags
|
||||||
|
Step 2: ForEachLoop (LocalTags):
|
||||||
|
├─► Name (Array Element) → ToString → Print String
|
||||||
|
Step 3: Print String: "Total tags across all tables: " + Array Length(LocalTags)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### `ExportTagNamespace(NamespacePrefix: String)` → `String` *(Blueprint Callable)*
|
||||||
|
|
||||||
|
**Node-by-Node Logic:**
|
||||||
|
```
|
||||||
|
[Function: ExportTagNamespace]
|
||||||
|
Step 1: Call GetAllRegisteredTags() → LocalTags
|
||||||
|
Step 2: Create String variable → Output = ""
|
||||||
|
Step 3: ForEachLoop (LocalTags):
|
||||||
|
├─► (Array Element) → ToString → TagString
|
||||||
|
├─► Branch: Does TagString start with NamespacePrefix?
|
||||||
|
│ True → Append TagString + "\n" to Output (use "Append" or "Build String")
|
||||||
|
└─► Continue
|
||||||
|
Step 4: Return Output
|
||||||
|
```
|
||||||
|
|
||||||
|
### 14.4 External Initialization
|
||||||
|
|
||||||
|
Since Data Assets have no `BeginPlay`, call validation from your GameInstance or StateManager:
|
||||||
|
|
||||||
|
**In `GI_StarterGameInstance.Init()` or `GI_GameFramework.Init()`:**
|
||||||
|
```
|
||||||
|
Step 1: Get DA_GameTagRegistry (hard reference or Load Asset)
|
||||||
|
Step 2: Call DA_GameTagRegistry.GetAllRegisteredTags() → LocalTags
|
||||||
|
Step 3: Branch: Array Length(LocalTags) == 0
|
||||||
|
├─► True → Print Warning: "No tags in registered Data Tables!"
|
||||||
|
└─► False → Print String: "N tags registered: " + Array Length
|
||||||
|
Step 4: [Debug builds only] Call DA_GameTagRegistry.LogAllTags()
|
||||||
|
```
|
||||||
|
|
||||||
|
### 14.5 Networking
|
||||||
|
|
||||||
|
No replication needed. This is a read-only Data Asset with a read-only Data Table reference. All clients load identical copies from disk.
|
||||||
|
|
||||||
|
### 14.6 Blueprint Build Checklist
|
||||||
|
|
||||||
|
- [ ] Create 11 Data Tables with Row Structure `GameplayTagTableRow`:
|
||||||
|
- [ ] `DT_Tags_Player` — Player state, stress, posture, movement, camera, body, vitals
|
||||||
|
- [ ] `DT_Tags_Interaction` — Interaction types, contexts, prompts, hiding spots, traversal, doors
|
||||||
|
- [ ] `DT_Tags_Item` — Item types, slots, rarities, contexts
|
||||||
|
- [ ] `DT_Tags_Narrative` — Flags, phases, choices, endings, trials, cutscenes, lore, objectives
|
||||||
|
- [ ] `DT_Tags_AI` — Alert levels, archetypes, stimuli, behaviors, memory
|
||||||
|
- [ ] `DT_Tags_Save` — Save types, death space, checkpoints, respawn
|
||||||
|
- [ ] `DT_Tags_Environment` — Atmosphere, scares, lighting, pacing, performance
|
||||||
|
- [ ] `DT_Tags_Combat` — Damage types, weapons, ammo, fire modes, hit reactions, shield
|
||||||
|
- [ ] `DT_Tags_State` — Action states, overlay states, vitals, gating
|
||||||
|
- [ ] `DT_Tags_Audio` — Audio buses, room acoustics, parameters, surfaces
|
||||||
|
- [ ] `DT_Tags_Achievement` — Achievement identifiers
|
||||||
|
- [ ] Add ALL 11 tables to `Project Settings → GameplayTags → Gameplay Tag Table List`
|
||||||
|
- [ ] Create Data Asset: `DA_GameTagRegistry` (Parent: `PrimaryDataAsset`)
|
||||||
|
- [ ] Add variables: `TagNamespace` (Text), `bIsFrameworkTag` (Boolean), `TagDataTables` (Array<Data Table> — populate with all 11 tables)
|
||||||
|
- [ ] Implement `GetAllRegisteredTags` with OUTER loop over TagDataTables + INNER loop over row names
|
||||||
|
- [ ] Implement `GetTagDisplayName` using `Get Tag Display Name` node
|
||||||
|
- [ ] Implement `ValidateTag` using `Is Gameplay Tag Valid` node
|
||||||
|
- [ ] Implement `LogAllTags` (editor-only, prints tags from all tables)
|
||||||
|
- [ ] Implement `ExportTagNamespace` (string prefix filtering across all tables)
|
||||||
|
- [ ] Add external initialization call from `GI_StarterGameInstance.Init()` or `GI_GameFramework.Init()`
|
||||||
|
- [ ] Verify: all tags from Section 10 exist in the appropriate Data Table
|
||||||
|
- [ ] Verify: `ValidateTag` returns true for tags in any registered table, false for unregistered
|
||||||
|
- [ ] Verify: `GetAllRegisteredTags` returns ALL tags merged from all tables
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 15. Multiplayer Networking
|
||||||
|
|
||||||
|
**Replication: None needed.** This Data Asset is read-only configuration. All clients load identical copies from disk. GameplayTag data lives in `DefaultGameplayTags.ini` which is identical on all instances.
|
||||||
|
|
||||||
|
**Authority: N/A.** No runtime state changes.
|
||||||
@@ -1,402 +1,19 @@
|
|||||||
# GI_GameTagRegistry — Blueprint Specification
|
# RENAMED — See `01_DA_GameTagRegistry.md`
|
||||||
|
|
||||||
> **Asset Type:** Data Asset (derives from `UPrimaryDataAsset`)
|
> **This file has been renamed.** The system is now `DA_GameTagRegistry` (Data Asset prefix, `UPrimaryDataAsset` parent), not `GI_GameTagRegistry` (Game Instance prefix).
|
||||||
> **UE Version:** 5.5–5.7
|
|
||||||
> **Category:** 01-Core / Foundation
|
|
||||||
> **Build Phase:** Phase 0 — Item 1
|
|
||||||
> **Dependencies:** None (this is the first system)
|
|
||||||
|
|
||||||
---
|
## Why the rename?
|
||||||
|
|
||||||
## 1. Purpose
|
The `GI_` prefix implies a `GameInstance` class, but this system is architecturally a **Data Asset** — it has no lifecycle events (`BeginPlay`, `Tick`), no runtime state, and is loaded as a read-only configuration asset. The framework already has `GI_GameFramework` (#04) as the project's sole GameInstance class.
|
||||||
|
|
||||||
Centralises every `GameplayTag` namespace used across the framework in a single asset. All other systems reference tags from this registry — never raw strings, never `FName` comparisons, never hardcoded booleans for state.
|
Additionally, the new [`GI_StarterGameInstance`](../00-project-setup/GI_StarterGameInstance.md) (00-project-setup) provides the actual GameInstance entry point that loads and validates `DA_GameTagRegistry` during `Event Init`.
|
||||||
|
|
||||||
---
|
## Migration
|
||||||
|
|
||||||
## 2. Class Settings
|
If you were referencing this file:
|
||||||
|
- **Old path:** `docs/blueprints/01-core/01_GI_GameTagRegistry.md`
|
||||||
|
- **New path:** [`docs/blueprints/01-core/01_DA_GameTagRegistry.md`](01_DA_GameTagRegistry.md)
|
||||||
|
- **Old asset name:** `GI_GameTagRegistry` → **New asset name:** `DA_GameTagRegistry`
|
||||||
|
- **Old asset path:** `/Game/Framework/Core/DA_GameTagRegistry` (asset path was already correct)
|
||||||
|
|
||||||
| Setting | Value |
|
All framework documentation has been updated to use `DA_GameTagRegistry`. No functionality has changed — only the prefix was corrected.
|
||||||
|---------|-------|
|
|
||||||
| **Parent Class** | `UPrimaryDataAsset` |
|
|
||||||
| **Blueprint Type** | Data Asset |
|
|
||||||
| **Asset Path** | `/Game/Framework/Core/DA_GameTagRegistry` |
|
|
||||||
| **Is Abstract** | No |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Enums
|
|
||||||
|
|
||||||
None. This Data Asset uses only **Gameplay Tags** as the canonical state identifiers. No enums are defined here.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Structs
|
|
||||||
|
|
||||||
None. The registry is a flat collection of tag declarations.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Variables
|
|
||||||
|
|
||||||
| Name | Type | Category | Instance Editable | Description |
|
|
||||||
|------|------|----------|-------------------|-------------|
|
|
||||||
| `TagNamespace` | `FText` | Documentation | Yes | Human-readable description of the tag namespace (e.g. "Player.State") |
|
|
||||||
| `bIsFrameworkTag` | `bool` | Documentation | Yes | `true` for framework-defined tags, `false` for project-specific overrides |
|
|
||||||
|
|
||||||
**NOTE:** The tag definitions themselves live in the project's `DefaultGameplayTags.ini` file (or via the **Project Settings → Gameplay Tags** editor). This asset provides a centralised **documentation anchor** for those tags. The Blueprint graph does not hold tag data.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. Functions
|
|
||||||
|
|
||||||
### 6.1 Blueprint Pure Functions
|
|
||||||
|
|
||||||
| Name | Inputs | Outputs | Category | Description |
|
|
||||||
|------|--------|---------|----------|-------------|
|
|
||||||
| `GetAllRegisteredTags` | — | `Array<FName>` | Query | Reads tags from all registered per-category Data Tables (see Section 14) |
|
|
||||||
| `GetTagDisplayName` | `Tag: FGameplayTag` | `Text` | Query | Returns the human-readable display name via `Get Tag Display Name` node |
|
|
||||||
| `ValidateTag` | `Tag: FGameplayTag` | `Boolean` | Validation | Returns `true` if the tag is valid via `Is Gameplay Tag Valid` node |
|
|
||||||
|
|
||||||
### 6.2 Blueprint Callable Functions
|
|
||||||
|
|
||||||
| Name | Inputs | Outputs | Category | Description |
|
|
||||||
|------|--------|---------|----------|-------------|
|
|
||||||
| `LogAllTags` | — | — | Debug | Prints all tags (from Data Table) to the output log (Editor-only) |
|
|
||||||
| `ExportTagNamespace` | `NamespacePrefix: String` | `String` | Tooling | Exports all tags matching a namespace prefix as a formatted string | |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. Event Dispatchers
|
|
||||||
|
|
||||||
None. This Data Asset is passive — it has no runtime events.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. Overridden Events
|
|
||||||
|
|
||||||
**Note:** Data Assets do NOT have `BeginPlay`, `Tick`, or `OnAssetLoaded` in Blueprint. All validation logic should be called externally from a GameInstance or Subsystem during initialization.
|
|
||||||
|
|
||||||
### Initialization Pattern (called externally):
|
|
||||||
```
|
|
||||||
[In GI_GameFramework.Init() or BPC_StateManager.BeginPlay:]
|
|
||||||
├─► Load DA_GameTagRegistry (hard reference or Get Data Asset)
|
|
||||||
├─► Call DA_GameTagRegistry.GetAllRegisteredTags()
|
|
||||||
├─► Array Length == 0?
|
|
||||||
│ ├─► Yes → Print Warning: "No tags in registered Data Tables! Framework tags are unregistered."
|
|
||||||
│ └─► No → Log: "N tags registered."
|
|
||||||
└─► Optional: call LogAllTags() for debug output
|
|
||||||
```
|
|
||||||
|
|
||||||
## 9. Blueprint Graph Logic
|
|
||||||
|
|
||||||
### 9.1 GetAllRegisteredTags (Multi-Table Data Table Proxy)
|
|
||||||
|
|
||||||
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestAllGameplayTags()` is C++ only — not exposed to Blueprints. This function uses a **Data Table proxy** with multiple per-category tables. All tables must be registered in `Project Settings → GameplayTags → Gameplay Tag Table List`.
|
|
||||||
|
|
||||||
```
|
|
||||||
[Function: GetAllRegisteredTags] → Array<GameplayTag>
|
|
||||||
Step 1: Create empty Array<GameplayTag> → LocalTags
|
|
||||||
Step 2: ForEachLoop over TagDataTables (outer loop):
|
|
||||||
├─► Branch: IsValid(current table)? → False: skip
|
|
||||||
├─► Get Data Table Row Names (current table)
|
|
||||||
└─► ForEachLoop (RowNames) (inner loop):
|
|
||||||
├─► Get Data Table Row → Break GameplayTagTableRow → get "Tag"
|
|
||||||
└─► Add "Tag" to LocalTags
|
|
||||||
Step 3: Return LocalTags
|
|
||||||
```
|
|
||||||
|
|
||||||
**Key Change from v1:** The outer loop iterates `TagDataTables` (Array), not a single `TagDataTable`. This enables tags split across multiple CSV files by category.
|
|
||||||
|
|
||||||
### 9.2 ValidateTag
|
|
||||||
|
|
||||||
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestGameplayTag()` is not a direct Blueprint node. Use `Is Gameplay Tag Valid` instead.
|
|
||||||
|
|
||||||
```
|
|
||||||
[Function: ValidateTag(Tag)] → Boolean
|
|
||||||
Step 1: Is Gameplay Tag Valid (Tag)
|
|
||||||
├─► True → Return true
|
|
||||||
└─► False → Print Warning: "Invalid Tag: {Get Tag Name(Tag)}" → Return false
|
|
||||||
```
|
|
||||||
|
|
||||||
**Node Search:** `Is Gameplay Tag Valid`, `Get Tag Name`
|
|
||||||
|
|
||||||
### 9.3 GetTagDisplayName
|
|
||||||
|
|
||||||
```
|
|
||||||
[Function: GetTagDisplayName(Tag)] → Text
|
|
||||||
Step 1: Get Tag Display Name (Tag) → Return
|
|
||||||
```
|
|
||||||
|
|
||||||
**Node Search:** `Get Tag Display Name` (Blueprint pure node, available)
|
|
||||||
|
|
||||||
### 9.4 LogAllTags
|
|
||||||
|
|
||||||
```
|
|
||||||
[Function: LogAllTags] (Blueprint Callable)
|
|
||||||
Step 1: GetAllRegisteredTags() → Store in LocalTags
|
|
||||||
Step 2: ForEachLoop (LocalTags):
|
|
||||||
├─► Get Tag Name → ToString → Print String
|
|
||||||
Step 3: Print String: "Total tags: {Array Length(LocalTags)}"
|
|
||||||
```
|
|
||||||
|
|
||||||
### 9.5 ExportTagNamespace(Prefix: String) → String
|
|
||||||
|
|
||||||
```
|
|
||||||
[Function: ExportTagNamespace]
|
|
||||||
Step 1: GetAllRegisteredTags() → LocalTags
|
|
||||||
Step 2: Create empty String → Output
|
|
||||||
Step 3: ForEachLoop (LocalTags):
|
|
||||||
├─► Get Tag Name → ToString → TagString
|
|
||||||
├─► Branch: Does TagString start with Prefix?
|
|
||||||
│ True → Append TagString + "\n" to Output
|
|
||||||
└─► Continue
|
|
||||||
Step 4: Return Output
|
|
||||||
```
|
|
||||||
[OnAssetLoaded]
|
|
||||||
└─► Call GetAllRegisteredTags()
|
|
||||||
└─► Length == 0?
|
|
||||||
├─► Yes → Print Warning: "No Gameplay Tags registered! /Game/Framework/Core/DA_GameTagRegistry is empty."
|
|
||||||
└─► No → Log: "N tags registered."
|
|
||||||
```
|
|
||||||
|
|
||||||
### 9.2 Validation Function Logic (ValidateTag)
|
|
||||||
|
|
||||||
```
|
|
||||||
[ValidateTag(Tag)]
|
|
||||||
└─► Use GameplayTag::RequestGameplayTag(Tag.TagName)
|
|
||||||
└─► IsValid?
|
|
||||||
├─► Yes → return true
|
|
||||||
└─► No → Print Warning: "Invalid Tag: {Tag}" → return false
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. Tag Namespace Reference (Framework Canonical)
|
|
||||||
|
|
||||||
All framework-level tags are defined in per-category Data Tables (CSV format, Row Structure: `GameplayTagTableRow`). These tables are registered in `Project Settings → GameplayTags → Gameplay Tag Table List`. The engine's `UGameplayTagsManager` merges all tables into one master list.
|
|
||||||
|
|
||||||
| Data Table | Namespaces Covered | Example Tags |
|
|
||||||
|------------|-------------------|--------------|
|
|
||||||
| `DT_Tags_Player` | `Framework.Player.State.*`, `*.Stress.*`, `*.Posture.*`, `*.Movement.*`, `*.Camera.*`, `*.Body.*`, `*.Overlay.*`, `*.Vitals.*` | Alive, Dead, Hidden, Sprinting, Crouching, Aiming, FullBody, Blood |
|
|
||||||
| `DT_Tags_Interaction` | `Framework.Interaction.Type.*`, `*.Context.*`, `*.Prompt.*`, `*.HidingSpot.*`, `*.Traversal.*`, `*.Door.*` | Pickup, Door, Container, Locked, OneShot, Vault, Mantle |
|
|
||||||
| `DT_Tags_Item` | `Framework.Item.Type.*`, `*.Slot.*`, `*.Rarity.*`, `*.Context.*` | Weapon, KeyItem, PrimaryWeapon, Legendary, Stackable |
|
|
||||||
| `DT_Tags_Narrative` | `Game.Narrative.Flag.*`, `*.Phase.*`, `*.Choice.*`, `*.Ending.*`, `*.Trial.*`, `*.Cutscene.*`, `*.Lore.*`, `Framework.Objective.*` | Chapter1Complete, Act2, GoodEnding, HospitalEscape, Intro |
|
|
||||||
| `DT_Tags_AI` | `Framework.AI.Alert.*`, `*.Archetype.*`, `*.Stimulus.*`, `*.Behavior.*`, `*.Memory.*` | Alerted, Stalker, Hearing, Aggressive, LastKnownLocation |
|
|
||||||
| `DT_Tags_Save` | `Framework.Save.*`, `*.DeathSpace.*`, `*.Checkpoint.*`, `*.Respawn.*`, `*.RunHistory.*` | Checkpoint, HardSave, Slot.1, Entered, Active, Reached, Start, Death |
|
|
||||||
| `DT_Tags_Environment` | `Game.Environment.Atmosphere.*`, `*.Scare.*`, `*.Light.*`, `*.Pacing.*`, `*.Performance.*` | Tense, MirrorJump, Flicker, Combat, High |
|
|
||||||
| `DT_Tags_Combat` | `Framework.Combat.Damage.*`, `*.Weapon.*`, `*.Ammo.*`, `*.FireMode.*`, `*.HitReaction.*`, `*.Feedback.*`, `*.Shield.*` | Physical, Firearm, Pistol, Flinch, HitMarker, Active |
|
|
||||||
| `DT_Tags_State` | `Framework.State.Action.*`, `*.Overlay.*`, `*.Vital.*`, `*.Gating.*` | Fire, Sprint, Menu, Health, BlockSprint |
|
|
||||||
| `DT_Tags_Audio` | `Framework.Audio.Bus.*`, `*.Room.*`, `*.Parameter.*`, `*.Surface.*` | SFX, Small, HeartRate, Concrete |
|
|
||||||
| `DT_Tags_Achievement` | `Game.Achievement.*` | FirstBlood, Survivor, Pacifist, Ghost, Collector, LoreMaster, TrueEnding, SpeedRunner, WeaponsMaster, Completionist |
|
|
||||||
|
|
||||||
**Usage Rule:** All systems must add the prefix `Framework.` to framework tags in code comments. Project-specific tags use `Game.` prefix. Example: `Framework.Item.Type.Weapon` vs `Game.Narrative.Flag.BasementDoorOpened`.
|
|
||||||
|
|
||||||
**CSV Format:** Each Data Table CSV uses columns: `Name,Tag,DevComment`. Name is a unique row identifier. Tag is the full gameplay tag string. DevComment explains the tag's purpose.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. Communication Matrix
|
|
||||||
|
|
||||||
| Target System | Method | Direction | Data |
|
|
||||||
|---------------|--------|-----------|------|
|
|
||||||
| All other systems | `GameplayTag` comparisons | Read-only | Framework-defined tag values |
|
|
||||||
|
|
||||||
This asset does not talk to other systems directly. All communication is passive — other systems read tag values from the project's tag table.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 12. Validation Checklist
|
|
||||||
|
|
||||||
- [ ] All namespace prefixes documented in the Data Asset's `TagNamespace` text field
|
|
||||||
- [ ] `bIsFrameworkTag` set to `true` for framework namespaces
|
|
||||||
- [ ] At least one project-specific tag exists (e.g. `Game.Narrative.Flag.PrologueComplete`) to validate the workflow
|
|
||||||
- [ ] `DefaultGameplayTags.ini` contains ALL documented tags
|
|
||||||
- [ ] No duplicate tag names across namespaces
|
|
||||||
- [ ] No raw string comparisons exist in any other system (all must use `HasTag` / `MatchesTag`)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 13. Reuse Notes
|
|
||||||
|
|
||||||
- The `Game.` namespace is reserved for **project-specific** tags and is empty in the framework distribution.
|
|
||||||
- To add new tags: edit `DefaultGameplayTags.ini` or use the **Gameplay Tags** editor under **Project Settings**.
|
|
||||||
- The Data Asset is purely documentary — the real tag data lives in the project's tag table. This file exists so systems have a single place to look up "what tags exist in the framework" without reading the `.ini` file directly.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 14. Manual Implementation Guide
|
|
||||||
|
|
||||||
> **For human implementer:** Follow these steps to build `DA_GameTagRegistry` in UE5 Blueprints.
|
|
||||||
> **⚠️ UE5 BP Limitation:** `UGameplayTagsManager::RequestAllGameplayTags()` is C++ only. This implementation uses an **Array of Data Tables** (11 per-category tables) as the 100% Blueprint workaround. All tables must be registered in `Project Settings → GameplayTags → Gameplay Tag Table List`.
|
|
||||||
|
|
||||||
### 14.0 Prerequisite: Create the Per-Category Data Tables
|
|
||||||
|
|
||||||
Before implementing the Data Asset, create **11 Data Tables**, one per category. Each follows the same format:
|
|
||||||
|
|
||||||
**Format:** Data Table with Row Structure = `GameplayTagTableRow`
|
|
||||||
**CSV Columns:** `Name,Tag,DevComment`
|
|
||||||
**Location in docs:** `docs/blueprints/01-core/data-tables/DT_Tags_*.csv`
|
|
||||||
**Location in UE5:** `Content/Framework/Core/DataTables/DT_Tags_*`
|
|
||||||
|
|
||||||
1. For each category, right-click in Content Browser → **Miscellaneous → Data Table**
|
|
||||||
2. Row Structure: `GameplayTagTableRow`
|
|
||||||
3. Name: `DT_Tags_{Category}` (e.g., `DT_Tags_Player`)
|
|
||||||
4. Import the corresponding CSV file (Right-click Data Table → Import → CSV)
|
|
||||||
5. **Critical:** Go to `Project Settings → GameplayTags → Gameplay Tag Table List` → click `+` 11 times → assign each table to a slot
|
|
||||||
- This auto-registers ALL tags with the engine's tag manager.
|
|
||||||
|
|
||||||
### 14.1 Class Setup
|
|
||||||
|
|
||||||
1. Right-click in Content Browser → **Miscellaneous → Data Asset**
|
|
||||||
2. Select parent class: `PrimaryDataAsset`
|
|
||||||
3. Name: `DA_GameTagRegistry`
|
|
||||||
4. Save to: `Content/Framework/Core/`
|
|
||||||
|
|
||||||
### 14.2 Variables
|
|
||||||
|
|
||||||
Add to Class Defaults:
|
|
||||||
| Variable | Type | Instance Editable | Default | Category |
|
|
||||||
|----------|------|------------------|---------|----------|
|
|
||||||
| `TagNamespace` | `Text` | ✓ | *"Framework tag namespace documentation"* | Documentation |
|
|
||||||
| `bIsFrameworkTag` | `Boolean` | ✓ | `true` | Documentation |
|
|
||||||
| `TagDataTables` | `Array<Data Table Object Reference>` | ✓ | [DT_Tags_Player, DT_Tags_Interaction, DT_Tags_Item, DT_Tags_Narrative, DT_Tags_AI, DT_Tags_Save, DT_Tags_Environment, DT_Tags_Combat, DT_Tags_State, DT_Tags_Audio, DT_Tags_Achievement] | Config |
|
|
||||||
|
|
||||||
**⚠️ Multi-Table Design:** Tags are split into 11 per-category Data Tables (see Section 10). In UE5 `Project Settings → GameplayTags → Gameplay Tag Table List`, add ALL 11 tables. The engine's `UGameplayTagsManager` merges them automatically.
|
|
||||||
|
|
||||||
### 14.3 Function Implementations
|
|
||||||
|
|
||||||
#### `GetAllRegisteredTags()` → `Array<GameplayTag>` *(Blueprint Pure)*
|
|
||||||
|
|
||||||
**Purpose:** Returns all tags from ALL registered Data Tables. Uses an outer loop over `TagDataTables` array and inner loop over each table's rows.
|
|
||||||
|
|
||||||
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestAllGameplayTags()` is C++ only — not exposed to Blueprints. This function uses the Data Table proxy approach with multiple tables.
|
|
||||||
|
|
||||||
**Node-by-Node Logic:**
|
|
||||||
```
|
|
||||||
[Function: GetAllRegisteredTags] (Pure, no execution pins)
|
|
||||||
Step 1: Create empty Array<GameplayTag> → LocalTags
|
|
||||||
Step 2: ForEachLoop over TagDataTables array (outer loop):
|
|
||||||
├─► Array Element = current Data Table
|
|
||||||
├─► Branch: IsValid(current table)?
|
|
||||||
│ False → Skip to next table
|
|
||||||
│ True → Continue
|
|
||||||
├─► Get Data Table Row Names (current table) → returns Array<Name>
|
|
||||||
└─► ForEachLoop over RowNames (inner loop):
|
|
||||||
├─► Get Data Table Row (current table, Array Element)
|
|
||||||
│ → Struct Pin: Break GameplayTagTableRow
|
|
||||||
│ → Get "Tag" field (type: GameplayTag)
|
|
||||||
└─► Add "Tag" to LocalTags array
|
|
||||||
Step 3: Return LocalTags
|
|
||||||
```
|
|
||||||
|
|
||||||
**Nodes to Search:** `ForEachLoop` (outer over TagDataTables), `ForEachLoop` (inner over row names), `Get Data Table Row Names`, `Get Data Table Row`, `Break GameplayTagTableRow`, `Add`, `Array`, `IsValid`
|
|
||||||
|
|
||||||
**⚠️ Note:** If your UE version doesn't support loops in Pure functions, make this **BlueprintCallable** (impure) instead.
|
|
||||||
|
|
||||||
#### `GetTagDisplayName(Tag: GameplayTag)` → `Text` *(Blueprint Pure)*
|
|
||||||
|
|
||||||
**Node-by-Node Logic:**
|
|
||||||
```
|
|
||||||
[Function: GetTagDisplayName]
|
|
||||||
Input Tag → Get Tag Display Name (Tag) → Return
|
|
||||||
```
|
|
||||||
|
|
||||||
**Node Search:** `Get Tag Display Name` — this IS available in Blueprint (part of GameplayTags plugin).
|
|
||||||
|
|
||||||
#### `ValidateTag(Tag: GameplayTag)` → `Boolean` *(Blueprint Pure)*
|
|
||||||
|
|
||||||
**⚠️ UE5 Limitation:** `UGameplayTagsManager::RequestGameplayTag()` is not directly available in BP. Use `Is Gameplay Tag Valid` instead.
|
|
||||||
|
|
||||||
**Node-by-Node Logic:**
|
|
||||||
```
|
|
||||||
[Function: ValidateTag]
|
|
||||||
Step 1: Is Gameplay Tag Valid (Tag)
|
|
||||||
├─► True → Return true
|
|
||||||
└─► False → Print Warning: "Invalid Tag: " + Get Tag Name(Tag) → Return false
|
|
||||||
```
|
|
||||||
|
|
||||||
**Node Search:** `Is Gameplay Tag Valid`, `Get Tag Name`
|
|
||||||
|
|
||||||
**⚠️ Note:** `Is Gameplay Tag Valid` returns true only if the tag is registered in the engine's tag table (which the 11 Data Tables populate via Project Settings). Tags NOT in any registered table will return false.
|
|
||||||
|
|
||||||
#### `LogAllTags()` → *(void)* *(Blueprint Callable)*
|
|
||||||
|
|
||||||
**Editor Only.** Prints all tags from all Data Tables to the output log.
|
|
||||||
|
|
||||||
**Node-by-Node Logic:**
|
|
||||||
```
|
|
||||||
[Function: LogAllTags]
|
|
||||||
Step 1: Call GetAllRegisteredTags() → LocalTags
|
|
||||||
Step 2: ForEachLoop (LocalTags):
|
|
||||||
├─► Name (Array Element) → ToString → Print String
|
|
||||||
Step 3: Print String: "Total tags across all tables: " + Array Length(LocalTags)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### `ExportTagNamespace(NamespacePrefix: String)` → `String` *(Blueprint Callable)*
|
|
||||||
|
|
||||||
**Node-by-Node Logic:**
|
|
||||||
```
|
|
||||||
[Function: ExportTagNamespace]
|
|
||||||
Step 1: Call GetAllRegisteredTags() → LocalTags
|
|
||||||
Step 2: Create String variable → Output = ""
|
|
||||||
Step 3: ForEachLoop (LocalTags):
|
|
||||||
├─► (Array Element) → ToString → TagString
|
|
||||||
├─► Branch: Does TagString start with NamespacePrefix?
|
|
||||||
│ True → Append TagString + "\n" to Output (use "Append" or "Build String")
|
|
||||||
└─► Continue
|
|
||||||
Step 4: Return Output
|
|
||||||
```
|
|
||||||
|
|
||||||
### 14.4 External Initialization
|
|
||||||
|
|
||||||
Since Data Assets have no `BeginPlay`, call validation from your GameInstance or StateManager:
|
|
||||||
|
|
||||||
**In `GI_GameFramework.Init()` or `BPC_StateManager.BeginPlay()`:**
|
|
||||||
```
|
|
||||||
Step 1: Get DA_GameTagRegistry (hard reference or Load Asset)
|
|
||||||
Step 2: Call DA_GameTagRegistry.GetAllRegisteredTags() → LocalTags
|
|
||||||
Step 3: Branch: Array Length(LocalTags) == 0
|
|
||||||
├─► True → Print Warning: "No tags in registered Data Tables!"
|
|
||||||
└─► False → Print String: "N tags registered: " + Array Length
|
|
||||||
Step 4: [Debug builds only] Call DA_GameTagRegistry.LogAllTags()
|
|
||||||
```
|
|
||||||
|
|
||||||
### 14.5 Networking
|
|
||||||
|
|
||||||
No replication needed. This is a read-only Data Asset with a read-only Data Table reference. All clients load identical copies from disk.
|
|
||||||
|
|
||||||
### 14.6 Blueprint Build Checklist
|
|
||||||
|
|
||||||
- [ ] Create 11 Data Tables with Row Structure `GameplayTagTableRow`:
|
|
||||||
- [ ] `DT_Tags_Player` — Player state, stress, posture, movement, camera, body, vitals
|
|
||||||
- [ ] `DT_Tags_Interaction` — Interaction types, contexts, prompts, hiding spots, traversal, doors
|
|
||||||
- [ ] `DT_Tags_Item` — Item types, slots, rarities, contexts
|
|
||||||
- [ ] `DT_Tags_Narrative` — Flags, phases, choices, endings, trials, cutscenes, lore, objectives
|
|
||||||
- [ ] `DT_Tags_AI` — Alert levels, archetypes, stimuli, behaviors, memory
|
|
||||||
- [ ] `DT_Tags_Save` — Save types, death space, checkpoints, respawn
|
|
||||||
- [ ] `DT_Tags_Environment` — Atmosphere, scares, lighting, pacing, performance
|
|
||||||
- [ ] `DT_Tags_Combat` — Damage types, weapons, ammo, fire modes, hit reactions, shield
|
|
||||||
- [ ] `DT_Tags_State` — Action states, overlay states, vitals, gating
|
|
||||||
- [ ] `DT_Tags_Audio` — Audio buses, room acoustics, parameters, surfaces
|
|
||||||
- [ ] `DT_Tags_Achievement` — Achievement identifiers
|
|
||||||
- [ ] Add ALL 11 tables to `Project Settings → GameplayTags → Gameplay Tag Table List`
|
|
||||||
- [ ] Create Data Asset: `DA_GameTagRegistry` (Parent: `PrimaryDataAsset`)
|
|
||||||
- [ ] Add variables: `TagNamespace` (Text), `bIsFrameworkTag` (Boolean), `TagDataTables` (Array<Data Table> — populate with all 11 tables)
|
|
||||||
- [ ] Implement `GetAllRegisteredTags` with OUTER loop over TagDataTables + INNER loop over row names
|
|
||||||
- [ ] Implement `GetTagDisplayName` using `Get Tag Display Name` node
|
|
||||||
- [ ] Implement `ValidateTag` using `Is Gameplay Tag Valid` node
|
|
||||||
- [ ] Implement `LogAllTags` (editor-only, prints tags from all tables)
|
|
||||||
- [ ] Implement `ExportTagNamespace` (string prefix filtering across all tables)
|
|
||||||
- [ ] Add external initialization call from `GI_GameFramework.Init()` or `BPC_StateManager.BeginPlay()`
|
|
||||||
- [ ] Verify: all tags from Section 10 exist in the appropriate Data Table
|
|
||||||
- [ ] Verify: `ValidateTag` returns true for tags in any registered table, false for unregistered
|
|
||||||
- [ ] Verify: `GetAllRegisteredTags` returns ALL tags merged from all tables
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 15. Multiplayer Networking
|
|
||||||
|
|
||||||
**Replication: None needed.** This Data Asset is read-only configuration. All clients load identical copies from disk. GameplayTag data lives in `DefaultGameplayTags.ini` which is identical on all instances.
|
|
||||||
|
|
||||||
**Authority: N/A.** No runtime state changes.
|
|
||||||
|
|||||||
@@ -4,7 +4,7 @@
|
|||||||
The single source of truth for every item in the game. Each item is represented by one `DA_ItemData` Primary Data Asset. No item data lives in Blueprint logic; all item definitions are data-driven from these assets.
|
The single source of truth for every item in the game. Each item is represented by one `DA_ItemData` Primary Data Asset. No item data lives in Blueprint logic; all item definitions are data-driven from these assets.
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
- **Requires:** `GameplayTag` system (`GI_GameTagRegistry`), `UPrimaryDataAsset` (engine base)
|
- **Requires:** `GameplayTag` system (`DA_GameTagRegistry`), `UPrimaryDataAsset` (engine base)
|
||||||
- **Required By:** `BPC_InventorySystem`, `BPC_EquipmentSlotSystem`, `BPC_ConsumableSystem`, `BPC_AmmoResourceSystem`, `BPC_ItemCombineSystem`, `BPC_KeyItemSystem`, `BPC_ActiveItemSystem`, `DA_ItemDatabase` (collection)
|
- **Required By:** `BPC_InventorySystem`, `BPC_EquipmentSlotSystem`, `BPC_ConsumableSystem`, `BPC_AmmoResourceSystem`, `BPC_ItemCombineSystem`, `BPC_KeyItemSystem`, `BPC_ActiveItemSystem`, `DA_ItemDatabase` (collection)
|
||||||
- **Engine/Plugin Requirements:** `GameplayTags`, `AssetManager` (Primary Data Asset registration)
|
- **Engine/Plugin Requirements:** `GameplayTags`, `AssetManager` (Primary Data Asset registration)
|
||||||
- **Parent Class:** `UPrimaryDataAsset`
|
- **Parent Class:** `UPrimaryDataAsset`
|
||||||
@@ -171,7 +171,7 @@ flowchart LR
|
|||||||
## 10. Reuse Notes
|
## 10. Reuse Notes
|
||||||
|
|
||||||
- Create one `DA_ItemData` per item. Name convention: `DA_Item_[ShortName]` (e.g. `DA_Item_MedKit`, `DA_Item_Flashlight`, `DA_Item_KeyCard_Omega`).
|
- Create one `DA_ItemData` per item. Name convention: `DA_Item_[ShortName]` (e.g. `DA_Item_MedKit`, `DA_Item_Flashlight`, `DA_Item_KeyCard_Omega`).
|
||||||
- All `ItemTag` values must be registered in `GI_GameTagRegistry` before use.
|
- All `ItemTag` values must be registered in `DA_GameTagRegistry` before use.
|
||||||
- The `CustomProperties` map future-proofs any per-project additions without modifying the base asset class.
|
- The `CustomProperties` map future-proofs any per-project additions without modifying the base asset class.
|
||||||
- For non-stackable items (weapons, key items, tools), set `StackLimit = 1`.
|
- For non-stackable items (weapons, key items, tools), set `StackLimit = 1`.
|
||||||
- For stacks, choose a sensible `StackLimit` (e.g. ammo = 999, consumables = 5).
|
- For stacks, choose a sensible `StackLimit` (e.g. ammo = 999, consumables = 5).
|
||||||
|
|||||||
@@ -244,7 +244,7 @@ Manages the player's ability to hide inside, behind, or under environmental obje
|
|||||||
- **Description:** Initialises state, binds to input actions.
|
- **Description:** Initialises state, binds to input actions.
|
||||||
- **Flow:**
|
- **Flow:**
|
||||||
1. Set CurrentHideState = Exposed
|
1. Set CurrentHideState = Exposed
|
||||||
2. Register with GI_GameTagRegistry if needed
|
2. Register with DA_GameTagRegistry if needed
|
||||||
3. Cache reference to CharacterMovementComponent for disabling during hide
|
3. Cache reference to CharacterMovementComponent for disabling during hide
|
||||||
|
|
||||||
### Custom Event: `ForceKickFromHide`
|
### Custom Event: `ForceKickFromHide`
|
||||||
|
|||||||
@@ -195,7 +195,7 @@ flowchart TD
|
|||||||
- MutationRegistry is populated per level — each level defines which rooms can mutate and how
|
- MutationRegistry is populated per level — each level defines which rooms can mutate and how
|
||||||
- DriftIntensity is ramped up by the adaptive director as the game progresses
|
- DriftIntensity is ramped up by the adaptive director as the game progresses
|
||||||
- For non-horror games, leave MutationRegistry empty to disable the system
|
- For non-horror games, leave MutationRegistry empty to disable the system
|
||||||
- Room tags are defined in GI_GameTagRegistry — add project-specific rooms there
|
- Room tags are defined in DA_GameTagRegistry — add project-specific rooms there
|
||||||
- Extend DA_RoomMutation with new mutation types (actor spawn, light change, sound trigger, etc.)
|
- Extend DA_RoomMutation with new mutation types (actor spawn, light change, sound trigger, etc.)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
@@ -91,7 +91,7 @@ Values:
|
|||||||
|
|
||||||
- [ ] EventTag is unique and valid GameplayTag
|
- [ ] EventTag is unique and valid GameplayTag
|
||||||
- [ ] Probability is in range 0.0–1.0 (0.001 = 0.1%, 0.01 = 1%, 0.1 = 10%)
|
- [ ] Probability is in range 0.0–1.0 (0.001 = 0.1%, 0.01 = 1%, 0.1 = 10%)
|
||||||
- [ ] EventConditions tags exist in GI_GameTagRegistry
|
- [ ] EventConditions tags exist in DA_GameTagRegistry
|
||||||
- [ ] EventActions array has at least one action
|
- [ ] EventActions array has at least one action
|
||||||
- [ ] S_RareEventAction.ActionType matches the data needed (audio uses ActionTag for cue, spawn uses ActionTag for actor class)
|
- [ ] S_RareEventAction.ActionType matches the data needed (audio uses ActionTag for cue, spawn uses ActionTag for actor class)
|
||||||
- [ ] bOncePerSession and bOncePerSaveFile properly gated (don't set both unless intended)
|
- [ ] bOncePerSession and bOncePerSaveFile properly gated (don't set both unless intended)
|
||||||
|
|||||||
@@ -4,7 +4,7 @@
|
|||||||
Single source of truth for "what can the player do right now?" Every system queries `IsActionPermitted(Tag)` instead of checking other systems' states directly. Manages exclusive action states, upper-body overlay states, action action gating, vital signs (heart rate), and the force-stack pattern for nested overrides (death, cutscenes, void space). Communicates with GASP exclusively through overlay state variables — never touches motion matching internals.
|
Single source of truth for "what can the player do right now?" Every system queries `IsActionPermitted(Tag)` instead of checking other systems' states directly. Manages exclusive action states, upper-body overlay states, action action gating, vital signs (heart rate), and the force-stack pattern for nested overrides (death, cutscenes, void space). Communicates with GASP exclusively through overlay state variables — never touches motion matching internals.
|
||||||
|
|
||||||
## Dependencies
|
## Dependencies
|
||||||
- **Requires:** `GI_GameFramework` (04 — game phase changes), `BPC_HealthSystem` (08 — death + injury bindings), `BPC_StressSystem` (10 — stress tier), `BPC_StaminaSystem` (09 — exhaustion), `BPC_MovementStateSystem` (11 — movement mode tracking), `GI_GameTagRegistry` (01 — tag queries), `SS_EnhancedInputManager` (128 — context switching), `ABP_GASP` (external — overlay + intensity variables)
|
- **Requires:** `GI_GameFramework` (04 — game phase changes), `BPC_HealthSystem` (08 — death + injury bindings), `BPC_StressSystem` (10 — stress tier), `BPC_StaminaSystem` (09 — exhaustion), `BPC_MovementStateSystem` (11 — movement mode tracking), `DA_GameTagRegistry` (01 — tag queries), `SS_EnhancedInputManager` (128 — context switching), `ABP_GASP` (external — overlay + intensity variables)
|
||||||
- **Required By:** EVERY gameplay system (central query point for action permission)
|
- **Required By:** EVERY gameplay system (central query point for action permission)
|
||||||
- **Engine/Plugin Requirements:** GameplayTags plugin, GASP plugin (read-only)
|
- **Engine/Plugin Requirements:** GameplayTags plugin, GASP plugin (read-only)
|
||||||
|
|
||||||
@@ -425,7 +425,7 @@ Values:
|
|||||||
4. Populate default `GatingRules` from `DA_StateGatingTable` if assigned
|
4. Populate default `GatingRules` from `DA_StateGatingTable` if assigned
|
||||||
5. Bind to `GI_GameFramework.OnGamePhaseChanged` (for game-phase-gated rules)
|
5. Bind to `GI_GameFramework.OnGamePhaseChanged` (for game-phase-gated rules)
|
||||||
6. Bind to `BPC_HealthSystem.OnDeath` (auto-call `ForceStateChange(Dead, "Death")`)
|
6. Bind to `BPC_HealthSystem.OnDeath` (auto-call `ForceStateChange(Dead, "Death")`)
|
||||||
7. Register with `GI_GameTagRegistry` for tag-based queries
|
7. Register with `DA_GameTagRegistry` for tag-based queries
|
||||||
8. Bind to `BPC_HealthSystem.OnHealthChanged` → call `EvaluateInjuryState()`
|
8. Bind to `BPC_HealthSystem.OnHealthChanged` → call `EvaluateInjuryState()`
|
||||||
9. Bind to `BPC_StressSystem.OnStressTierChanged` → recalculate heart rate
|
9. Bind to `BPC_StressSystem.OnStressTierChanged` → recalculate heart rate
|
||||||
10. Bind to `BPC_StaminaSystem.OnExhaustionStateChanged` → recalculate heart rate
|
10. Bind to `BPC_StaminaSystem.OnExhaustionStateChanged` → recalculate heart rate
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Master Blueprint Index — UE5 Modular Game Framework
|
# Master Blueprint Index — UE5 Modular Game Framework
|
||||||
|
|
||||||
**Version:** 3.0 | **Generated:** 2026-05-18 | **Total Files:** 135 numbered (129 original + 6 new)
|
**Version:** 3.1 | **Generated:** 2026-05-20 | **Total Files:** 135 numbered + 1 starter (136 total specs)
|
||||||
|
|
||||||
This document is the canonical index of every Blueprint specification file in the framework. Each entry links to its full spec document and includes: file name, asset type, parent class, purpose summary, and key dependencies.
|
This document is the canonical index of every Blueprint specification file in the framework. Each entry links to its full spec document and includes: file name, asset type, parent class, purpose summary, and key dependencies.
|
||||||
|
|
||||||
@@ -14,6 +14,8 @@ docs/blueprints/
|
|||||||
├── TEMPLATE.md ← Spec template v2.0
|
├── TEMPLATE.md ← Spec template v2.0
|
||||||
├── AUDIT_REPORT.md ← Clean slate audit
|
├── AUDIT_REPORT.md ← Clean slate audit
|
||||||
│
|
│
|
||||||
|
├── 00-project-setup/ ← Project Setup & Starter Assets (1 file)
|
||||||
|
│ └── GI_StarterGameInstance.md ← Minimal GameInstance; tag validation entry point
|
||||||
├── 01-core/ ← Foundation (7 files + 11 Data Table CSVs)
|
├── 01-core/ ← Foundation (7 files + 11 Data Table CSVs)
|
||||||
│ ├── data-tables/ ← Per-category Gameplay Tag Data Tables (NEW — replaces DT_ProjectTags.csv)
|
│ ├── data-tables/ ← Per-category Gameplay Tag Data Tables (NEW — replaces DT_ProjectTags.csv)
|
||||||
│ │ ├── DT_Tags_Player.csv (34 tags)
|
│ │ ├── DT_Tags_Player.csv (34 tags)
|
||||||
@@ -51,7 +53,8 @@ docs/blueprints/
|
|||||||
|
|
||||||
| # | File Name | Asset Type | Parent Class | Short Purpose | Category |
|
| # | File Name | Asset Type | Parent Class | Short Purpose | Category |
|
||||||
|---|-----------|-----------|-------------|---------------|----------|
|
|---|-----------|-----------|-------------|---------------|----------|
|
||||||
| 01 | [`01_GI_GameTagRegistry`](01-core/01_GI_GameTagRegistry.md) | `GI_` Game Instance | `GameInstance` | Central gameplay tag registry; maps tags to data/assets | 01-core |
|
| — | [`GI_StarterGameInstance`](00-project-setup/GI_StarterGameInstance.md) | `GI_` Game Instance | `GameInstance` | Minimal GameInstance; loads DA_GameTagRegistry, validates tags, broadcasts OnFrameworkReady | 00-project-setup |
|
||||||
|
| 01 | [`01_DA_GameTagRegistry`](01-core/01_DA_GameTagRegistry.md) | `DA_` Data Asset | `PrimaryDataAsset` | Central gameplay tag registry; maps tags to data/assets | 01-core |
|
||||||
| 02 | [`02_FL_GameUtilities`](01-core/02_FL_GameUtilities.md) | `FL_` Function Library | `BlueprintFunctionLibrary` | Shared utility functions (logging, tag queries, math) | 01-core |
|
| 02 | [`02_FL_GameUtilities`](01-core/02_FL_GameUtilities.md) | `FL_` Function Library | `BlueprintFunctionLibrary` | Shared utility functions (logging, tag queries, math) | 01-core |
|
||||||
| 03 | [`03_I_InterfaceLibrary`](01-core/03_I_InterfaceLibrary.md) | `I_` Interface | `Interface` | All framework interfaces (I_Damageable, I_Interactable, I_Persistable, etc.) | 01-core |
|
| 03 | [`03_I_InterfaceLibrary`](01-core/03_I_InterfaceLibrary.md) | `I_` Interface | `Interface` | All framework interfaces (I_Damageable, I_Interactable, I_Persistable, etc.) | 01-core |
|
||||||
| 04 | [`04_GI_GameFramework`](01-core/04_GI_GameFramework.md) | `GI_` Game Instance | `GameInstance` | Application kernel; owns subsystems, game phases, platform init | 01-core |
|
| 04 | [`04_GI_GameFramework`](01-core/04_GI_GameFramework.md) | `GI_` Game Instance | `GameInstance` | Application kernel; owns subsystems, game phases, platform init | 01-core |
|
||||||
@@ -210,7 +213,7 @@ docs/blueprints/
|
|||||||
| `BPC_` | Blueprint Component | 80 |
|
| `BPC_` | Blueprint Component | 80 |
|
||||||
| `BP_` | Blueprint Actor | 11 |
|
| `BP_` | Blueprint Actor | 11 |
|
||||||
| `WBP_` | Widget Blueprint | 14 |
|
| `WBP_` | Widget Blueprint | 14 |
|
||||||
| `DA_` | Data Asset | 18 |
|
| `DA_` | Data Asset | 19 |
|
||||||
| `SS_` | GameInstance Subsystem | 7 |
|
| `SS_` | GameInstance Subsystem | 7 |
|
||||||
| `GI_` | Game Instance | 2 |
|
| `GI_` | Game Instance | 2 |
|
||||||
| `GM_` | Game Mode | 1 |
|
| `GM_` | Game Mode | 1 |
|
||||||
@@ -220,7 +223,7 @@ docs/blueprints/
|
|||||||
| `AI_` | AI Controller | 1 |
|
| `AI_` | AI Controller | 1 |
|
||||||
| `BB_` | Blackboard | 1 |
|
| `BB_` | Blackboard | 1 |
|
||||||
| `E_` | Enum | 5 |
|
| `E_` | Enum | 5 |
|
||||||
| **Total** | | **145** |
|
| **Total** | | **146** |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -280,8 +283,9 @@ Below are the most cross-referenced systems — these are the ones the State Man
|
|||||||
| `BPC_PerformanceScaler` | 91 | `BPC_PersistentCorpseSystem` | 40 | | |
|
| `BPC_PerformanceScaler` | 91 | `BPC_PersistentCorpseSystem` | 40 | | |
|
||||||
| `BPC_PersistentWorldStateRecorder` | 41 | `BPC_PhysicsDragSystem` | 22 | | |
|
| `BPC_PersistentWorldStateRecorder` | 41 | `BPC_PhysicsDragSystem` | 22 | | |
|
||||||
| `FL_GameUtilities` | 2 | `GI_GameFramework` | 4 | | |
|
| `FL_GameUtilities` | 2 | `GI_GameFramework` | 4 | | |
|
||||||
| `GI_GameTagRegistry` | 1 | `GM_CoreGameMode` | 5 | | |
|
| `GI_StarterGameInstance` | — | `GI_GameTagRegistry` | 1 | `GM_CoreGameMode` | 5 |
|
||||||
| `GS_CoreGameState` | 6 | `I_HidingSpot` | 17 | | |
|
| `DA_GameTagRegistry` | 1 | `GM_CoreGameMode` | 5 | | |
|
||||||
|
| `GS_CoreGameState` | 6 | `HidingSpot` | 17 | | |
|
||||||
| `I_InterfaceLibrary` | 3 | `I_Persistable` | 36 | | |
|
| `I_InterfaceLibrary` | 3 | `I_Persistable` | 36 | | |
|
||||||
| `SS_AchievementSystem` | 103 | `SS_EnhancedInputManager` | 128 | | |
|
| `SS_AchievementSystem` | 103 | `SS_EnhancedInputManager` | 128 | | |
|
||||||
| `SS_SaveManager` | 35 | `SS_SettingsSystem` | 105 | | |
|
| `SS_SaveManager` | 35 | `SS_SettingsSystem` | 105 | | |
|
||||||
|
|||||||
124
docs/developer/00-starter-gameinstance.md
Normal file
124
docs/developer/00-starter-gameinstance.md
Normal file
@@ -0,0 +1,124 @@
|
|||||||
|
# 00 — Starter GameInstance (`GI_StarterGameInstance`)
|
||||||
|
|
||||||
|
**Category Purpose:** This is the first Blueprint you create in a new UE5 project using the Modular Game Framework. It provides a working GameInstance entry point that validates your GameplayTag setup and broadcasts `OnFrameworkReady` so other systems can safely initialize.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## System Index
|
||||||
|
|
||||||
|
| # | System | Asset Type | Role |
|
||||||
|
|---|--------|-----------|------|
|
||||||
|
| — | `GI_StarterGameInstance` | Game Instance | Minimal GameInstance; loads `DA_GameTagRegistry`, validates tags, broadcasts `OnFrameworkReady` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What It Does
|
||||||
|
|
||||||
|
`GI_StarterGameInstance` is a **temporary** lightweight GameInstance that you set as your project's `Game Instance Class` during Phase 0 setup. Its sole purpose is to:
|
||||||
|
|
||||||
|
1. **Load `DA_GameTagRegistry`** during `Event Init` — before any level loads
|
||||||
|
2. **Validate that all 11 Data Tables are registered** in Project Settings → GameplayTags
|
||||||
|
3. **Broadcast `OnFrameworkReady`** — other systems bind to this dispatcher and defer their initialization
|
||||||
|
4. **Log clear error messages** if something is misconfigured (missing tag tables, unassigned registry reference)
|
||||||
|
|
||||||
|
Once the full `GI_GameFramework` (#04) is implemented, you swap the `Game Instance Class` in Project Settings and the starter is discarded. All systems that bind to `OnFrameworkReady` continue working.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Boot Sequence
|
||||||
|
|
||||||
|
```
|
||||||
|
Engine Start
|
||||||
|
└─► GI_StarterGameInstance.Event Init()
|
||||||
|
├─► Parent::Init() (UE native GameInstance init)
|
||||||
|
├─► ValidateFrameworkTags()
|
||||||
|
│ ├─► IsValid(TagRegistry)?
|
||||||
|
│ │ False → Print Error → Return
|
||||||
|
│ │ True → Call DA_GameTagRegistry.GetAllRegisteredTags()
|
||||||
|
│ ├─► Tag count == 0?
|
||||||
|
│ │ True → Print Warning: "No tags registered!"
|
||||||
|
│ │ False → Print: "N tags registered across 11 Data Tables"
|
||||||
|
│ └─► bLogTagsOnInit? → Call LogAllTags()
|
||||||
|
├─► Set bFrameworkInitialized = true
|
||||||
|
└─► Broadcast OnFrameworkReady
|
||||||
|
└─► All bound systems begin their initialization
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration Pattern: How Other Systems Use It
|
||||||
|
|
||||||
|
Every Blueprint that needs framework services follows this pattern:
|
||||||
|
|
||||||
|
```
|
||||||
|
[Event BeginPlay in any system]
|
||||||
|
Step 1: Get Game Instance → Cast to GI_StarterGameInstance → "GameInstance" ref
|
||||||
|
Step 2: Branch: IsValid(GameInstance)?
|
||||||
|
False → Print Warning: "GI_StarterGameInstance not found!"
|
||||||
|
True → Branch: GameInstance → IsFrameworkReady()?
|
||||||
|
True → Call "OnFrameworkReadyHandler" immediately (already initialized)
|
||||||
|
False → Bind "OnFrameworkReadyHandler" to GameInstance.OnFrameworkReady
|
||||||
|
```
|
||||||
|
|
||||||
|
**Custom Event: OnFrameworkReadyHandler**
|
||||||
|
```
|
||||||
|
Step 1: Unbind from GameInstance.OnFrameworkReady (prevent double-fire)
|
||||||
|
Step 2: ... proceed with system-specific init (load Data Assets, bind to other dispatchers, etc.)
|
||||||
|
```
|
||||||
|
|
||||||
|
This pattern ensures systems work regardless of initialization order — if the GameInstance fired `OnFrameworkReady` before `BeginPlay`, the system initializes immediately. Otherwise it waits for the broadcast.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration Variables
|
||||||
|
|
||||||
|
| Variable | Type | Default | Purpose |
|
||||||
|
|----------|------|---------|---------|
|
||||||
|
| `TagRegistry` | `DA_GameTagRegistry` (Object Ref) | *Must be assigned* | Hard reference to the Data Asset |
|
||||||
|
| `bValidateTagsOnInit` | `Boolean` | `true` | Enables/disables tag counting during init |
|
||||||
|
| `bLogTagsOnInit` | `Boolean` | `false` | If true, prints ALL tag names to output log (verbose) |
|
||||||
|
| `bFrameworkInitialized` | `Boolean` (Private) | `false` | Set true after successful init; queried by `IsFrameworkReady()` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dispatchers
|
||||||
|
|
||||||
|
| Dispatcher | When It Fires | Who Binds |
|
||||||
|
|------------|--------------|-----------|
|
||||||
|
| `OnFrameworkReady` | After `Event Init` completes successfully | Every system that needs tag validation before it starts |
|
||||||
|
| `OnFrameworkInitFailed(ErrorReason)` | If `TagRegistry` is invalid or null | Error handling UI, debug menu, crash reporter |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Edge Cases
|
||||||
|
|
||||||
|
- **TagRegistry not assigned:** `Event Init` detects `IsValid(TagRegistry) == false` → broadcasts `OnFrameworkInitFailed("TagRegistry not assigned or invalid")` → no crash, but all tag-dependent systems will fail. Fix by opening `GI_StarterGameInstance` Class Defaults and assigning `DA_GameTagRegistry`.
|
||||||
|
- **Zero tags in Data Tables:** The init prints a warning but does NOT fire `OnFrameworkInitFailed`. Empty tables are a warning, not a failure — tags may be added later. `OnFrameworkReady` still broadcasts.
|
||||||
|
- **Multiple BeginPlay calls:** `IsFrameworkReady()` gates duplicate init — systems check the boolean before proceeding.
|
||||||
|
- **Replaced by GI_GameFramework:** When you swap the Game Instance Class, existing bindings to `OnFrameworkReady` must be rebound to `GI_GameFramework`'s dispatcher. Both classes use the same dispatcher name and signature for compatibility.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Replacement Path
|
||||||
|
|
||||||
|
When you're ready for the full framework:
|
||||||
|
|
||||||
|
1. Implement `GI_GameFramework` (#04) with all subsystems, game phases, and platform init
|
||||||
|
2. Ensure `GI_GameFramework` includes the `OnFrameworkReady` dispatcher (with identical signature)
|
||||||
|
3. Open `Project Settings → Maps & Modes` → change `Game Instance Class` from `GI_StarterGameInstance` to `GI_GameFramework`
|
||||||
|
4. Update all `Cast to GI_StarterGameInstance` nodes to `Cast to GI_GameFramework` (find-replace in Blueprints)
|
||||||
|
5. Test: output log should show the same tag count, `OnFrameworkReady` still fires, all systems still init correctly
|
||||||
|
|
||||||
|
**Migration effort:** ~30 minutes (find-replace casts + rebind dispatchers in 3-5 key systems).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Multiplayer Networking
|
||||||
|
|
||||||
|
**Replication: None needed.** The GameInstance is a client-only singleton — each client gets its own instance with identical configuration. `OnFrameworkReady` fires independently on each client's GameInstance. No server coordination required.
|
||||||
|
|
||||||
|
**Host/Client parity:** Both listen-server host and dedicated-server clients run `Event Init` independently. Tag validation passes on both because Data Tables and `DefaultGameplayTags.ini` are identical across all instances (shipped with the build).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Developer Reference v1.0 — 00 Starter GameInstance. Companion to docs/blueprints/00-project-setup/GI_StarterGameInstance.md.*
|
||||||
@@ -8,7 +8,7 @@
|
|||||||
|
|
||||||
| # | System | Asset Type | Role |
|
| # | System | Asset Type | Role |
|
||||||
|---|--------|-----------|------|
|
|---|--------|-----------|------|
|
||||||
| 01 | `GI_GameTagRegistry` | Data Asset | Central GameplayTag namespace registry & validation |
|
| 01 | `DA_GameTagRegistry` | Data Asset | Central GameplayTag namespace registry & validation |
|
||||||
| 02 | `FL_GameUtilities` | Function Library | Static utility functions (safe casts, math, tags, debug) |
|
| 02 | `FL_GameUtilities` | Function Library | Static utility functions (safe casts, math, tags, debug) |
|
||||||
| 03 | `I_InterfaceLibrary` | Interface Collection | All 9 framework interfaces for decoupled communication |
|
| 03 | `I_InterfaceLibrary` | Interface Collection | All 9 framework interfaces for decoupled communication |
|
||||||
| 04 | `GI_GameFramework` | Game Instance | Application kernel; owns subsystems, manages game phases |
|
| 04 | `GI_GameFramework` | Game Instance | Application kernel; owns subsystems, manages game phases |
|
||||||
@@ -42,7 +42,7 @@
|
|||||||
│ ├─► Bind to GI_GameFramework.OnGamePhaseChanged │
|
│ ├─► Bind to GI_GameFramework.OnGamePhaseChanged │
|
||||||
│ └─► Tick: accumulate ElapsedPlayTime when InGame │
|
│ └─► Tick: accumulate ElapsedPlayTime when InGame │
|
||||||
│ │
|
│ │
|
||||||
│ ALL SYSTEMS query GameplayTags via GI_GameTagRegistry │
|
│ ALL SYSTEMS query GameplayTags via DA_GameTagRegistry │
|
||||||
│ ALL SYSTEMS use FL_GameUtilities for safe casts & logging │
|
│ ALL SYSTEMS use FL_GameUtilities for safe casts & logging │
|
||||||
│ ALL SYSTEMS communicate via I_InterfaceLibrary interfaces │
|
│ ALL SYSTEMS communicate via I_InterfaceLibrary interfaces │
|
||||||
│ ALL ITEMS are defined as DA_ItemData Data Assets │
|
│ ALL ITEMS are defined as DA_ItemData Data Assets │
|
||||||
@@ -51,7 +51,7 @@
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 01 — GI_GameTagRegistry: Central GameplayTag Registry
|
## 01 — DA_GameTagRegistry: Central GameplayTag Registry
|
||||||
|
|
||||||
**What It Does:** This is a **documentation anchor** Data Asset, not a runtime tag database. The actual GameplayTag definitions live in `DefaultGameplayTags.ini`, but this asset serves as the single place where all framework tag namespaces are documented and validated. Every system that uses GameplayTags references them from this registry's documented namespaces.
|
**What It Does:** This is a **documentation anchor** Data Asset, not a runtime tag database. The actual GameplayTag definitions live in `DefaultGameplayTags.ini`, but this asset serves as the single place where all framework tag namespaces are documented and validated. Every system that uses GameplayTags references them from this registry's documented namespaces.
|
||||||
|
|
||||||
@@ -298,7 +298,7 @@ MainMenu → Loading → InGame ⇄ Paused
|
|||||||
**How It Works Internally:**
|
**How It Works Internally:**
|
||||||
|
|
||||||
**Core Properties (every item has these):**
|
**Core Properties (every item has these):**
|
||||||
- `ItemTag` (GameplayTag) — unique identifier, must be registered in `GI_GameTagRegistry`
|
- `ItemTag` (GameplayTag) — unique identifier, must be registered in `DA_GameTagRegistry`
|
||||||
- `DisplayName`, `Description` (FText) — player-facing text
|
- `DisplayName`, `Description` (FText) — player-facing text
|
||||||
- `Icon` (Texture2D soft reference) — UI icon
|
- `Icon` (Texture2D soft reference) — UI icon
|
||||||
- `WorldMesh` (StaticMesh soft reference) — 3D mesh when dropped in world
|
- `WorldMesh` (StaticMesh soft reference) — 3D mesh when dropped in world
|
||||||
@@ -361,7 +361,7 @@ MainMenu → Loading → InGame ⇄ Paused
|
|||||||
|
|
||||||
13. DA_ItemData assets are loaded on demand ← Asset Manager async loads
|
13. DA_ItemData assets are loaded on demand ← Asset Manager async loads
|
||||||
14. FL_GameUtilities calls available immediately ← Static library
|
14. FL_GameUtilities calls available immediately ← Static library
|
||||||
15. GI_GameTagRegistry.OnAssetLoaded() ← Fires when data asset loads
|
15. DA_GameTagRegistry loaded by Asset Manager ← Fires when data asset loads (no native OnAssetLoaded in BP)
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
@@ -385,7 +385,7 @@ MainMenu → Loading → InGame ⇄ Paused
|
|||||||
| `GI_GameFramework` | GamePhase, session flags | Server sets; clients read via replicated dispatcher |
|
| `GI_GameFramework` | GamePhase, session flags | Server sets; clients read via replicated dispatcher |
|
||||||
| `GM_CoreGameMode` | Player spawning, chapter transitions, death routing | Server-only (extends replicated GameMode) |
|
| `GM_CoreGameMode` | Player spawning, chapter transitions, death routing | Server-only (extends replicated GameMode) |
|
||||||
| `GS_CoreGameState` | Shared session state bus | **Fully replicated** — 5 vars with OnRep handlers |
|
| `GS_CoreGameState` | Shared session state bus | **Fully replicated** — 5 vars with OnRep handlers |
|
||||||
| `GI_GameTagRegistry` | Tag documentation | Read-only config — identical on all clients |
|
| `DA_GameTagRegistry` | Tag documentation | Read-only config — identical on all clients |
|
||||||
| `FL_GameUtilities` | Static utilities | No state — callable from any side |
|
| `FL_GameUtilities` | Static utilities | No state — callable from any side |
|
||||||
| `I_InterfaceLibrary` | Communication contracts | Interface calls work on any side; mutators must check authority |
|
| `I_InterfaceLibrary` | Communication contracts | Interface calls work on any side; mutators must check authority |
|
||||||
| `DA_ItemData` | Item definitions | Read-only Data Asset — identical on all clients |
|
| `DA_ItemData` | Item definitions | Read-only Data Asset — identical on all clients |
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
# Developer Reference — UE5 Modular Game Framework
|
# Developer Reference — UE5 Modular Game Framework
|
||||||
|
|
||||||
**Version:** 1.2 | **Generated:** 2026-05-19 | **Files:** 15 (1 index + 2 overview + 1 migration + 10 category docs + 1 combined) | **Networking:** All docs include multiplayer sections
|
**Version:** 1.3 | **Generated:** 2026-05-20 | **Files:** 16 (1 index + 2 overview + 1 migration + 1 starter + 10 category docs + 1 combined) | **Networking:** All docs include multiplayer sections
|
||||||
|
|
||||||
This directory contains developer-facing reference documentation for every system in the framework. Unlike the blueprint spec files (which define *what* to build), these documents explain *how each system works internally* — the data flow, state machines, integration points, and design rationale. Use these when you need to understand a system's behavior to implement, debug, or extend it.
|
This directory contains developer-facing reference documentation for every system in the framework. Unlike the blueprint spec files (which define *what* to build), these documents explain *how each system works internally* — the data flow, state machines, integration points, and design rationale. Use these when you need to understand a system's behavior to implement, debug, or extend it.
|
||||||
|
|
||||||
@@ -21,6 +21,7 @@ docs/developer/
|
|||||||
├── project-setup-migration.md ← Project setup & migration guide (NEW — Project Settings, plugins, init sequence)
|
├── project-setup-migration.md ← Project setup & migration guide (NEW — Project Settings, plugins, init sequence)
|
||||||
│
|
│
|
||||||
├── 01-core-foundation.md ← Foundation systems (systems 01-07)
|
├── 01-core-foundation.md ← Foundation systems (systems 01-07)
|
||||||
|
├── 00-starter-gameinstance.md ← Starter GameInstance: GI_StarterGameInstance setup guide
|
||||||
├── 02-player-systems.md ← Player state & embodiment (systems 08-15)
|
├── 02-player-systems.md ← Player state & embodiment (systems 08-15)
|
||||||
├── 03-interaction-systems.md ← Interaction & world manipulation (systems 16-23)
|
├── 03-interaction-systems.md ← Interaction & world manipulation (systems 16-23)
|
||||||
├── 04-inventory-systems.md ← Inventory, items & collectibles (systems 24-34)
|
├── 04-inventory-systems.md ← Inventory, items & collectibles (systems 24-34)
|
||||||
@@ -37,7 +38,8 @@ docs/developer/
|
|||||||
|
|
||||||
| # | System | Category | Role |
|
| # | System | Category | Role |
|
||||||
|---|--------|----------|------|
|
|---|--------|----------|------|
|
||||||
| 01 | `GI_GameTagRegistry` | Foundation | Central GameplayTag → asset registry |
|
| — | `GI_StarterGameInstance` | Project Setup | Minimal GameInstance; tag validation entry point |
|
||||||
|
| 01 | `DA_GameTagRegistry` | Foundation | Central GameplayTag → asset registry |
|
||||||
| 02 | `FL_GameUtilities` | Foundation | Shared utility functions (logging, math) |
|
| 02 | `FL_GameUtilities` | Foundation | Shared utility functions (logging, math) |
|
||||||
| 03 | `I_InterfaceLibrary` | Foundation | All framework interfaces |
|
| 03 | `I_InterfaceLibrary` | Foundation | All framework interfaces |
|
||||||
| 04 | `GI_GameFramework` | Foundation | Application kernel; owns subsystems |
|
| 04 | `GI_GameFramework` | Foundation | Application kernel; owns subsystems |
|
||||||
@@ -176,7 +178,7 @@ docs/developer/
|
|||||||
## How to Use These Docs
|
## How to Use These Docs
|
||||||
|
|
||||||
1. **New to the framework?** Start with [`architecture-overview.md`](architecture-overview.md) to understand the big picture.
|
1. **New to the framework?** Start with [`architecture-overview.md`](architecture-overview.md) to understand the big picture.
|
||||||
2. **Setting up a new project?** Read [`project-setup-migration.md`](project-setup-migration.md) — covers all Project Settings, plugins, Data Tables, Enhanced Input, and initialization sequence.
|
2. **Setting up a new project?** Read [`00-starter-gameinstance.md`](00-starter-gameinstance.md) first — create `GI_StarterGameInstance` to validate your GameplayTags immediately. Then follow [`project-setup-migration.md`](project-setup-migration.md) for full Project Settings, plugins, Data Tables, and init sequence.
|
||||||
3. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic.
|
3. **Implementing a system?** Read the Blueprint Spec in `docs/blueprints/` — every file has a Manual Implementation Guide with node-by-node logic.
|
||||||
4. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory.
|
4. **Need to understand internals?** Read the corresponding Developer Reference doc in this directory.
|
||||||
5. **Debugging?** Each category doc includes a data flow section showing how data moves between systems.
|
5. **Debugging?** Each category doc includes a data flow section showing how data moves between systems.
|
||||||
|
|||||||
@@ -78,7 +78,7 @@ No hardcoded values. Every configuration lives in Data Assets (`DA_ItemData`, `D
|
|||||||
Widgets display data from gameplay systems but never own game state. They bind to event dispatchers (`OnHealthChanged` → update health bar) and call functions (`UseItem()`) — but never store authoritative data.
|
Widgets display data from gameplay systems but never own game state. They bind to event dispatchers (`OnHealthChanged` → update health bar) and call functions (`UseItem()`) — but never store authoritative data.
|
||||||
|
|
||||||
### 5. GameplayTags for State, Not Booleans
|
### 5. GameplayTags for State, Not Booleans
|
||||||
No `bIsDead`, `bIsHidden`, `bIsInCombat` booleans. Everything is a GameplayTag compared via `HasTag()` / `MatchesTag()`. Tags are documented in `GI_GameTagRegistry`.
|
No `bIsDead`, `bIsHidden`, `bIsInCombat` booleans. Everything is a GameplayTag compared via `HasTag()` / `MatchesTag()`. Tags are documented in `DA_GameTagRegistry`.
|
||||||
|
|
||||||
### 6. Single Audio Entry Point (SS_AudioManager)
|
### 6. Single Audio Entry Point (SS_AudioManager)
|
||||||
Never call `UGameplayStatics::PlaySound*` directly. All audio routes through `SS_AudioManager` which manages 4 MetaSound buses (SFX, Ambience, Music, Dialogue → Master Bus). Room acoustics switch automatically via `BP_RoomAudioZone` triggers.
|
Never call `UGameplayStatics::PlaySound*` directly. All audio routes through `SS_AudioManager` which manages 4 MetaSound buses (SFX, Ambience, Music, Dialogue → Master Bus). Room acoustics switch automatically via `BP_RoomAudioZone` triggers.
|
||||||
|
|||||||
@@ -243,7 +243,7 @@
|
|||||||
|
|
||||||
**Key Rules:**
|
**Key Rules:**
|
||||||
- Framework tags use `Framework.` prefix; project tags use `Game.` prefix
|
- Framework tags use `Framework.` prefix; project tags use `Game.` prefix
|
||||||
- All tags documented in `GI_GameTagRegistry`
|
- All tags documented in `DA_GameTagRegistry`
|
||||||
- Never use `FName` or `FString` for state — always GameplayTags
|
- Never use `FName` or `FString` for state — always GameplayTags
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
Reference in New Issue
Block a user