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

namespace AcDream.Core.CharGen;

/// <summary>
/// Retail's four skill states. Wire values match ACE's
/// <c>ACE.Entity.Enum.SkillAdvancementClass</c> exactly (0=Inactive,
/// 1=Untrained, 2=Trained, 3=Specialized) — ACE unpacks the 0xF656
/// <c>CharacterCreateInfo.SkillAdvancementClasses</c> list with this same
/// numbering, and retail's <c>CharGenState::UpdateRemainingSkillCredits @
/// 0x005C37C0</c> only charges credits for Trained (2) and Specialized (3).
/// </summary>
public enum ChargenSkillAdvancementClass : uint
{
    Inactive = 0,
    Untrained = 1,
    Trained = 2,
    Specialized = 3,
}

/// <summary>
/// One skill's retail training cost for a heritage. Retail schema:
/// <c>SkillCG</c>, entries of <c>HeritageGroupCG.Skills</c>.
/// <c>PrimaryCost</c> is the TOTAL cost to reach Specialized (not an
/// increment on top of <c>NormalCost</c>) — retail's
/// <c>UpdateRemainingSkillCredits</c> adds exactly one of the two per
/// skill, never both.
/// </summary>
public readonly record struct ChargenSkillCost(uint SkillId, int NormalCost, int PrimaryCost);

/// <summary>
/// Retail's fixed-size per-character skill-advancement array
/// (<c>CharGenState.skillLevels</c>). ACE's <c>CharacterCreateInfo.Unpack</c>
/// terminates the connection if the wire's <c>numSkills</c> count is not
/// exactly <see cref="SlotCount"/> (55): retail's own loop in
/// <c>UpdateRemainingSkillCredits</c> walks indices <c>1..totalNumSkills</c>
/// (skipping reserved slot 0), and Chorizite's <c>SkillId</c> enum runs
/// 1..54 — 54 real skills plus the reserved slot 0 is exactly 55. This type
/// makes that shape structural: it always holds exactly 55 slots, so a
/// caller building the 0xF656 body (CC2) cannot accidentally send a
/// different count.
/// </summary>
public sealed class ChargenSkillAdvancementSet
{
    /// <summary>Slot 0 is reserved (unused by retail); slots 1..54 map 1:1
    /// to Chorizite's <c>DatReaderWriter.Enums.SkillId</c> values.</summary>
    public const int SlotCount = 55;

    private readonly ChargenSkillAdvancementClass[] _slots = new ChargenSkillAdvancementClass[SlotCount];

    /// <summary>Skill state by raw skill id. Ids outside <c>1..54</c> read
    /// as <see cref="ChargenSkillAdvancementClass.Inactive"/> and cannot be
    /// set.</summary>
    public ChargenSkillAdvancementClass this[uint skillId]
    {
        get => skillId >= 1 && skillId < SlotCount
            ? _slots[skillId]
            : ChargenSkillAdvancementClass.Inactive;
        set
        {
            if (skillId < 1 || skillId >= SlotCount)
                throw new ArgumentOutOfRangeException(
                    nameof(skillId),
                    skillId,
                    $"Skill id must be in 1..{SlotCount - 1}.");
            _slots[skillId] = value;
        }
    }

    /// <summary>
    /// Materializes the wire body shape: exactly <see cref="SlotCount"/>
    /// entries, slot 0 first, matching ACE's
    /// <c>CharacterCreateInfo.SkillAdvancementClasses</c> read order.
    /// </summary>
    public IReadOnlyList<uint> ToWireClasses()
    {
        var wire = new uint[SlotCount];
        for (int i = 0; i < SlotCount; i++)
            wire[i] = (uint)_slots[i];
        return wire;
    }
}