Skip to content

t1k:unity:base:blueprint-csv

FieldValue
Modulebase
Version5.116.6
Effortlow
Tools—

Keywords: battlepass blueprint, blueprint, blueprintmanager, blueprintutils, csv, csvcolumn, csvdata, csvignore, csvoptional, csvrow, enemy stats, gacha blueprint, progression reward blueprint, theone.data

/t1k:unity:base:blueprint-csv

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, package com.theone.data, Library/PackageCache/com.theone.data*/Scripts/X.Data.asmdef) uses using X.Data; (and X.Extensions for [Key]); older games still use TheOne.Data. Read the project’s existing blueprint .cs (e.g. Assets/Scripts/Blueprints/*.cs) or the package asmdef for the using line before generating records; the wrong one fails with CS0246.
  • Container base: CsvData<TKey, TValue> (dictionary) or CsvData<T> (list). Both implement ICsvData — that interface is the type BlueprintManager loads (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 ICsvData becomes a nested sub-table (advanced; see CsvSerializer for the row-grouping rules).
  • Parser: CsvHelper (org.nuget.csvhelper) + IConverterManager. Requires the X_CSV and X_UNITASK scripting defines.
  • Int keys are fine: CsvData<int, TRecord> works when the first column is an integer id; the record property is public int RealmId { get; } (no = null!).

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:

  1. CSV asset in the project’s blueprint folder, named <ClassName>.csv.
  2. Addressable entry — add the CSV to the project’s Blueprints addressable group (e.g. Assets/AddressableAssetsData/AssetGroups/Blueprints.asset) with m_Address = the blueprint class name (must equal type.GetKey()). AssetTextDataStorage loads the TextAsset at that address via IAssetsManager. Register via the editor Addressables window or AddressableAssetSettings.CreateOrMoveEntry(guid, group) + entry.address = className.
  3. Registration — in the owning module’s VContainer (Configure/RegisterServices) call builder.RegisterBlueprint<FooBlueprint>(); (extension in GameFoundation.Scripts.Blueprints). Skipping it loads nothing and Get<T>() later logs Critical (“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>().

Managed systems reach BlueprintManager through the service bridge (registered with builder.RegisterServiceBridge<BlueprintManager>();):

if (!ManagedServiceBridge<BlueprintManager>.IsReady) return; // bridge not ready yet
var 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 */ }
  • First row is the header. Column names bind to the record’s properties/fields (case-sensitive).
  • Empty cells: leave blank — do not write null or "". 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.

  • Enter Play mode and trigger the feature that consumes the blueprint; confirm the records resolve (e.g. blueprint[id] returns data, no KeyNotFound, and BlueprintManager logs Loaded 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 found unless the field is [CsvOptional]/[CsvIgnore].
  • Get<T>() is cache-only and never throws. It logs Critical and returns an empty instance when the blueprint is missing; it never triggers a synchronous load. If you see a Blueprint X not loaded/not registered Critical log, the cause is a missing RegisterBlueprint<T>() call, a missing/mis-addressed CSV (address ≠ class name), or reading before BlueprintsLoadedSignal.
  • Never cache the Get<T>() result in a field — always a private computed property. Constructor-inject BlueprintManager, then private FooBlueprint blueprint => this.blueprintManager.Get<FooBlueprint>();. A field initialized at construction (= this.blueprintManager.Get<T>()) resolves before BlueprintsLoadedSignal and 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. BlueprintManager loads 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.