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
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 |
|
||||
|---|--------|-----------|------|
|
||||
| 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) |
|
||||
| 03 | `I_InterfaceLibrary` | Interface Collection | All 9 framework interfaces for decoupled communication |
|
||||
| 04 | `GI_GameFramework` | Game Instance | Application kernel; owns subsystems, manages game phases |
|
||||
@@ -42,7 +42,7 @@
|
||||
│ ├─► Bind to GI_GameFramework.OnGamePhaseChanged │
|
||||
│ └─► 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 communicate via I_InterfaceLibrary interfaces │
|
||||
│ 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.
|
||||
|
||||
@@ -298,7 +298,7 @@ MainMenu → Loading → InGame ⇄ Paused
|
||||
**How It Works Internally:**
|
||||
|
||||
**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
|
||||
- `Icon` (Texture2D soft reference) — UI icon
|
||||
- `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
|
||||
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 |
|
||||
| `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 |
|
||||
| `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 |
|
||||
| `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 |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
|
||||
@@ -21,6 +21,7 @@ docs/developer/
|
||||
├── project-setup-migration.md ← Project setup & migration guide (NEW — Project Settings, plugins, init sequence)
|
||||
│
|
||||
├── 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)
|
||||
├── 03-interaction-systems.md ← Interaction & world manipulation (systems 16-23)
|
||||
├── 04-inventory-systems.md ← Inventory, items & collectibles (systems 24-34)
|
||||
@@ -37,7 +38,8 @@ docs/developer/
|
||||
|
||||
| # | 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) |
|
||||
| 03 | `I_InterfaceLibrary` | Foundation | All framework interfaces |
|
||||
| 04 | `GI_GameFramework` | Foundation | Application kernel; owns subsystems |
|
||||
@@ -176,7 +178,7 @@ docs/developer/
|
||||
## How to Use These Docs
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
### 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)
|
||||
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:**
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user