Skip to content

t1k:unity:base:blueprint-migrate

FieldValue
Modulebase
Version5.116.6
Effortlow
Tools—

Keywords: blueprint migration, BlueprintByRow, blueprintflow, blueprintManager.Get, BlueprintReader, BlueprintsLoadedSignal, computed property, CsvHeaderKey, GenericBlueprintReaderByCol, GenericBlueprintReaderByList, GenericBlueprintReaderByRow, GetAllData, GetDataById, migrate blueprint

/t1k:unity:base:blueprint-migrate

Migrate Blueprints → TheOne.Data.CsvData<,>

Section titled “Migrate Blueprints → TheOne.Data.CsvData<,>”

Port a Unity blueprint from the legacy BlueprintFlow reader (GenericBlueprintReaderByRow<,>, GenericBlueprintReaderByCol, GenericBlueprintReaderByList<>) to the current TheOne.Data.CsvData<,> mechanism, which is loaded centrally by BlueprintManager (eager, boot-time, reflection-discovered — no per-blueprint DI registration).

Scope: this is the migration procedure. The authoritative steady-state CSV-format and loader rules live in t1k-unity-base-blueprint-csv — load it alongside this skill. When the two disagree, that skill wins.

This skill applies to one blueprint or fifty. The full step-by-step (Search / Action / Verify per step) is in references/migration-playbook.md — read it before touching code.

  • A blueprint class still inherits GenericBlueprintReader* and you need it on CsvData<,>.
  • A consumer still injects a blueprint type directly (constructor / [Inject] / Resolve<XxxBlueprint>()) and must switch to BlueprintManager.Get<T>().
  • A controller resolves IWritableData/UserDataManager.Get<T>() once in its constructor and you need the lazy computed-property idiom.
  • Authoring a brand-new blueprint (already CsvData<,>) → use t1k-unity-base-blueprint-csv.
  • …ByCol targets the single-record base CsvData / CsvRecordData (not the list CsvData<T>); …ByList differs too — see the playbook’s scope note; do not treat either as a 1:1 ByRow swap.
  • Editing a blueprint shipped inside a submodule/package (Packages/com.gdk.core, com.theone.data) — those are read-only from the consumer; PR the owning repo.
ConcernLegacy (BlueprintFlow)Current (TheOne.Data)
Base classGenericBlueprintReaderByRow<TKey,TRecord>CsvData<TKey,TRecord> (dict) / CsvData<T> (list)
Nested tableBlueprintByRow<TKey,TRecord> fieldCsvData<TKey,TRecord> field
Data id / address[BlueprintReader("Some/Path", true)]Addressable address == type.GetKey() ([Key] value, else class name)
Key column[CsvHeaderKey("Col")]record’s first field, or [CsvRow("", "Col")]
Read one rowbp.GetDataById(id) (null if missing)bp[id] (throws) / bp.TryGetValue(id, out v)
Read allbp.GetAllData()bp.Values (IEnumerable<TValue>)
How it’s obtainedinjected directly as XxxBlueprintinject BlueprintManager, call Get<XxxBlueprint>()
Registrationper-reader, autonone — BlueprintManager auto-discovers every ICsvData and eager-loads at boot

Key consequence: the migrated blueprint type is no longer in the DI container. Every consumer that injected it MUST switch to BlueprintManager. This is a compile- and runtime requirement, not optional cleanup.

1. Swap the blueprint class + record (playbook §2)

Section titled “1. Swap the blueprint class + record (playbook §2)”
// before
[BlueprintReader("GameplayData/Foo", true)]
[CsvHeaderKey("Id")]
public class FooBlueprint : GenericBlueprintReaderByRow<int, FooRecord> { }
// after
using TheOne.Data;
public class FooBlueprint : CsvData<int, FooRecord> { } // Id is FooRecord's first field → key
  • using BlueprintFlow.BlueprintReader; → using TheOne.Data;
  • Drop [BlueprintReader(...)] and [CsvHeaderKey(...)].
  • Nested BlueprintByRow<K,V> field → CsvData<K,V> field.
  • Key field = first declared field by default; if not, reorder it or add [CsvRow("", "ColumnName")].
  • Keep any extra interface the record implements for other systems (e.g. a project IGameData) — harmless to CSV binding.

2. Rewire every consumer to BlueprintManager (playbook §3)

Section titled “2. Rewire every consumer to BlueprintManager (playbook §3)”

Add using GameFoundation.Scripts.Blueprints;, inject BlueprintManager, expose a computed property:

private readonly BlueprintManager blueprintManager;
private FooBlueprint fooBlueprint => this.blueprintManager.Get<FooBlueprint>();
public Foo(BlueprintManager blueprintManager) => this.blueprintManager = blueprintManager;

Call-site swaps: GetDataById(id) → bp[id] (or TryGetValue), GetAllData() → bp.Values, nested.Values.Count → nested.Count. Load-gate LoadBlueprintDataSucceedSignal → BlueprintsLoadedSignal.

6. Fix the IWritableData constructor-resolve anti-pattern (playbook §3a)

Section titled “6. Fix the IWritableData constructor-resolve anti-pattern (playbook §3a)”

Same idiom for user-data: store UserDataManager, resolve lazily — never cache the data instance in the ctor (it may not be loaded at construction time).

// ✅ correct
private readonly UserDataManager userDataManager;
private XxxLocalData xxxLocalData => this.userDataManager.Get<XxxLocalData>();
public XxxController(UserDataManager userDataManager) => this.userDataManager = userDataManager;
// ❌ wrong — resolves once in the ctor, before user data is guaranteed loaded
private readonly XxxLocalData xxxLocalData;
public XxxController(UserDataManager u) => this.xxxLocalData = u.Get<XxxLocalData>();
  • Get<T>() is cache-only and throws if the blueprint wasn’t loaded at boot — it never triggers a synchronous load. Blueprint X was not loaded almost always = missing/mis-addressed CSV (address ≠ class name), not a missing DI registration.
  • .Values is IEnumerable<T> — use .Count (dictionary) or .Values.Count() (LINQ), never .Values.Count (property).
  • Class-only or CSV-only edits drift silently — add/rename/remove a column and the record field in the same change; a missing required column throws Column … not found unless [CsvOptional]/[CsvIgnore].
  • CSV + Addressable is an Editor step — the Addressable address MUST equal the class name; use the project’s blueprint-addressable setup tool (a MenuItem), do not hand-edit the group YAML. Never Reimport All, never kill the editor.
  • Static grep is not a compile — if Unity is closed, state the change is unverified by the compiler.
  • t1k-unity-base-blueprint-csv — authoritative CSV-format + loader reference (steady state).
  • t1k-unity-base-code-conventions — The1Studio C# conventions for the touched files.