FM39hz.DataCatalyst 0.2.5

DataCatalyst

Roslyn source generator: JSON → strongly-typed C# struct + enum + FrozenDictionary at compile time. Zero reflection. NativeAOT-safe. Engine-agnostic.

Requirements

• .NET 8+ / .NET Standard 2.0+
• C# 12+

Quick start

Installation

dotnet add package FM39hz.DataCatalyst --version 0.2.4

Project setup

<ItemGroup>
  <AdditionalFiles Include="Data\*.json" />
</ItemGroup>

[CatalystData("Items.json")]
public partial struct Item { }

var hp = Item.Potion.Health;
var item = Item.Get(ItemKind.Elixir);
var heavy = Item.Query(x => x.Weight > 1f);
Item.TryGetKind("Potion", out var kind);

Backend switching

[CatalystData("Items.json", Backend = DataBackendConst.All)]
public partial struct Item { }

SQLite — IDbConnection/DbDataReader, no hard dep:

ItemSql.CreateSelectAllCommand(conn);
ItemSql.ReadRow((DbDataReader)reader);
var repo = new ItemSqlRepository(() => new SqliteConnection("..."));

JSON — Utf8JsonReader, no reflection:

ItemJson.Read(ref reader);
ItemJson.LoadAll("items.json");

Env: DATACATALYST_BACKEND, DATACATALYST_CONNECTION, DATACATALYST_DATAPATH.

Mod content — runtime, drop-in files

[CatalystData("Items.json", ModSupport = true)]
public partial struct Item { }

ItemMod.LoadMods("mods/items/");           // JSON files at runtime
ItemMod.AddEntry("SuperPotion", new() { Health = 999 });
ItemMod.RemoveEntry("OldPotion");
var item = Item.Get(ItemKind.Potion);      // mod override → core

Engine adapter — notified on every change:

public class EcsItemAdapter : IDataViewAdapter<Item> {
    public void OnEntryAdded(string key, Item entry) { /* create entity */ }
    public void OnEntryRemoved(string key) { /* destroy entity */ }
    public void OnAllCleared() { /* destroy all */ }
}

DSL reader — custom text format:

public sealed class YamlItemReader : IDslReader<Item> {
    public string FileExtension => ".yaml";
    public bool TryRead(string text, out Item value) { /* parse */ }
}

Steam Workshop / Nexus

public override void _Ready() {
    ItemMod.LoadMods("Mods/Items");
    DataViewAdapterRegistry.Register<Item>(new MyAdapter(_store));
    PluginRegistry.LoadAll(new ModGameContext());
}

Code mod — scripting layer

Add a Lua/C# scripting VM on top of DataCatalyst's data API:

// Lua: Data.Add("Item", "FireSword", { Weight = 3, Health = 80 })
// Lua: ECS.RegisterSystem("BurnAura", { run = function(dt, e) end })

public sealed class ScriptBridge {
    Script _lua = new();
    public ScriptBridge() {
        _lua.Globals["Data"] = new DataBridge();
    }

    public void LoadModScripts(string dir) {
        foreach (var file in Directory.EnumerateFiles(dir, "*.lua"))
            _lua.DoFile(file);
    }
}

Code mod — build merge (MSBuild)

<PropertyGroup><EnableModMerge>true</EnableModMerge></PropertyGroup>

Mods/
├── SkillPack/
│   ├── mod.json
│   ├── Skills.cs                          ← compiled
│   └── skills_override.json               ← AdditionalFiles

[ModPlugin("SkillPack")]
public class SkillPack : IModPlugin {
    public void OnLoad(IModGameContext ctx) {
        ItemMod.AddEntry("SuperPotion", new() { Health = 500 });
        ctx.GetService<ISystemRegistry>()?.Register(new CombatLevelSystem());
    }
}

Build: dotnet publish -p:EnableModMerge=true

Trade-offs: compile-time baking = zero runtime cost, memory-resident. Scripting (Lua, C#) is the game's responsibility — DataCatalyst handles data.

Cross-catalog references

[CatalystData("buffs.json", typeof(BuffTemplate))]
public partial struct Buff { }

[CatalystData("items.json", typeof(ItemTemplate), RefTo = new[] { typeof(Buff) })]
public partial struct Item { }

var buff = Buff.Get(item.BuffRef.Kind);

DataCatalyst topo-sorts by RefTo — referenced catalogs are processed first.

Generated API

All catalogs auto-register into CatalogRegistry.

Load mode

[CatalystData("Items.json")]                          // Lazy (default): Repository on first Get
[CatalystData("Items.json", LoadMode = LoadModeConst.Eager)]  // Eager: FrozenDictionary at module init

Generated components

Examples

Extension points

License

MIT