t1k:unity:base:blueprint-migrate
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| Tools | — |
Keywords: blueprint migration, BlueprintByRow, blueprintflow, blueprintManager.Get, BlueprintReader, BlueprintsLoadedSignal, computed property, CsvHeaderKey, GenericBlueprintReaderByCol, GenericBlueprintReaderByList, GenericBlueprintReaderByRow, GetAllData, GetDataById, migrate blueprint
How to invoke
Section titled “How to invoke”/t1k:unity:base:blueprint-migrateMigrate 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.
When to use
Section titled “When to use”- A blueprint class still inherits
GenericBlueprintReader*and you need it onCsvData<,>. - A consumer still injects a blueprint type directly (constructor /
[Inject]/Resolve<XxxBlueprint>()) and must switch toBlueprintManager.Get<T>(). - A controller resolves
IWritableData/UserDataManager.Get<T>()once in its constructor and you need the lazy computed-property idiom.
When NOT to use
Section titled “When NOT to use”- Authoring a brand-new blueprint (already
CsvData<,>) → uset1k-unity-base-blueprint-csv. …ByColtargets the single-record baseCsvData/CsvRecordData(not the listCsvData<T>);…ByListdiffers too — see the playbook’s scope note; do not treat either as a 1:1ByRowswap.- 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.
Mental model — legacy → current
Section titled “Mental model — legacy → current”| Concern | Legacy (BlueprintFlow) | Current (TheOne.Data) |
|---|---|---|
| Base class | GenericBlueprintReaderByRow<TKey,TRecord> | CsvData<TKey,TRecord> (dict) / CsvData<T> (list) |
| Nested table | BlueprintByRow<TKey,TRecord> field | CsvData<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 row | bp.GetDataById(id) (null if missing) | bp[id] (throws) / bp.TryGetValue(id, out v) |
| Read all | bp.GetAllData() | bp.Values (IEnumerable<TValue>) |
| How it’s obtained | injected directly as XxxBlueprint | inject BlueprintManager, call Get<XxxBlueprint>() |
| Registration | per-reader, auto | none — 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.
The three core moves
Section titled “The three core moves”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> { }
// afterusing TheOne.Data;public class FooBlueprint : CsvData<int, FooRecord> { } // Id is FooRecord's first field → keyusing 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).
// ✅ correctprivate 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 loadedprivate readonly XxxLocalData xxxLocalData;public XxxController(UserDataManager u) => this.xxxLocalData = u.Get<XxxLocalData>();Hard rules
Section titled “Hard rules”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 loadedalmost always = missing/mis-addressed CSV (address ≠ class name), not a missing DI registration..ValuesisIEnumerable<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 foundunless[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.
Related skills
Section titled “Related skills”t1k-unity-base-blueprint-csv— authoritative CSV-format + loader reference (steady state).t1k-unity-base-code-conventions— The1Studio C# conventions for the touched files.