t1k:unity:base:blueprint-csv
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| Tools | — |
Keywords: battlepass blueprint, blueprint, blueprintmanager, blueprintutils, csv, csvcolumn, csvdata, csvignore, csvoptional, csvrow, enemy stats, gacha blueprint, progression reward blueprint, theone.data
How to invoke
Section titled “How to invoke”/t1k:unity:base:blueprint-csvCSV Blueprint Editing
Section titled “CSV Blueprint Editing”Blueprints are CSV-driven configs read at runtime. A CSV blueprint is two parts: a plaintext .csv (the data) and a C# class pair (a container + a row record) that the CSV columns bind to.
Scope: this skill covers the CSV blueprint format (
TheOne.Data.CsvData<,>). Sibling formats (e.g.blueprint:json) are separate skills. There is now one CSV mechanism —CsvData<,>— and one loader —BlueprintManager(centralized, eager, boot-time).
The class pair — TheOne.Data (com.theone.data)
Section titled “The class pair — TheOne.Data (com.theone.data)”namespace MyGame.Features.Foo.Models{ using TheOne.Data;
// Container: a dictionary keyed by the first column (or the [CsvRow] key). public sealed class FooBlueprint : CsvData<string, FooRecord> { }
// Row record: a plain POCO. Each column binds to a property/field by name. public sealed class FooRecord { public string Id { get; set; } = null!; // first column → dictionary key (default) public int Cost { get; set; } public Rarity Rarity { get; set; } // enums/Vector/Color auto-convert }}- Namespace depends on the base: a template made from the renamed base (assembly
X.Data, packagecom.theone.data,Library/PackageCache/com.theone.data*/Scripts/X.Data.asmdef) usesusing X.Data;(andX.Extensionsfor[Key]); older games still useTheOne.Data. Read the project’s existing blueprint.cs(e.g.Assets/Scripts/Blueprints/*.cs) or the package asmdef for theusingline before generating records; the wrong one fails with CS0246. - Container base:
CsvData<TKey, TValue>(dictionary) orCsvData<T>(list). Both implementICsvData— that interface is the typeBlueprintManagerloads (each type must be registered, see below). - Key column: by default the first column is the dictionary key. Override with
[CsvRow(prefix, key)]on the record (key= the column name to use as key;prefix= a string prepended to every column name). - Column name: defaults to the property/field name. Override per field with
[CsvColumn("Header Name")]. [CsvIgnore]— skip a field.[CsvOptional]— field’s column may be absent from the CSV (no throw).- Nested tables: a field whose type is itself an
ICsvDatabecomes a nested sub-table (advanced; seeCsvSerializerfor the row-grouping rules). - Parser: CsvHelper (
org.nuget.csvhelper) +IConverterManager. Requires theX_CSVandX_UNITASKscripting defines. - Int keys are fine:
CsvData<int, TRecord>works when the first column is an integer id; the record property ispublic int RealmId { get; }(no= null!).
File location
Section titled “File location”Author the plaintext CSV in the project’s flat blueprint folder (e.g. Assets/Blueprints/<ClassName>.csv — pick one folder per project and keep all blueprint CSVs flat under it; the exact path is a project convention, not a hard requirement). The hard rule is the filename/address, not the folder: the filename stem must equal type.GetKey() — the [TheOne.Extensions.Key("…")] value on the class, or the type name if no [Key] is present (the editor loader BlueprintUtils resolves a blueprint’s CSV by FindAssetByName(type.GetKey()), and the runtime resolves the Addressable by the same key). There is no encryption step — the runtime reads the plaintext CSV directly.
Loading & runtime wiring — centralized via BlueprintManager
Section titled “Loading & runtime wiring — centralized via BlueprintManager”Loading is centralized but registration-driven. BlueprintManager (in GameFoundation.Scripts.Blueprints, package com.gdk.core) is an IAsyncEarlyLoadable that eager-loads every registered blueprint once at boot into an in-memory map, then fires BlueprintsLoadedSignal. It does no reflection discovery: its constructor takes the injected IEnumerable<IBlueprintLoadRequest> and LoadAsync iterates exactly that list. A type enters the list only through builder.RegisterBlueprint<T>() (BlueprintVContainer, which registers a BlueprintLoadRequest<T> singleton), so a new blueprint needs one RegisterBlueprint<T>() call in its owning module’s VContainer. A blueprint with a CSV and Addressable entry but no registration is silently absent from the load set.
Adding a new blueprint is therefore three steps:
- CSV asset in the project’s blueprint folder, named
<ClassName>.csv. - Addressable entry — add the CSV to the project’s
Blueprintsaddressable group (e.g.Assets/AddressableAssetsData/AssetGroups/Blueprints.asset) withm_Address= the blueprint class name (must equaltype.GetKey()).AssetTextDataStorageloads theTextAssetat that address viaIAssetsManager. Register via the editor Addressables window orAddressableAssetSettings.CreateOrMoveEntry(guid, group)+entry.address = className. - Registration — in the owning module’s VContainer (
Configure/RegisterServices) callbuilder.RegisterBlueprint<FooBlueprint>();(extension inGameFoundation.Scripts.Blueprints). Skipping it loads nothing andGet<T>()later logsCritical(“not registered”) and returns an empty instance.
That’s it — no per-feature loader class. BlueprintManager itself is registered once centrally in GameFoundationVContainer (builder.Register<BlueprintManager>(Lifetime.Singleton).AsSelf().AsImplementedInterfaces();) and its IAsyncEarlyLoadable.LoadAsync runs during boot.
Consuming a blueprint (managed / VContainer code)
Section titled “Consuming a blueprint (managed / VContainer code)”Inject BlueprintManager and always read through a private computed property — never cache the Get<T>() result in a field. Get<T>() is cache-only: it returns the boot-loaded instance, and when the blueprint is not in the cache it does not throw — it logs Critical (“not loaded” if registered but boot load incomplete, “not registered” if RegisterBlueprint<T>() was never called) and returns a fresh empty instance, i.e. silent bad data. A field initialized at construction (private readonly FooBlueprint blueprint = this.blueprintManager.Get<FooBlueprint>();) runs before boot load completes → captures an empty instance. The computed property defers the lookup to use-time (post-boot) and always resolves the canonical cached instance. This is the only sanctioned access shape:
public sealed class FooService{ private readonly BlueprintManager blueprintManager; [Preserve] public FooService(BlueprintManager blueprintManager) => this.blueprintManager = blueprintManager;
// ALWAYS a computed property — never `= this.blueprintManager.Get<...>()` in a field (cache-only, empty instance pre-boot). private FooBlueprint blueprint => this.blueprintManager.Get<FooBlueprint>();}Code that runs before boot completes can gate on BlueprintsLoadedSignal before its first Get<T>().
Consuming from DOTS / unmanaged systems
Section titled “Consuming from DOTS / unmanaged systems”Managed systems reach BlueprintManager through the service bridge (registered with builder.RegisterServiceBridge<BlueprintManager>();):
if (!ManagedServiceBridge<BlueprintManager>.IsReady) return; // bridge not ready yetvar blueprint = ManagedServiceBridge<BlueprintManager>.Instance.Get<EnemyStatsBlueprint>();Reading a blueprint in an Editor validator
Section titled “Reading a blueprint in an Editor validator”Editor-time code (validators, tooling) uses the static BlueprintUtils.Get<T>() (in GameFoundation.Editor.Validator). It deserializes the blueprint’s CSV (<Key>.csv) through a throwaway CsvSerializer built from the same DI graph and returns an empty instance (never throws) when the CSV is missing:
if (BlueprintUtils.Get<FooBlueprint>() is { } foo) { /* validate foo */ }CSV format rules
Section titled “CSV format rules”- First row is the header. Column names bind to the record’s properties/fields (case-sensitive).
- Empty cells: leave blank — do not write
nullor"". Blank → the converter’s default for that type. - A comma inside a value: wrap the whole cell in double quotes.
- Line endings: match the existing file (LF vs CRLF) to avoid noisy diffs.
- No trailing blank line — the parser can read it as an empty-key row and throw.
Data modeling — separate logic data from visualization data
Section titled “Data modeling — separate logic data from visualization data”Keep logic data (gameplay numbers, ids, formulas, rarity, cooldowns, costs, unlock gates) separate from visualization data (which prefab / sprite / icon / VFX / sound / animation an entity uses) — either as clearly-grouped columns within one CSV, or (preferred for real presentation data) a separate CSV/blueprint keyed by the same Id. Designers then tune balance without touching art bindings and vice-versa. Asset references are always addressable keys/AssetReference, not file paths. Full Logic/Visual family convention (naming, boundary rules for ambiguous fields like DisplayName, folder organization, SSOT precedence): references/logic-visual-data-split.md.
Verification
Section titled “Verification”- Enter Play mode and trigger the feature that consumes the blueprint; confirm the records resolve (e.g.
blueprint[id]returns data, noKeyNotFound, andBlueprintManagerlogsLoaded N blueprints.with the count including yours). - Schema change (added/removed/renamed column) → update the record class in the same change. A CSV-only edit silently drops the unmapped column; a class-only edit throws
Column … not foundunless the field is[CsvOptional]/[CsvIgnore].
Hard rules
Section titled “Hard rules”Get<T>()is cache-only and never throws. It logsCriticaland returns an empty instance when the blueprint is missing; it never triggers a synchronous load. If you see aBlueprint X not loaded/not registeredCritical log, the cause is a missingRegisterBlueprint<T>()call, a missing/mis-addressed CSV (address ≠ class name), or reading beforeBlueprintsLoadedSignal.- Never cache the
Get<T>()result in a field — always a private computed property. Constructor-injectBlueprintManager, thenprivate FooBlueprint blueprint => this.blueprintManager.Get<FooBlueprint>();. A field initialized at construction (= this.blueprintManager.Get<T>()) resolves beforeBlueprintsLoadedSignaland captures an empty instance; constructor-injecting the blueprint instance directly (rather than the manager) has the same failure. The computed property is the only shape that survives boot ordering. - Forgetting
RegisterBlueprint<T>()is the #1 silent failure.BlueprintManagerloads only registered types (no assembly scan), so a CSV + Addressable entry without the registration never loads. Check the owning module’s VContainer first. - No encryption /
EncryptedData/folder. Older docs describing a “plaintext + encrypted twin” pair and an “Encrypt Blueprints” tool do not apply — the runtime reads plaintext. - Columns bind by name, not order — renaming a property without updating the CSV header drops that column silently (or throws if the field is required).
- Submodule files are READ-ONLY from the consumer side. To change a default blueprint shipped in
com.gdk.core/com.theone.data, edit the submodule repo and PR there — not the consumer project.