@flow-industries/id 0.23.4 → 0.24.1

package/dist/sdk/settings/cosmetics.js

@@ -0,0 +1,408 @@
+/**
+ * The cosmetic catalog, the space each item occupies, the surfaces it exposes
+ * for paint, and the single rule that decides whether two items may be worn at
+ * once.
+ *
+ * Pure — no DB, no I/O — and deliberately the ONLY implementation of that rule.
+ * TF2 evaluated it per equip path and its quickswitch path skipped the check
+ * entirely, so players equipped conflicting cosmetics that silently unequipped
+ * on restart (Source-1-Games#4055). Here the rule hangs off the surface
+ * registry and runs inside the one settings write path, which is why no route
+ * can forget it: a client may grey out conflicting picks for UX, but the save
+ * is the enforcer.
+ *
+ * The catalog is a code constant rather than a table, matching the appearance
+ * palette beside it — adding an item is a one-line edit and no migration. It
+ * promotes to a `cosmetic` table when non-engineers must edit it live.
+ */
+import { isString } from "../json";
+import hairItems from "./hair-items.json";
+/**
+ * Region pairs that physically overlap, declared once in ONE direction and
+ * symmetrised at module load so a pair can never be half-declared. Not
+ * transitive: a hat overlaps `whole_head` and `whole_head` overlaps `face`,
+ * but a hat and a bandana coexist happily.
+ */
+const REGION_OVERLAPS = [
+    ["whole_head", "hat"],
+    ["whole_head", "hair"],
+    ["whole_head", "face"],
+    ["whole_head", "glasses"],
+    ["whole_head", "ears"],
+    ["glasses", "face"],
+];
+const OVERLAPS = (() => {
+    const map = new Map();
+    const link = (from, to) => {
+        const set = map.get(from) ?? new Set();
+        set.add(to);
+        map.set(from, set);
+    };
+    for (const [left, right] of REGION_OVERLAPS) {
+        link(left, right);
+        link(right, left);
+    }
+    return map;
+})();
+/**
+ * Every slot, in the order the customizer and the resolver walk them, with the
+ * name a player reads it by and whether an avatar may go without it filled.
+ *
+ * `required` is a property of the SLOT and lives here because this is the only
+ * place both halves of it can be read from: the schema projects it onto the
+ * slot's descriptor so a client stops offering "None", and the surface's
+ * cross-field rule refuses an empty value for it inside the write path. A rule
+ * written down in auth and mirrored by hand in the customizer is the shape
+ * AUTH-210 went silent in and the one AUTH-222 undid.
+ *
+ * `satisfies` makes a new slot a typecheck error here until someone has said
+ * what it is called and whether an avatar may go without it.
+ */
+const SLOTS = {
+    hair: { label: "Hair", required: true },
+    hat: { label: "Headwear", required: false },
+    face: { label: "Face", required: false },
+    top: { label: "Top", required: true },
+    bottom: { label: "Bottom", required: true },
+    feet: { label: "Footwear", required: false },
+};
+function slotNames() {
+    // SAFETY: SLOTS satisfies Record<CosmeticSlot, _>, so its keys are exactly the slot names.
+    return Object.keys(SLOTS);
+}
+/** Every slot, in the order the customizer and the resolver walk them. */
+export const COSMETIC_SLOTS = slotNames();
+/** What a player reads this slot's row as. */
+export function slotLabel(slot) {
+    return SLOTS[slot].label;
+}
+/** Whether an avatar must wear something in this slot. */
+export function slotRequired(slot) {
+    return SLOTS[slot].required;
+}
+/** Namespaces the paint keys so they can never collide with a fixed setting. */
+const PAINT_KEY_PREFIX = "paint";
+/** Separates a paint key's segments. Forbidden inside an id or a material name. */
+const PAINT_KEY_SEPARATOR = ".";
+/** A catalog over `items`, refusing a duplicate id. */
+export function catalogOf(items) {
+    const byId = new Map(items.map((item) => [item.id, item]));
+    // A duplicate id would silently shadow one of the two items — loud beats a
+    // cosmetic that cannot be equipped and no error anywhere.
+    if (byId.size !== items.length) {
+        throw new Error("duplicate cosmetic id in the catalog");
+    }
+    return byId;
+}
+/**
+ * Every item a player may equip. EACH ONE MUST HAVE GEOMETRY: an id here with
+ * no mesh behind it renders as an item that vanishes when worn, and the model's
+ * side of the pairing is `cosmetic_items` in
+ * `game/games/arena/player/luna_bodygroups.tres` — a catalog id absent from
+ * there names nothing the renderer can draw.
+ */
+export const COSMETICS = [
+    ...hairItems.map((item) => ({
+        ...item,
+        slot: "hair",
+        regions: item.id === "hair_original" ? [] : ["hair"],
+        hides: item.id === "hair_original" ? [] : ["hair"],
+        paintable: [],
+    })),
+    {
+        id: "round_glasses",
+        slot: "face",
+        name: "Round glasses",
+        regions: ["glasses"],
+        hides: [],
+        // `LUNA_glasses.glb` carries exactly one material, and its name is the
+        // model's own — recolouring it paints the frames.
+        paintable: ["outline"],
+    },
+    {
+        id: "hoodie",
+        slot: "top",
+        name: "Hoodie",
+        regions: ["torso", "arms"],
+        // Long sleeves, so both arm segments go; the cuff stops at the wrist and
+        // the collar sits below the jaw, which is why the hands and `body_neck`
+        // stay. `body_pelvis` stays too — where a hoodie hem falls on the model is
+        // unknown until the cosmetic is authored, and hiding a region a cosmetic only
+        // half covers opens a hole, which reads far worse than the clipping it
+        // would have prevented.
+        hides: [
+            "body_chest",
+            "body_arm_upper_l",
+            "body_arm_upper_r",
+            "body_arm_lower_l",
+            "body_arm_lower_r",
+        ],
+        // The model's torso cosmetic is `cosmetic_tshirt`, whose one material is
+        // `tshirt`. That material is carried by no other mesh, which is why the
+        // body palette no longer names it: a `tshirt_color` row could only ever
+        // reach this item, and this row already owns it (AUTH-226).
+        paintable: ["tshirt"],
+    },
+    {
+        id: "cargo_shorts",
+        slot: "bottom",
+        name: "Cargo shorts",
+        regions: ["legs"],
+        // Exactly what the shipped `cosmetic_shorts` hides. The thigh is its own
+        // region below the shorts hem, so a longer cargo cut covers only part of
+        // it and claiming the whole thing would amputate the leg.
+        hides: ["body_pelvis"],
+        paintable: ["shorts"],
+    },
+    {
+        id: "boots",
+        slot: "feet",
+        name: "Boots",
+        // `feet` rather than `legs`, even though the shaft sheathes the calf: the
+        // shorts occupy `legs`, and a boot that fought them over it would be
+        // unwearable with the only bottom there is.
+        regions: ["feet"],
+        // The shipped `cosmetic_boots`. NOT `body_foot_*` — the model's toes stand
+        // proud of the boot, so hiding the feet cuts a hole in the avatar rather
+        // than preventing a clip (`cosmetic_coverage_test.gd` scores that pair as
+        // one of its two historical faults).
+        hides: ["body_leg_lower_l", "body_leg_lower_r"],
+        // `LUNA_boots.glb` names its one material `Shoes`, capital and all.
+        paintable: ["Shoes"],
+    },
+];
+/** Every item the shipped model can wear. */
+export const CATALOG = catalogOf(COSMETICS);
+/**
+ * What a player is wearing before they have dressed themselves — the outfit the
+ * model ships in, named in catalog terms.
+ *
+ * It is a DEFAULT of the appearance surface, resolved server-side exactly the
+ * way `randomDefaults` resolves a palette colour, and that is the whole point:
+ * a stored loadout is then the entire truth about what an avatar wears, and no
+ * renderer has to guess whether an empty slot means "new player" or "wants
+ * nothing there". AUTH-223 is what guessing cost — the client synthesised the
+ * starting outfit whenever the loadout named nothing at all, so equipping a
+ * single item anywhere silently stripped the other two.
+ *
+ * Every slot is listed, `""` for the ones a player starts bare in, so
+ * `satisfies` makes a new slot a typecheck error here until someone has said
+ * what a new player wears in it. A slot {@link SLOTS} marks required must name
+ * an item: it is the value an unnamed slot falls back to, so a mandatory slot
+ * starting at `""` would be a refusal every new player is born holding.
+ */
+export const STARTING_OUTFIT = {
+    hair: "hair_original",
+    hat: "",
+    face: "",
+    top: "hoodie",
+    bottom: "cargo_shorts",
+    feet: "",
+};
+export function cosmeticById(id, catalog = CATALOG) {
+    return catalog.get(id);
+}
+export function cosmeticsForSlot(slot, catalog = CATALOG) {
+    return [...catalog.values()].filter((item) => item.slot === slot);
+}
+/**
+ * Every region an item occupying `regions` cannot share a body with: those
+ * regions themselves, plus everything each of them overlaps.
+ *
+ * Closing the set here is what lets a client grey out an impossible pick
+ * without a copy of {@link REGION_OVERLAPS}. The schema projects this per
+ * catalog item, so a collision becomes a set intersection: nothing to
+ * symmetrise, and no room to assume overlap is transitive (it is not). A
+ * mirrored vocabulary is what AUTH-210 cost.
+ */
+export function conflictingRegions(regions) {
+    const closed = new Set(regions);
+    for (const region of regions) {
+        for (const overlap of OVERLAPS.get(region) ?? [])
+            closed.add(overlap);
+    }
+    return [...closed];
+}
+/**
+ * The first region two items both occupy, or null. A region trivially occupies
+ * itself, so "sharing a region" and "occupying overlapping regions" are the
+ * same check rather than two rules that can drift apart.
+ *
+ * Resolved through {@link conflictingRegions}, so the rule the save path
+ * enforces and the projection a client greys out from are ONE function rather
+ * than two that happen to agree today.
+ */
+export function sharedRegion(a, b) {
+    const blocked = new Set(conflictingRegions(b));
+    return a.find((region) => blocked.has(region)) ?? null;
+}
+/** The catalog items a blob names, in slot order, skipping empty and unknown ids. */
+function equippedItems(settings, catalog) {
+    const worn = [];
+    for (const slot of COSMETIC_SLOTS) {
+        const id = settings[slot];
+        if (!isString(id) || id === "")
+            continue;
+        const item = cosmeticById(id, catalog);
+        // An id filed under the wrong slot is as unusable as an unknown one: the
+        // catalog, not the blob, decides where an item is worn.
+        if (!item || item.slot !== slot)
+            continue;
+        worn.push({ slot, item });
+    }
+    return worn;
+}
+/** The first pair of equipped items whose regions collide, or null. THE rule. */
+export function equipConflict(settings, catalog = CATALOG) {
+    const accepted = [];
+    for (const entry of equippedItems(settings, catalog)) {
+        for (const prior of accepted) {
+            const region = sharedRegion(prior.item.regions, entry.item.regions);
+            if (region) {
+                return {
+                    region,
+                    items: [prior.item.id, entry.item.id],
+                    slots: [prior.slot, entry.slot],
+                };
+            }
+        }
+        accepted.push(entry);
+    }
+    return null;
+}
+/**
+ * The first mandatory slot the loadout explicitly empties, or null.
+ *
+ * Explicitly is the whole subtlety: `""` is the unequip verb, while a slot the
+ * blob never names falls back to its default — the starting outfit, which fills
+ * every mandatory slot. So this refuses the request that undresses an avatar
+ * and never a partial patch that simply did not mention the slot.
+ *
+ * A slot the catalog sells nothing for is exempt for the same reason it is not
+ * a setting: there is nothing to put in it, so demanding one would lock every
+ * save out until content lands.
+ */
+export function bareSlot(settings, catalog = CATALOG) {
+    for (const slot of COSMETIC_SLOTS) {
+        if (!slotRequired(slot))
+            continue;
+        if (cosmeticsForSlot(slot, catalog).length === 0)
+            continue;
+        if (settings[slot] === "")
+            return slot;
+    }
+    return null;
+}
+/**
+ * The appearance surface's cross-field rule as the registry consumes it. Wired
+ * onto the surface rather than called from a route, so every write path gets
+ * it by construction.
+ *
+ * Two rules, one hook: a pair of items that cannot share a body, and a slot an
+ * avatar may not go without. Both are relations over the whole loadout rather
+ * than properties of one key, which is why neither can live in `sanitize`.
+ */
+export function appearanceConflict(settings, catalog = CATALOG) {
+    const conflict = equipConflict(settings, catalog);
+    if (conflict) {
+        const [first, second] = conflict.items.map((id) => cosmeticById(id, catalog)?.name ?? id);
+        return {
+            code: "equip_region_conflict",
+            message: `${first} and ${second} both occupy the ${conflict.region} region`,
+            keys: [...conflict.slots],
+        };
+    }
+    const bare = bareSlot(settings, catalog);
+    if (bare) {
+        return {
+            code: "slot_required",
+            message: `${slotLabel(bare)} cannot be left empty`,
+            keys: [bare],
+        };
+    }
+    return null;
+}
+/**
+ * The equipped items that actually render: catalog-resolved, in slot order,
+ * with any item colliding with one already accepted dropped.
+ *
+ * Dropping here is a self-heal, not a second copy of the rule — the save path
+ * refuses conflicts, so a stored blob can only become conflicting when a
+ * catalog edit changes an item's regions underneath it. Both paths call
+ * {@link sharedRegion}, so there is still exactly one definition of collision.
+ *
+ * Everything downstream of a loadout resolves it through here, which is what
+ * keeps the colour pickers a player is offered and the equipped set a game
+ * server receives describing the same avatar.
+ */
+function wornItems(settings, catalog) {
+    const worn = [];
+    for (const entry of equippedItems(settings, catalog)) {
+        const collides = worn.some((prior) => sharedRegion(prior.item.regions, entry.item.regions) !== null);
+        if (!collides)
+            worn.push(entry);
+    }
+    return worn;
+}
+/**
+ * The `appearance` key holding one item's colour for one of its materials.
+ *
+ * Segmented rather than opaque so it can GROW without a second key space:
+ * GAME-178 paints a masked region of an item instead of its whole surface,
+ * which is one more segment here. The separator is legal in a JSON key and
+ * illegal in an id and a material name, which `cosmetics.test.ts` enforces —
+ * without that a key would be ambiguous the day someone names an item
+ * `round.glasses`.
+ */
+export function paintKey(itemId, material) {
+    return [PAINT_KEY_PREFIX, itemId, material].join(PAINT_KEY_SEPARATOR);
+}
+/**
+ * Every recolourable surface the equipped set exposes, in slot order: one
+ * entry per paintable material on each worn item.
+ *
+ * This is what makes the appearance surface dynamic — the colour pickers a
+ * player sees are a function of what they are wearing, so a colour cannot
+ * outlive the item it painted.
+ */
+export function paintSlots(settings, catalog = CATALOG) {
+    return wornItems(settings, catalog).flatMap(({ slot, item }) => item.paintable.map((material) => ({
+        key: paintKey(item.id, material),
+        slot,
+        item,
+        material,
+    })));
+}
+/**
+ * The colours a blob holds for one item's paintable materials, skipping any it
+ * does not name. Absent rather than blank: no colour is an instruction to
+ * leave the item as it was authored, which is not the same as painting it
+ * nothing.
+ */
+function paintFor(settings, item) {
+    const paint = [];
+    for (const material of item.paintable) {
+        const color = settings[paintKey(item.id, material)];
+        if (isString(color) && color !== "")
+            paint.push({ material, color });
+    }
+    return paint;
+}
+/**
+ * The equipped set as `/api/session/verify` hands it to a game server: the
+ * items that render, each carrying the regions it occupies, the body it
+ * suppresses, and the paint to apply to it.
+ */
+export function equippedFor(settings, catalog = CATALOG) {
+    const equipped = {};
+    for (const { slot, item } of wornItems(settings, catalog)) {
+        equipped[slot] = {
+            id: item.id,
+            name: item.name,
+            regions: item.regions,
+            hides: item.hides,
+            paint: paintFor(settings, item),
+        };
+    }
+    return equipped;
+}