namespace AcDream.Core.World;

/// <summary>
/// Server-specified palette composition for a live-mode entity. Gets
/// handed to <see cref="StaticMeshRenderer"/> so the texture cache can
/// compose the effective palette (base with sub-palette overlays) at
/// decode time and use it when decoding palette-indexed textures
/// (PFID_P8 / PFID_INDEX16). Non-palette textures ignore this entirely.
///
/// <para>
/// <b>Semantics (ported from Chorizite.ACProtocol.Types.Subpalette docs
/// and confirmed against ACE's CalculateObjDesc):</b>
/// </para>
/// <list type="bullet">
///   <item><c>BasePaletteId</c> — the entity's base palette dat id
///         (<c>0x04XXXXXX</c>). Comes from <c>ObjDesc.Palette</c>. Acts
///         as the starting point before subpalette overlays are applied.</item>
///   <item>Each overlay entry <c>(SubPaletteId, Offset, Length)</c>
///         means "copy the first <c>Length*8</c> colors from the
///         subpalette into the base palette starting at index
///         <c>Offset*8</c>." Length=0 is a sentinel meaning "entire
///         palette" (Chorizite documents it as defaulting to <c>256*8</c>
///         which is effectively everything).</item>
/// </list>
///
/// <para>
/// Palette overlays are per-entity, not per-part: all parts of a
/// character share the same composed palette (skin color is consistent
/// across the whole body even if different body parts use different
/// meshes).
/// </para>
/// </summary>
public sealed record PaletteOverride(
    uint BasePaletteId,
    IReadOnlyList<PaletteOverride.SubPaletteRange> SubPalettes)
{
    /// <summary>
    /// One overlay range in a <see cref="PaletteOverride"/>. Offset and
    /// Length are the raw bytes the server sent; callers multiply by 8
    /// to get palette-index units.
    /// </summary>
    public readonly record struct SubPaletteRange(
        uint SubPaletteId,
        byte Offset,
        byte Length);
}