fee12b115f
- 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.
125 lines
6.2 KiB
Markdown
125 lines
6.2 KiB
Markdown
# 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.*
|