erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

perf(content): add typed prepared asset source

Browse source 
Introduce explicit loaded, missing, and corrupt outcomes over typed pak keys, validate package/DAT identity at open, add zero-I/O TOC probes, preserve cancellation, and route the package path through RuntimeOptions. Production injection follows in the next checkpoint.
This commit is contained in:
Erik 2026-07-24 14:52:12 +02:00
parent 7fb7189de8
commit c42f93b323
7 changed files with 750 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

4
src/AcDream.App/RuntimeOptions.cs
View file

@ -1,5 +1,6 @@
using System;
using System.Globalization;
using System.IO;
namespace AcDream.App;
@ -26,6 +27,7 @@ namespace AcDream.App;
/// </remarks>
public sealed record RuntimeOptions(
string DatDir,
string PreparedAssetPath,
bool LiveMode,
string LiveHost,
int LivePort,
@ -72,6 +74,8 @@ public sealed record RuntimeOptions(
return new RuntimeOptions(
DatDir: datDir,
PreparedAssetPath: NullIfEmpty(env("ACDREAM_PAK_PATH"))
?? Path.Combine(datDir, "acdream.pak"),
LiveMode: IsExactlyOne(env("ACDREAM_LIVE")),
LiveHost: env("ACDREAM_TEST_HOST") ?? "127.0.0.1",
LivePort: TryParseInt(env("ACDREAM_TEST_PORT")) ?? 9000,

431
src/AcDream.Content/IPreparedAssetSource.cs Normal file
View file

@ -0,0 +1,431 @@
using System.Collections.Concurrent;
using System.Threading;
using AcDream.Content.Pak;
using DatReaderWriter.DBObjs;
using DatReaderWriter.Enums;
using Microsoft.Extensions.Logging;
namespace AcDream.Content;
public enum PreparedAssetPresence
{
Missing,
Available,
Corrupt,
}
public enum PreparedAssetReadStatus
{
Missing,
Loaded,
Corrupt,
}
/// <summary>
/// Schema retained only for the live-DAT tooling source. Pak aliases use the
/// source Cell DID as their lookup identity and carry the already-prepared
/// deduplicated geometry as their payload.
/// </summary>
public sealed record PreparedEnvCellSchema(
uint EnvironmentId,
ushort CellStructure,
IReadOnlyList<ushort> Surfaces);
/// <summary>
/// One typed prepared-payload request. <see cref="SourceFileId"/> selects the
/// persisted pak key; <see cref="RuntimeObjectId"/> is the identity published
/// to the renderer. They differ for deduplicated EnvCell geometry.
/// </summary>
public readonly record struct PreparedAssetRequest(
PakAssetType Type,
uint SourceFileId,
ulong RuntimeObjectId,
PreparedEnvCellSchema? EnvCell = null)
{
public static PreparedAssetRequest GfxObj(uint fileId) =>
new(PakAssetType.GfxObjMesh, fileId, fileId);
public static PreparedAssetRequest Setup(uint fileId) =>
new(PakAssetType.SetupMesh, fileId, fileId);
public static PreparedAssetRequest EnvCellGeometry(
uint sourceCellId,
ulong runtimeGeometryId,
uint environmentId,
ushort cellStructure,
IReadOnlyList<ushort> surfaces) =>
new(
PakAssetType.EnvCellMesh,
sourceCellId,
runtimeGeometryId,
new PreparedEnvCellSchema(
environmentId,
cellStructure,
surfaces));
}
public readonly record struct PreparedAssetReadResult(
PreparedAssetReadStatus Status,
ObjectMeshData? Data)
{
public static PreparedAssetReadResult Missing =>
new(PreparedAssetReadStatus.Missing, null);
public static PreparedAssetReadResult Corrupt =>
new(PreparedAssetReadStatus.Corrupt, null);
public static PreparedAssetReadResult Loaded(ObjectMeshData data) =>
new(PreparedAssetReadStatus.Loaded, data);
}
public readonly record struct PreparedAssetSourceStats(
long Probes,
long Reads,
long Loaded,
long Missing,
long Corrupt);
public readonly record struct PreparedAssetCatalogIdentity(
uint PortalIteration,
uint CellIteration,
uint HighResIteration,
uint LanguageIteration,
uint BakeToolVersion)
{
public static PreparedAssetCatalogIdentity From(IDatReaderWriter dats)
{
ArgumentNullException.ThrowIfNull(dats);
return new(
checked((uint)dats.PortalIteration),
checked((uint)dats.CellIteration),
checked((uint)dats.HighResIteration),
checked((uint)dats.LanguageIteration),
PakFormat.CurrentBakeToolVersion);
}
}
/// <summary>
/// Immutable CPU-side render payload source. Implementations perform no GL
/// work and may be called concurrently by the renderer's decode workers.
/// </summary>
public interface IPreparedAssetSource : IDisposable
{
PreparedAssetPresence Probe(PakAssetType type, uint sourceFileId);
PreparedAssetReadResult Read(
in PreparedAssetRequest request,
CancellationToken cancellationToken = default);
PreparedAssetSourceStats Stats { get; }
CacheStats DecodedTextureCacheStats { get; }
}
internal static class PreparedAssetRequestContract
{
public static void ValidateType(PakAssetType type)
{
if (!Enum.IsDefined(type))
{
throw new ArgumentOutOfRangeException(
nameof(type),
type,
"unknown prepared asset type");
}
}
public static void Validate(in PreparedAssetRequest request)
{
ValidateType(request.Type);
if (request.Type == PakAssetType.EnvCellMesh
&& request.EnvCell is null)
{
throw new ArgumentException(
"EnvCell prepared requests must retain their source schema.",
nameof(request));
}
}
public static bool Matches(
in PreparedAssetRequest request,
ObjectMeshData data)
{
bool expectedSetup = request.Type == PakAssetType.SetupMesh;
return data.ObjectId == request.RuntimeObjectId
&& data.IsSetup == expectedSetup;
}
}
/// <summary>
/// Production prepared source backed by one immutable memory-mapped pak.
/// There is intentionally no DAT fallback.
/// </summary>
public sealed class PakPreparedAssetSource : IPreparedAssetSource
{
private readonly PakReader _reader;
private readonly Action<string>? _diagnosticSink;
private readonly ConcurrentDictionary<ulong, byte> _loggedIdentityFaults = new();
private long _probes;
private long _reads;
private long _loaded;
private long _missing;
private long _corrupt;
public PakPreparedAssetSource(
string path,
PreparedAssetCatalogIdentity expected,
Action<string>? diagnosticSink = null)
{
ArgumentException.ThrowIfNullOrWhiteSpace(path);
_diagnosticSink = diagnosticSink;
_reader = new PakReader(path);
try
{
ValidateHeader(path, _reader.Header, expected);
}
catch
{
_reader.Dispose();
throw;
}
}
public PakPreparedAssetSource(
string path,
IDatReaderWriter dats,
Action<string>? diagnosticSink = null)
: this(
path,
PreparedAssetCatalogIdentity.From(dats),
diagnosticSink)
{
}
public PreparedAssetSourceStats Stats =>
new(
Volatile.Read(ref _probes),
Volatile.Read(ref _reads),
Volatile.Read(ref _loaded),
Volatile.Read(ref _missing),
Volatile.Read(ref _corrupt));
public CacheStats DecodedTextureCacheStats => default;
public PreparedAssetPresence Probe(
PakAssetType type,
uint sourceFileId)
{
PreparedAssetRequestContract.ValidateType(type);
Interlocked.Increment(ref _probes);
ulong key = PakKey.Compose(type, sourceFileId);
return _reader.ProbeEntry(key) switch
{
PakEntryState.Available => PreparedAssetPresence.Available,
PakEntryState.Corrupt => PreparedAssetPresence.Corrupt,
_ => PreparedAssetPresence.Missing,
};
}
public PreparedAssetReadResult Read(
in PreparedAssetRequest request,
CancellationToken cancellationToken = default)
{
PreparedAssetRequestContract.Validate(request);
cancellationToken.ThrowIfCancellationRequested();
Interlocked.Increment(ref _reads);
ulong key = PakKey.Compose(request.Type, request.SourceFileId);
PakObjectReadStatus status =
_reader.ReadObjectMeshData(key, out ObjectMeshData? data);
cancellationToken.ThrowIfCancellationRequested();
if (status == PakObjectReadStatus.Missing)
{
Interlocked.Increment(ref _missing);
return PreparedAssetReadResult.Missing;
}
if (status == PakObjectReadStatus.Corrupt || data is null)
{
Interlocked.Increment(ref _corrupt);
return PreparedAssetReadResult.Corrupt;
}
if (!PreparedAssetRequestContract.Matches(request, data))
{
Interlocked.Increment(ref _corrupt);
LogIdentityFaultOnce(
key,
$"prepared payload identity mismatch for key 0x{key:X16}: " +
$"expected runtime=0x{request.RuntimeObjectId:X16}, " +
$"type={request.Type}; payload runtime=0x{data.ObjectId:X16}, " +
$"isSetup={data.IsSetup}");
return PreparedAssetReadResult.Corrupt;
}
Interlocked.Increment(ref _loaded);
return PreparedAssetReadResult.Loaded(data);
}
private static void ValidateHeader(
string path,
PakHeader actual,
PreparedAssetCatalogIdentity expected)
{
var mismatches = new List<string>();
if (actual.BakeToolVersion != expected.BakeToolVersion)
mismatches.Add(
$"bake tool {actual.BakeToolVersion} != {expected.BakeToolVersion}");
if (actual.PortalIteration != expected.PortalIteration)
mismatches.Add(
$"portal iteration {actual.PortalIteration} != {expected.PortalIteration}");
if (actual.CellIteration != expected.CellIteration)
mismatches.Add(
$"cell iteration {actual.CellIteration} != {expected.CellIteration}");
if (actual.HighResIteration != expected.HighResIteration)
mismatches.Add(
$"high-res iteration {actual.HighResIteration} != {expected.HighResIteration}");
if (actual.LanguageIteration != expected.LanguageIteration)
mismatches.Add(
$"language iteration {actual.LanguageIteration} != {expected.LanguageIteration}");
if (mismatches.Count != 0)
{
throw new InvalidDataException(
$"prepared asset package '{path}' does not match the installed DAT set: " +
string.Join("; ", mismatches) +
". Re-bake acdream.pak with this client build and DAT install.");
}
}
private void LogIdentityFaultOnce(ulong key, string message)
{
if (_loggedIdentityFaults.TryAdd(key, 0))
(_diagnosticSink ?? Console.Error.WriteLine)(message);
}
public void Dispose() => _reader.Dispose();
}
/// <summary>
/// Explicit live-DAT adapter for bake/equivalence and UI Studio tooling.
/// Production GameWindow composition never constructs this implementation.
/// </summary>
public sealed class DatPreparedAssetSource : IPreparedAssetSource
{
private readonly IDatReaderWriter _dats;
private readonly MeshExtractor _extractor;
private long _probes;
private long _reads;
private long _loaded;
private long _missing;
public DatPreparedAssetSource(
IDatReaderWriter dats,
ILogger logger,
Action<ObjectMeshData>? sideStagedSink = null)
{
ArgumentNullException.ThrowIfNull(dats);
ArgumentNullException.ThrowIfNull(logger);
_dats = dats;
_extractor = new MeshExtractor(dats, logger, sideStagedSink);
}
public PreparedAssetSourceStats Stats =>
new(
Volatile.Read(ref _probes),
Volatile.Read(ref _reads),
Volatile.Read(ref _loaded),
Volatile.Read(ref _missing),
0);
public CacheStats DecodedTextureCacheStats =>
_extractor.DecodedTextureCacheStats;
public PreparedAssetPresence Probe(
PakAssetType type,
uint sourceFileId)
{
PreparedAssetRequestContract.ValidateType(type);
Interlocked.Increment(ref _probes);
DBObjType expected = type switch
{
PakAssetType.GfxObjMesh => DBObjType.GfxObj,
PakAssetType.SetupMesh => DBObjType.Setup,
PakAssetType.EnvCellMesh => DBObjType.EnvCell,
_ => DBObjType.Unknown,
};
if (expected == DBObjType.Unknown)
return PreparedAssetPresence.Missing;
return _dats.ResolveId(sourceFileId).Any(r => r.Type == expected)
? PreparedAssetPresence.Available
: PreparedAssetPresence.Missing;
}
public PreparedAssetReadResult Read(
in PreparedAssetRequest request,
CancellationToken cancellationToken = default)
{
PreparedAssetRequestContract.Validate(request);
cancellationToken.ThrowIfCancellationRequested();
Interlocked.Increment(ref _reads);
ObjectMeshData? data;
if (request.Type == PakAssetType.EnvCellMesh)
{
PreparedEnvCellSchema schema = request.EnvCell
?? throw new ArgumentException(
"EnvCell prepared requests must retain their source schema.",
nameof(request));
uint environmentId = 0x0D00_0000u | schema.EnvironmentId;
if (!_dats.Portal.TryGet<DatReaderWriter.DBObjs.Environment>(
environmentId,
out DatReaderWriter.DBObjs.Environment? environment)
|| environment is null
|| !environment.Cells.TryGetValue(
schema.CellStructure,
out DatReaderWriter.Types.CellStruct? cellStruct)
|| cellStruct is null)
{
Interlocked.Increment(ref _missing);
return PreparedAssetReadResult.Missing;
}
data = _extractor.PrepareCellStructMeshData(
request.RuntimeObjectId,
cellStruct,
schema.Surfaces,
System.Numerics.Matrix4x4.Identity,
cancellationToken);
}
else
{
data = _extractor.PrepareMeshData(
request.SourceFileId,
request.Type == PakAssetType.SetupMesh,
cancellationToken);
}
cancellationToken.ThrowIfCancellationRequested();
if (data is null)
{
Interlocked.Increment(ref _missing);
return PreparedAssetReadResult.Missing;
}
if (!PreparedAssetRequestContract.Matches(request, data))
{
throw new InvalidDataException(
$"live-DAT prepared payload identity mismatch: expected " +
$"runtime=0x{request.RuntimeObjectId:X16}, type={request.Type}; " +
$"payload runtime=0x{data.ObjectId:X16}, isSetup={data.IsSetup}");
}
Interlocked.Increment(ref _loaded);
return PreparedAssetReadResult.Loaded(data);
}
public void Dispose()
{
// The caller owns the shared DAT collection. MeshExtractor owns only
// managed caches and thread-local decoders.
}
}

3
src/AcDream.Content/MeshExtractor.cs
View file

@ -130,8 +130,7 @@ public sealed class MeshExtractor {
return null;
}
catch (OperationCanceledException) {
// Ignore
return null;
throw;
}
catch (Exception ex) {
_logger.LogError(ex, "Error preparing mesh data for 0x{Id:X16}", id);

24
src/AcDream.Content/Pak/PakReadStatus.cs Normal file
View file

@ -0,0 +1,24 @@
namespace AcDream.Content.Pak;
/// <summary>
/// TOC-only state for one exact typed pak key. <see cref="Available"/> means
/// the immutable TOC row exists and has a structurally valid file range; CRC
/// and payload structure are deliberately not faulted in by a probe.
/// </summary>
public enum PakEntryState
{
Missing,
Available,
Corrupt,
}
/// <summary>
/// Result of reading and deserializing one pak payload. This preserves the
/// distinction between an absent key and a present-but-damaged external file.
/// </summary>
public enum PakObjectReadStatus
{
Missing,
Loaded,
Corrupt,
}

36
src/AcDream.Content/Pak/PakReader.cs
View file

@ -112,21 +112,45 @@ public sealed class PakReader : IDisposable {
return VerdictFor(index) == 1;
}
/// <summary>
/// Probes the immutable TOC only. No payload bytes are copied, CRC-checked,
/// or deserialized. A structurally invalid entry is reported as corrupt;
/// a CRC or payload-structure fault becomes visible after the first read.
/// </summary>
public PakEntryState ProbeEntry(ulong key) {
int index = BinarySearch(key);
if (index < 0)
return PakEntryState.Missing;
return _entryVerdictByTocIndex.TryGetValue(index, out int verdict)
&& verdict == 0
? PakEntryState.Corrupt
: PakEntryState.Available;
}
/// <summary>
/// Reads and deserializes the <see cref="ObjectMeshData"/> stored under
/// <paramref name="key"/>. Returns false (data null) if the key is absent
/// OR the blob fails any tripwire (bounds, CRC, structural deserialization
/// failure) — logged once per entry, per the corrupt-=-missing contract.
/// </summary>
public bool TryReadObjectMeshData(ulong key, out ObjectMeshData? data) {
public bool TryReadObjectMeshData(ulong key, out ObjectMeshData? data) =>
ReadObjectMeshData(key, out data) == PakObjectReadStatus.Loaded;
/// <summary>
/// Reads one payload while preserving absent-versus-corrupt state for the
/// production prepared-asset boundary.
/// </summary>
public PakObjectReadStatus ReadObjectMeshData(
ulong key,
out ObjectMeshData? data) {
data = null;
int index = BinarySearch(key);
if (index < 0) return false;
if (index < 0) return PakObjectReadStatus.Missing;
// Previously judged bad (bounds at open, or an earlier CRC/structure
// failure): missing, no re-read, no re-log.
bool judged = _entryVerdictByTocIndex.TryGetValue(index, out var verdict);
if (judged && verdict == 0) return false;
if (judged && verdict == 0) return PakObjectReadStatus.Corrupt;
// Single pass (review finding 4): ONE copy out of the map; CRC and
// deserialization both run over this same buffer.
@ -139,14 +163,14 @@ public sealed class PakReader : IDisposable {
if (actualCrc != entry.Crc32) {
_entryVerdictByTocIndex[index] = 0;
LogCorruptionOnce(index, $"crc mismatch (expected 0x{entry.Crc32:X8}, got 0x{actualCrc:X8})");
return false;
return PakObjectReadStatus.Corrupt;
}
_entryVerdictByTocIndex[index] = 1;
}
try {
data = ObjectMeshDataSerializer.Read(bytes);
return true;
return PakObjectReadStatus.Loaded;
}
catch (Exception ex) {
// Structurally malformed blob behind a valid CRC (bake-side bug or
@ -155,7 +179,7 @@ public sealed class PakReader : IDisposable {
data = null;
_entryVerdictByTocIndex[index] = 0;
LogCorruptionOnce(index, $"deserialization failed despite matching CRC: {ex.GetType().Name}: {ex.Message}");
return false;
return PakObjectReadStatus.Corrupt;
}
}