Vault Hierarchy

Public usage

The up-to-date public persistence API is IVault<T>.

In normal application code you inject IVault<T> directly and work with it through fluent query methods plus terminal async operations. There is no developer-facing VaultRepository or RepositoryFactory flow in the current API.

[Service]
public class PlayerService
{
    private readonly IVault<PlayerVault> _players;

    public PlayerService(IVault<PlayerVault> players)
    {
        _players = players;
    }
}

Runtime layers

#LayerInterface / ClassDescription
1Persistence ProviderIGeneralDatabaseProviderLow-level database connectivity and provider-specific execution
2Vault ImplementationSqlVault<T>Internal fluent vault implementation used by the configured provider
3Public Vault ContractIVault<T>The developer-facing API for querying, saving, updating, deleting, and history
4Vault RegistryVaultRegistryRuntime metadata and dynamic vault lookup for tooling and generic systems

Note:

Most game and service code should stop at IVault<T>. VaultRegistry is mainly for advanced runtime scenarios where the model type is only known dynamically.

Example usage

var highLevelPlayers = await _players
    .Where(p => p.Level >= 50)
    .OrderByDescending(p => p.Level)
    .Take(20)
    .ToListAsync();

var player = await _players
    .Where(p => p.StorageId == playerId)
    .FirstOrDefaultAsync();

await _players.SaveAsync(player);
await _players.SaveAsync(player, saveHistory: true);

Update and delete

IVault<T> also supports update and delete operations over the current fluent query:

await _players
    .Where(p => p.StorageId == playerId)
    .UpdateAsync(setters => setters.SetProperty(p => p.Level, p => p.Level + 1));

await _players
    .Where(p => p.StorageId == playerId)
    .DeleteAsync();

History

Every vault exposes a History accessor, but it is only available when the model enables history with [Vault(..., StoreHistory = true)].

var historicalStates = await _players.History
    .Where(p => p.StorageId == playerId)
    .OrderByDescending(p => p.Timestamp)
    .Take(20)
    .ToListAsync(startTime, endTime);

Use saveHistory: true when saving if you want the current write to also append a historical snapshot.

Dynamic lookup

When you only know the model type at runtime, use VaultRegistry:

var metadata = VaultRegistry.GetByClr(typeof(PlayerVault));
var dynamicVault = VaultRegistry.GetVault(typeof(PlayerVault));
var player = await VaultRegistry.FindByStorageIdAsync(typeof(PlayerVault), playerId);

This is useful for dashboards, admin panels, generic editors, and reflection-driven systems. For regular gameplay or service code, prefer DI with IVault<T>.

Summary

  • IVault<T> is the main public vault API.
  • SqlVault<T> is the internal provider-backed implementation behind it.
  • VaultRegistry is for runtime metadata and dynamic lookup, not normal app flow.
  • Old repository/factory-based examples are not current for the modern Altruist API.