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.*
|
||||
Reference in New Issue
Block a user