namespace AcDream.Core.World;

/// <summary>
/// Allocates stable, collision-free ids for procedurally generated scenery.
///
/// <para>
/// The top nibble is fixed at <c>0x8</c>: <see cref="IsInNamespace"/> tests
/// <c>(id &amp; 0xF0000000u) == 0x80000000u</c>, the full nibble, not bit 31
/// alone. Bit 31 alone is NOT a reliable procedural-scenery test — it is
/// also set by <c>LandblockStaticEntityIdAllocator</c>'s <c>0xC...</c>
/// namespace (top nibble <c>1100</c>) and by the synthetic render ids
/// <c>0xDA11_D0xx</c> (paperdoll) and <c>0xFFFF_FF01</c> (portal tunnel).
/// <c>LandblockPhysicsPublisher.cs</c>'s <c>isOutdoorMesh</c> predicate
/// intentionally tests bit 31 alone — it wants "any of these broader
/// synthetic/outdoor namespaces", not specifically procedural scenery — but
/// that is the one deliberate exception; every OTHER consumer, including
/// foliage-wind classification, must use <see cref="IsInNamespace"/>. The
/// remaining 28 bits are X(8), Y(8), and a 12-bit per-landblock counter:
/// <c>0x8XXYYIII</c>.
/// </para>
///
/// <para>
/// The old 8-bit counter aborted generation after 256 drawable spawns. That
/// exception rejected the entire streamed landblock before render publication,
/// exposing the grey clear color as portal space ended. A 12-bit counter gives
/// 4096 entries while retaining full landblock coordinates. Overflow fails
/// before it can alias the next landblock.
/// </para>
/// </summary>
public static class ProceduralSceneryIdAllocator
{
    public const uint MaxCounter = 0xFFFu;

    public static uint Base(uint landblockX, uint landblockY)
        => 0x80000000u
           | ((landblockX & 0xFFu) << 20)
           | ((landblockY & 0xFFu) << 12);

    public static uint Allocate(uint landblockX, uint landblockY, ref uint counter)
    {
        if (counter > MaxCounter)
            throw new InvalidDataException(
                $"Landblock ({landblockX & 0xFFu:X2},{landblockY & 0xFFu:X2}) exceeds the 4096-entry procedural scenery id namespace.");

        return Base(landblockX, landblockY) + counter++;
    }

    /// <summary>
    /// The full top-nibble test — <c>0x8...</c>, not bit 31 alone. Bit 31
    /// alone also matches <c>LandblockStaticEntityIdAllocator</c>'s
    /// <c>0xC...</c> ids (top nibble <c>1100</c> also has bit 31 set) and
    /// the synthetic render ids <c>0xDA11_D0xx</c> / <c>0xFFFF_FF01</c>.
    /// </summary>
    public static bool IsInNamespace(uint entityId) =>
        (entityId & 0xF0000000u) == 0x80000000u;
}