UE5-Modular-Game-Framework/docs/developer/00-starter-gameinstance.md

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.