acdream/src/AcDream.Content/IDatReaderWriter.cs

using DatReaderWriter;
using DatReaderWriter.Enums;
using DatReaderWriter.Lib.IO;
using AcDream.Core.Content;
using System.Collections.ObjectModel;
using System.Diagnostics.CodeAnalysis;

// Phase O-T7: verbatim copy of WorldBuilder.Shared.Services.IDatReaderWriter +
// IDatDatabase, taken into our tree so the WorldBuilder.Shared project
// reference could be dropped.
//
// MP1a (2026-07-05, Task 4): moved to AcDream.Content, namespace only —
// MeshExtractor's constructor takes IDatReaderWriter and must be GL-free.
// MP1b review (finding 7): the concrete DatCollection-backed implementation
// (DatCollectionAdapter, this assembly) now lives HERE too — one shared
// adapter for ObjectMeshManager (App), acdream-bake, and the equivalence
// suite, so the three consumers can never drift apart.

namespace AcDream.Content;

/// <summary>
/// Interface for the dat reader/writer
/// </summary>
public interface IDatReaderWriter : IDisposable, IDatObjectSource {
    /// <summary>
    /// Gets the source directory of the DAT files.
    /// </summary>
    string SourceDirectory { get; }

    /// <summary>
    /// Tries to get the raw bytes of a file from a specific region database.
    /// </summary>
    bool TryGetFileBytes(uint regionId, uint fileId, ref byte[] bytes, out int bytesRead);

    /// <summary>
    /// The portal database
    /// </summary>
    IDatDatabase Portal { get; }

    /// <summary>The single cell database exposed by DatCollection.</summary>
    IDatDatabase Cell { get; }

    /// <summary>
    /// The cell region databases. Each key is a cell region ID
    /// </summary>
    ReadOnlyDictionary<uint, IDatDatabase> CellRegions { get; }

    /// <summary>
    /// The high res database
    /// </summary>
    IDatDatabase HighRes { get; }

    /// <summary>
    /// The language database
    /// </summary>
    IDatDatabase Language { get; }

    /// <summary>Alias matching DatCollection's Local database name.</summary>
    IDatDatabase Local { get; }

    /// <summary>Enumerates typed ids across the database selected for the type.</summary>
    IEnumerable<uint> GetAllIdsOfType<T>() where T : IDBObj;

    /// <summary>
    /// A mapping of region ids to region dat file entry ids. key: region id, value: region dat file entry
    /// </summary>
    ReadOnlyDictionary<uint, uint> RegionFileMap { get; }

    /// <summary>
    /// Gets the current portal iteration.
    /// </summary>
    int PortalIteration { get; }

    /// <summary>
    /// Gets the current cell iteration (from the first cell region).
    /// </summary>
    int CellIteration { get; }

    /// <summary>
    /// Gets the current high res iteration.
    /// </summary>
    int HighResIteration { get; }

    /// <summary>
    /// Gets the current language iteration.
    /// </summary>
    int LanguageIteration { get; }

    // Write-path methods — preserved from WB's interface for verbatim
    // compatibility but not exercised by ObjectMeshManager in acdream.
    /// <summary>Attempts to save a database object to the appropriate DAT.</summary>
    bool TrySave<T>(T obj, int iteration = 0) where T : IDBObj;

    /// <summary>Attempts to save a database object to the appropriate DAT for a specific region.</summary>
    bool TrySave<T>(uint regionId, T obj, int iteration = 0) where T : IDBObj;

    /// <summary>
    /// Resolution of a data ID to a database and type
    /// </summary>
    public record IdResolution(IDatDatabase Database, DBObjType Type);

    /// <summary>
    /// Resolves a data ID to all possible databases and types.
    /// </summary>
    public IEnumerable<IdResolution> ResolveId(uint id);

    /// <summary>
    /// Resolves one data ID using acdream's canonical precedence without
    /// materializing a result collection: Portal, HighRes, Language, Cell.
    /// Production's concrete adapter overrides this with direct B-tree probes.
    /// </summary>
    bool TryResolvePreferred(
        uint id,
        [NotNullWhen(true)] out IDatDatabase? database,
        out DBObjType type)
    {
        IDatDatabase? highRes = null;
        DBObjType highResType = DBObjType.Unknown;
        IDatDatabase? language = null;
        DBObjType languageType = DBObjType.Unknown;
        IDatDatabase? cell = null;
        DBObjType cellType = DBObjType.Unknown;

        foreach (IdResolution resolution in ResolveId(id))
        {
            if (ReferenceEquals(resolution.Database, Portal))
            {
                database = resolution.Database;
                type = resolution.Type;
                return true;
            }
            if (ReferenceEquals(resolution.Database, HighRes))
            {
                highRes = resolution.Database;
                highResType = resolution.Type;
            }
            else if (ReferenceEquals(resolution.Database, Language))
            {
                language = resolution.Database;
                languageType = resolution.Type;
            }
            else if (ReferenceEquals(resolution.Database, Cell))
            {
                cell = resolution.Database;
                cellType = resolution.Type;
            }
        }

        database = highRes ?? language ?? cell;
        type = highRes is not null
            ? highResType
            : language is not null
                ? languageType
                : cellType;
        return database is not null;
    }
}

/// <summary>
/// Interface for a dat database, providing methods to retrieve files and objects.
/// </summary>
public interface IDatDatabase : IDisposable {
    DatDatabase Db { get; }

    /// <summary>Retrieves the current iteration of the database.</summary>
    int Iteration { get; }

    /// <summary>Retrieves all file IDs of a specific type.</summary>
    public IEnumerable<uint> GetAllIdsOfType<T>() where T : IDBObj;

    /// <summary>Attempts to retrieve a database object by its file ID.</summary>
    public bool TryGet<T>(uint fileId, [MaybeNullWhen(false)] out T value) where T : IDBObj;

    /// <summary>Attempts to retrieve the raw bytes of a file by its ID.</summary>
    bool TryGetFileBytes(uint fileId, [MaybeNullWhen(false)] out byte[] value);

    /// <summary>Attempts to retrieve the raw bytes of a file by its ID into a provided buffer.</summary>
    bool TryGetFileBytes(uint fileId, ref byte[] bytes, out int bytesRead);

    /// <summary>Attempts to save a database object.</summary>
    bool TrySave<T>(T obj, int iteration = 0) where T : IDBObj;
}