Fix: Legendary camouflage parts, materials, names and attachments

Fixes a batch of legendary camouflage problems in the Tankopedia viewer, adds three missing unique camouflages and lets attachments be shown together with a camouflage.

## Camouflage parts (state switchers)
- Camouflages now choose which tank pieces show the same way the game does. Each switcher's load-time scenario script runs at export time (checks for attached camouflage items, or compares the camouflage preset), along with its state-switch actions. This replaces the old guess from part names (new `core/blitzkit/switcherStates.ts`).
- Fixes missing roof MGs, fenders and fuel tanks (IS-3 Bear, Obj. 140 Terror, IS-7, IS-4, FV215b 183, AMX 50 B, KV-1S) and default parts mixed into camouflages (Pershing Speedfire, Forest Witch Fullmetal, Waffenträger Goldstreifen).
- Switchers inside camouflage parts now show one state instead of all of them stacked (Obj. Kust double net, Goldstreifen stowage, Tiger II cat).
- States are matched by original node names, because the GLTF loader renames duplicates.
- Camouflage part meshes with no LODs (`lodIndex -1`) are kept, which restores the Tiger II cat body and missing pieces on about 11 other camouflages.

## Materials
- `AlphaBlend` materials export as transparent. `AlphaBlendAdditive` materials export as additive and are applied in `jsxTree`, and unlit `Textured` materials export as unlit (IS-8 Raroh flames, dinosaur holograms, and glass and screens on a few base tanks).
- Camouflage part materials that share a name with the tank's material no longer replace the tank's camouflage material (Bisonte C45 Unbreakable).

## Names
- With a legendary camouflage selected, the title shows the tank's in-battle name ("GuP Type 95 Ha-Go", "KV-1 Warrior", "Shinobi").
- Camouflages without a name in the game files yet show "Unreleased" in orange instead of their raw string key, and no longer crash the tank names list.

## Attachments
- Attachments (`kind: customization`) are listed in their own group under the camouflages and can be turned on together with a camouflage. They load the same way as camouflages and fade with the same transition.

## Other
- Liberté, You Rock! and Ozzie (single-tank camouflages that only set a preset through `override`) are now available.
- Mastery gun mark meshes (`custom_gun_marks_*`) are no longer drawn (Helsing, HWT20 FalconFire and two camouflage guns).

## Not included
- Pixel Wave, Digital Trace and Forest Shadow are tiled pattern camouflages, which the viewer can't render yet.
- FV301 Corbie's drone position and the dinosaur heads' glow depend on camouflage animations and emissive materials, which are separate PRs.

Fixes #417
Fixes #419
Fixes #421

packages/website/src/core/blitzkit/jsxTree.tsx

@@ -1,5 +1,11 @@
 import type { ComponentProps, ReactNode } from "react";
-import { Mesh, MeshStandardMaterial, Object3D } from "three";
+import {
+  AdditiveBlending,
+  Material,
+  Mesh,
+  MeshStandardMaterial,
+  Object3D,
+} from "three";
 
 export function jsxTree(
   node: Object3D,
@@ -29,6 +35,13 @@ export function jsxTree(
       props.material.depthWrite = true;
     }
 
+    if (
+      props.material instanceof Material &&
+      props.material.userData.blending === "additive"
+    ) {
+      props.material.blending = AdditiveBlending;
+    }
+
     return mergers?.mesh ? (
       mergers.mesh(node, props, node.uuid)
     ) : (

packages/website/src/core/blitzkit/skinTree.tsx

@@ -4,17 +4,56 @@ import { jsxTree } from "./jsxTree";
 
 type Mergers = Parameters<typeof jsxTree>[1];
 
-export function skinTree(
-  node: Object3D,
-  skin: Skin | undefined,
-  mergers: Mergers,
-) {
-  const skinNodes = new Map(
-    skin?.scene.children.map((node) => [node.name, node]),
-  );
+// names get sanitized and made unique on load
+function nameOf(object3d: Object3D): string {
+  return object3d.userData.name ?? object3d.name;
+}
+
+/**
+ * skins are layered in order, so an attachment's states win over the
+ * camouflage's
+ */
+export function skinTree(node: Object3D, skins: Skin[], mergers: Mergers) {
+  const skinNodes = new Map<string, Object3D[]>();
+  const materials = new Map<string, Material>();
+  const states: Record<string, string | null> = {};
+
+  for (const skin of skins) {
+    for (const node of skin.scene.children) {
+      skinNodes.set(node.name, [...(skinNodes.get(node.name) ?? []), node]);
+    }
+
+    for (const [name, material] of skin.materials) {
+      materials.set(name, material);
+    }
+
+    Object.assign(states, skin.scene.userData.states);
+  }
+
+  function switchChildren(object3d: Object3D, childMergers: Mergers) {
+    if (object3d.userData.state === undefined) return;
+
+    const name = nameOf(object3d);
+    const state = name in states ? states[name] : object3d.userData.state;
+
+    return object3d.children
+      .filter((child) => nameOf(child) === state)
+      .map((child) => jsxTree(child, childMergers));
+  }
+
+  const partMergers: Mergers = {
+    ...mergers,
+    group(object3d, props, key) {
+      return (
+        <group key={key} {...props}>
+          {switchChildren(object3d, partMergers) ?? props.children}
+        </group>
+      );
+    },
+  };
   const skinMergers: Mergers = {
     mesh(mesh, props, key) {
-      const material = skin?.materials.get((mesh.material as Material).name);
+      const material = materials.get((mesh.material as Material).name);
 
       return mergers!.mesh!(
         mesh,
@@ -23,20 +62,14 @@ export function skinTree(
       );
     },
     group(object3d, props, key) {
-      const skinNode = skinNodes.get(object3d.name);
-      const isSwitch = object3d.userData.state !== undefined;
-      const state = skin
-        ? skin.scene.userData.states[object3d.name]
-        : object3d.userData.state;
+      const parts = skinNodes.get(object3d.name) ?? [];
 
       return (
         <group key={key} {...props}>
-          {isSwitch
-            ? object3d.children
-                .filter((child) => child.name === state)
-                .map((child) => jsxTree(child, skinMergers))
-            : props.children}
-          {skinNode?.children.map((child) => jsxTree(child, mergers))}
+          {switchChildren(object3d, skinMergers) ?? props.children}
+          {parts.flatMap((part) =>
+            part.children.map((child) => jsxTree(child, partMergers)),
+          )}
         </group>
       );
     },

packages/website/src/core/blitzkit/switcherStates.ts

@@ -0,0 +1,255 @@
+import { parseHierarchies, type Sc2ReadStream } from "@blitzkit/core";
+import { times } from "lodash-es";
+
+interface Value {
+  "any.type": string;
+  "any.value": unknown;
+}
+
+interface ScriptNode {
+  type: string;
+  node: Record<string, unknown> & { defaults?: Record<string, Value> };
+  connections?: Record<
+    string,
+    { pinIn: string; pinOut: string; target: string }
+  >;
+}
+
+interface Script {
+  nodes: Record<string, ScriptNode>;
+}
+
+interface Action {
+  "act.delay": number;
+  "act.entityName": string;
+  "act.event": number;
+  "act.switchIndex": number;
+  "act.type": number;
+  "act.userEventId": string;
+}
+
+interface Entity {
+  name: string;
+  parent?: Entity;
+  children: Entity[];
+}
+
+const SELF_ENTITY = "*** Self ***";
+const SCENE_LOADED_EVENT = 1;
+const USER_EVENT = 2;
+const SWITCH_ACTIONS = [8, 9];
+// what the game fires as a tank is shown in the garage, in order
+const LOAD_EVENTS = ["Added", "TankAliveInHangar", "TankIsShownInNewScreen"];
+const MAX_DEPTH = 64;
+
+function findChild(entity: Entity, name: string): Entity | undefined {
+  for (const child of entity.children) {
+    if (child.name === name) return child;
+
+    const found = findChild(child, name);
+
+    if (found) return found;
+  }
+}
+
+function resolveTarget(owner: Entity, entityName: string) {
+  if (entityName === SELF_ENTITY) return owner;
+
+  const [first, ...rest] = entityName.split("->");
+  let target: Entity | undefined;
+
+  for (
+    let ancestor: Entity | undefined = owner;
+    ancestor && !target;
+    ancestor = ancestor.parent
+  ) {
+    target = ancestor.name === first ? ancestor : findChild(ancestor, first);
+  }
+
+  for (const name of rest) target = target && findChild(target, name);
+
+  return target;
+}
+
+/**
+ * replays what picks each state switcher's state as a tank is shown in the
+ * garage, with the camo's preset applied and its items attached; delayed
+ * actions are skipped so states stay as they are when the tank appears
+ */
+export function switcherStates(
+  sc2: ReturnType<Sc2ReadStream["sc2"]>,
+  preset: string | undefined,
+  attachments: Map<string, string[]>,
+) {
+  const scripts: Record<string, Script> = {};
+  const stateNames = new Map<Entity, string[]>();
+  const scenarios: { owner: Entity; script: Script }[] = [];
+  const actions: { owner: Entity; action: Action }[] = [];
+  const states: Record<string, string | null> = {};
+
+  function activateState(entity: Entity | undefined, state: number) {
+    const names = entity && stateNames.get(entity);
+
+    if (names) states[entity.name] = names[state] ?? null;
+  }
+
+  for (const component of Object.values(
+    sc2["#sceneComponents"] as unknown as Record<string, unknown>,
+  ) as { "comp.typename"?: string; "ssc.scripts"?: Record<string, Script> }[]) {
+    if (component?.["comp.typename"] !== "ScenarioSingletonComponent") continue;
+
+    Object.assign(scripts, component["ssc.scripts"]);
+  }
+
+  parseHierarchies<Entity>(
+    sc2["#hierarchy"],
+    { name: "", children: [] },
+    (hierarchy, components, parent) => {
+      const entity: Entity = { name: hierarchy.name, parent, children: [] };
+
+      parent.children.push(entity);
+
+      for (const item of attachments.get(hierarchy.name) ?? []) {
+        entity.children.push({ name: item, parent: entity, children: [] });
+      }
+
+      for (const component of components) {
+        switch (component["comp.typename"]) {
+          case "StateSwitcherComponent": {
+            const names = times(
+              component["ssc.statesCount"],
+              (index) => component[`ssc.state${index}`],
+            );
+
+            stateNames.set(entity, names);
+            states[entity.name] = names[component["ssc.activeState"]] ?? null;
+            break;
+          }
+
+          case "ScenarioComponent": {
+            const script = scripts[component["scenario.scriptId"]];
+
+            if (script) scenarios.push({ owner: entity, script });
+            break;
+          }
+
+          case "ActionComponent":
+            times(component["ac.actionCount"], (index) => {
+              actions.push({
+                owner: entity,
+                action: component[index.toString().padStart(4, "0")] as Action,
+              });
+            });
+            break;
+        }
+      }
+
+      return entity;
+    },
+  );
+
+  function runScenario(
+    { owner, script }: (typeof scenarios)[number],
+    event: string,
+  ) {
+    const { nodes } = script;
+    const links = (id: string) => Object.values(nodes[id].connections ?? {});
+
+    function input(id: string, pin: string): unknown {
+      const link = links(id).find((link) => link.pinIn === pin);
+
+      return link
+        ? output(link.target, link.pinOut)
+        : nodes[id].node.defaults?.[pin]?.["any.value"];
+    }
+
+    function output(id: string, pin: string): unknown {
+      const { type, node } = nodes[id];
+
+      switch (type) {
+        case "ScenarioSceneInfoNode":
+          return node["scenarioSceneInfoNode.infoKind"] === "GetCurrentEntity"
+            ? owner
+            : undefined;
+
+        case "ScenarioGetMemberNode":
+          return node["scenarioGetMemberNode.fieldName"] === "parent" &&
+            pin === "parent"
+            ? (input(id, "object") as Entity | undefined)?.parent
+            : undefined;
+
+        case "ScenarioFunctionNode":
+          switch (
+            `${node["scenarioFunctionNode.className"]}.${node["scenarioFunctionNode.functionName"]}`
+          ) {
+            case "Entity.FindChildByName": {
+              const entity = input(id, "entity") as Entity | undefined;
+              return entity && findChild(entity, input(id, "name") as string);
+            }
+
+            case "TankComponent.GetAppliedSkinMaterialConfigName":
+              return preset;
+
+            case "String.Compare":
+              return input(id, "1") === input(id, "2");
+          }
+      }
+    }
+
+    function execute(id: string, depth: number) {
+      if (depth > MAX_DEPTH) return;
+
+      const { type, node } = nodes[id];
+      let pin = "exit";
+
+      if (type === "ScenarioEventNode") {
+        pin = "event";
+      } else if (type === "ScenarioBranchNode") {
+        pin = input(id, "condition") ? "true" : "false";
+      } else if (
+        node["scenarioFunctionNode.functionName"] === "ActivateState"
+      ) {
+        activateState(
+          input(id, "entity") as Entity | undefined,
+          Number(input(id, "state")),
+        );
+      }
+
+      for (const link of links(id)) {
+        if (link.pinIn === pin) execute(link.target, depth + 1);
+      }
+    }
+
+    for (const id in nodes) {
+      const { type, node } = nodes[id];
+      const name =
+        node["ScenarioEventNode.eventName"] === "Custom"
+          ? node.defaults?.["Event Name"]?.["any.value"]
+          : node["ScenarioEventNode.eventName"];
+
+      if (type === "ScenarioEventNode" && name === event) execute(id, 0);
+    }
+  }
+
+  for (const event of LOAD_EVENTS) {
+    for (const { owner, action } of actions) {
+      if (
+        action["act.delay"] === 0 &&
+        SWITCH_ACTIONS.includes(action["act.type"]) &&
+        (event === LOAD_EVENTS[0]
+          ? action["act.event"] === SCENE_LOADED_EVENT
+          : action["act.event"] === USER_EVENT &&
+            action["act.userEventId"] === event)
+      ) {
+        activateState(
+          resolveTarget(owner, action["act.entityName"]),
+          action["act.switchIndex"],
+        );
+      }
+    }
+
+    for (const scenario of scenarios) runScenario(scenario, event);
+  }
+
+  return states;
+}