# 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.*