acdream/src/AcDream.Core/CharGen/ChargenClothingTable.cs

using System.Collections.Frozen;

namespace AcDream.Core.CharGen;

/// <summary>
/// One un-resolved dye-shade choice inside a clothing "palette template"
/// (retail's inner <c>CloSubpalEffect</c> array entry, one per
/// <c>ClothingTable::BuildObjDesc @ 0x005A7900</c> loop iteration; Chorizite
/// projects the identical shape as <c>DatReaderWriter.Types.CloSubPalette</c>
/// — a <c>PaletteSet</c> id plus a list of overlay ranges). Offsets/counts
/// here are the REAL (unpacked) color units read straight off the dat
/// (installed-DAT probe: Aluvian male "Cloth Cap" headgear reads
/// off=2000,n=48 for every one of its 28 palette-template entries) — the
/// *8-packed byte convention only applies to the OUTPUT
/// <see cref="ChargenSubPalette"/>, converted once at composition time
/// (<see cref="ChargenAppearanceFactory"/>).
/// </summary>
public readonly record struct ChargenClothingSubPaletteRange(uint Offset, uint NumColors);

/// <summary>
/// One resolvable-by-shade colour choice for a clothing palette template:
/// the PalSet id (0x0F......) to resolve via
/// <see cref="ChargenPalSetMath.GetPaletteIndex"/>, plus every overlay range
/// to apply once resolved.
/// </summary>
public readonly record struct ChargenClothingSubPaletteChoice(
    uint PalSetId,
    IReadOnlyList<ChargenClothingSubPaletteRange> Ranges);

/// <summary>
/// One clothing-table "palette template" (retail's <c>CloPaletteTemplate</c>,
/// looked up in <c>ClothingTable::_paletteTemplatesHash</c> by the id
/// <c>CharGenState::GetHeadgearPaletteTemplateID</c> (and its Shirt/Trousers/
/// Footwear siblings, all at 0x005C38F0-0x005C3980) return — which is itself
/// just a bounds-checked passthrough of <c>Sex_CG.ClothingColors[index]</c>:
/// every one of the four per-slot template-id arrays
/// (<c>headgearPaletteTemplateIDs</c>/<c>shirtPaletteTemplateIDs</c>/
/// <c>trousersPaletteTemplateIDs</c>/<c>footwearPaletteTemplateIDs</c>) is
/// populated from the SAME single <c>Sex_CG::ClothingColors</c> dat field —
/// there is no per-clothing-slot color list in the dat schema at all. This
/// CONFIRMS (does not merely approximate) register row AP-208's shared-list
/// design in <c>RuntimeCharacterCreationAppearance</c>/
/// <c>ChargenAppearanceSlot</c> — installed-DAT probe: Aluvian male's
/// <c>ClothingColors</c> = {9,6,4,8,7,5,2,3,13}, and the "Cloth Cap"
/// headgear's <c>ClothingSubPalEffects</c> keys include 2,3,4,5,6,7,8,9,13 —
/// the shared list's raw values ARE the template-id keys, verified live.
/// </summary>
public sealed record ChargenClothingPaletteTemplate(
    IReadOnlyList<ChargenClothingSubPaletteChoice> Choices)
{
    public static ChargenClothingPaletteTemplate Empty { get; } =
        new(Array.Empty<ChargenClothingSubPaletteChoice>());
}

/// <summary>
/// One body-Setup-specific part/texture override set (retail's
/// <c>ClothingBaseEffect</c>, applied by
/// <c>ClothingBase::ApplyPartAndTextureChanges @ 0x005A8EB0</c>): for each
/// <c>CloObjectEffect</c>, an unconditional <see cref="ChargenAnimPartChange"/>
/// (part index → replacement GfxObj) plus every
/// <see cref="ChargenTextureChange"/> the SAME object effect carries for
/// that part.
/// </summary>
public sealed record ChargenClothingBaseEffect(
    IReadOnlyList<ChargenAnimPartChange> PartChanges,
    IReadOnlyList<ChargenTextureChange> TextureChanges)
{
    public static ChargenClothingBaseEffect Empty { get; } = new(
        Array.Empty<ChargenAnimPartChange>(),
        Array.Empty<ChargenTextureChange>());
}

/// <summary>
/// Pure projection of one ClothingTable dat object (0x19......, retail
/// <c>ClothingTable::Unpack</c> / Chorizite
/// <c>DatReaderWriter.DBObjs.ClothingTable</c>). One instance is referenced
/// per <see cref="ChargenGearOption.ClothingTableId"/> — a single garment
/// CHOICE (e.g. "Cloth Cowl") carries its own table covering every body
/// Setup it can be worn on plus every dye choice offered for it.
///
/// <para>
/// <b>Deliberate scope cut (CC6a) — MEASURED, not just asserted:</b> retail's
/// <c>ClothingTable::BuildObjDesc</c> falls back through a chain of ~8
/// hard-coded Setup-id substitutions (Umbraen crown/no-crown/void,
/// Penumbraen, Undead skeleton/zombie, Anakshay) when
/// <see cref="BaseEffectsBySetupId"/> has no direct entry for the requested
/// body Setup. CC6a's composer looks up <see cref="BaseEffectsBySetupId"/>
/// directly and skips a slot's part/texture contribution on a miss (this is
/// the OUTER lookup — <c>ClothingTable::_cloBaseHash</c> — whose retail
/// miss behavior is genuinely a no-op the caller never checks; the SEPARATE
/// inner per-choice PalSet lookup inside the same function's subpalette loop
/// has its own, stricter, abort-on-miss behavior — see
/// <c>ChargenAppearanceFactory.ComposeClothingSlot</c>'s own doc, ported
/// faithfully there) rather than porting the Setup-substitution chain. The
/// installed-DAT catalog test (<c>ChargenAppearanceCatalogInstalledDatTests</c>)
/// MEASURED this directly across all 26 heritage/gender combinations rather
/// than assuming it: for the 9 standard heritages where retail's own UI
/// actually shows clothing controls (everything except Gear Knight and the
/// two Olthoi variants, which retail hides the clothes button for entirely
/// — <c>gmCGAppearancePage::Update @ 0x0047E8F0</c>'s
/// <c>m_pClothesButton->SetVisible(0)</c> branches for
/// <c>mHeritageGroup == 6</c> and <c>== 0xc || == 0xd</c>), the default
/// gear choices resolve against their own body Setup with ZERO missing
/// coverage. <b>Undead IS a real gap</b> — retail DOES show clothing
/// controls for Undead, and MEASURED coverage is missing for <b>ALL FOUR</b>
/// clothing slots (headgear, trousers, shirt, AND footwear — not just three
/// of the four), on both genders: neither gender's live body Setup has a
/// <see cref="BaseEffectsBySetupId"/> entry in any of its four default gear
/// choices' clothing tables, because Undead's live body Setup IS one of the
/// skeleton/zombie variants the un-ported substitution chain exists to
/// redirect. A live preview for Undead will therefore render its default
/// clothing selection with NO part/texture override applied on any of the
/// four slots (the underlying body shows through unclothed) until the
/// substitution chain — or an equivalent per-heritage default-clothing-setup
/// mapping — lands. Filed as a known CC6a limitation for CC6b/a follow-up
/// rather than silently "confirmed unreachable."
/// </para>
/// </summary>
public sealed record ChargenClothingTable(
    IReadOnlyDictionary<uint, ChargenClothingBaseEffect> BaseEffectsBySetupId,
    IReadOnlyDictionary<uint, ChargenClothingPaletteTemplate> PaletteTemplatesById)
{
    public static ChargenClothingTable Empty { get; } = new(
        FrozenDictionary<uint, ChargenClothingBaseEffect>.Empty,
        FrozenDictionary<uint, ChargenClothingPaletteTemplate>.Empty);
}

/// <summary>
/// Resolves a PalSet dat id (0x0F......) to its pure projection. The
/// production implementation (<c>AcDream.Content.CharGen.ChargenAppearanceCatalog</c>)
/// reads and caches the real dat object; this interface keeps
/// <see cref="ChargenAppearanceFactory"/> free of any Chorizite dependency
/// (unit tests supply a hand-built fake).
/// </summary>
public interface IChargenPalSetSource
{
    ChargenPalSet? TryGetPalSet(uint palSetId);
}

/// <summary>
/// Resolves a ClothingTable dat id (0x19......) to its pure projection.
/// Same production/test split as <see cref="IChargenPalSetSource"/>.
/// </summary>
public interface IChargenClothingTableSource
{
    ChargenClothingTable? TryGetClothingTable(uint clothingTableId);
}