CultLib/src/GameCult.Caching
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-05-09 11:14:23 +01:00
..
Contracts Specify canonical CultCache persistence format 2026-05-08 00:16:55 +01:00
CultCache.cs Fix CultLib nullable warnings 2026-05-09 11:14:23 +01:00
CultDocumentContracts.cs Document CultCache and CultNet public surface 2026-05-08 13:11:01 +01:00
CultGeneratedDocumentMetadata.cs Document CultCache and CultNet public surface 2026-05-08 13:11:01 +01:00
GameCult.Caching.csproj Initial commit 2026-04-18 06:04:39 +01:00
GameCult.Caching.txt Initial commit 2026-04-18 06:04:39 +01:00
README.md Remove alternate CultCache backing stores 2026-05-08 02:42:11 +01:00
ReflectionExtensions.cs Rewrite CultCache as attribute-first storage 2026-05-08 01:13:15 +01:00

GameCult.Caching

GameCult.Caching is an attribute-driven typed cache with a canonical single-file MessagePack store. Domain models stay clean. The cache owns record keys, schema ids, timestamps, and persistence metadata instead of smearing that sludge across every class.

Authoring Model

Cacheable models are plain classes annotated with cache intent.

using GameCult.Caching;
using MessagePack;

[CultDocument("gamecult.item_data", "gamecult.item_data.v1")]
public sealed class ItemData
{
    [Key(0)]
    [CultName]
    public string Name = string.Empty;

    [Key(1)]
    [CultIndex]
    public string Category = string.Empty;

    [Key(2)]
    public int Value;
}

Available cache attributes:

  • CultDocument(schemaName, schemaVersion)
  • CultName
  • CultIndex(alias?)
  • CultGlobal
  • CultReference(targetType?, many: false)

If you want compile-time document metadata instead of runtime assembly spelunking, add the GameCult.Caching.MessagePack.Generator analyzer to the project that declares your [CultDocument] types. It emits a metadata provider the cache registry can load directly, while reflection stays behind as fallback for projects that have not taken the hint yet.

Main Concepts

Record keys and handles

CultCache gives each stored document a cache-owned CultRecordKey. You work with typed handles instead of forcing storage identity into the domain object.

var cache = new CultCache();
var handle = await cache.AddAsync(new ItemData
{
    Name = "Potion",
    Category = "Consumable",
    Value = 50
});

var potion = cache.Get<ItemData>(handle.Key);

Name and index lookups

Name and index lookups are driven from attributes, not manual registration.

var byName = cache.GetByName<ItemData>("Potion");
var byIndex = cache.GetByIndex<ItemData>("Category", "Consumable");

Explicit references

References stay explicit in the domain. The cache will resolve them on demand, but it will not quietly build an entire haunted object graph behind your back.

[CultDocument("gamecult.quest_data", "gamecult.quest_data.v1")]
public sealed class QuestData
{
    [Key(0)] public string Title = string.Empty;
    [Key(1)] [CultReference] public CultRecordRef<ItemData> Reward;
}

Persistence Shape

CultCache persistence is store-shaped, not entry-shaped:

  1. store header
  2. embedded schema catalog
  3. records

Each persisted record carries:

  • key
  • schemaId
  • storedAt
  • payload

The domain payload stays free of storage metadata.

Backing Store

CultCache now has one sanctioned persistence format:

  • SingleFileMessagePackBackingStore

It persists the whole store as:

  1. store format version
  2. embedded schema catalog
  3. persisted records

Each persisted record carries:

  • key
  • schemaId
  • storedAt
  • payload

Typical Startup

using GameCult.Caching;
using GameCult.Caching.MessagePack;

var cache = new CultCache();
var store = new SingleFileMessagePackBackingStore("Data.msgpack");

cache.AddBackingStore(store);
await cache.PullAllBackingStoresAsync();