# Cast3D
The 3D anime cast of "Kicked Out of the Hero's Party": six rigged, cel-shaded humanoid characters (Ren, Seraphine, Gorvin, Dorian, Mira, King Aldric), a humanoid clip per action, 15 gear models that seat on the rig, and one call to put a character in a scene. Scene builds and gameplay code call it; the synced `CastActor` component it adds rebuilds each character's look on every peer.
```luau
local Cast3D = require("game.cast3d.Cast3D")
-- in a scene build's content(), or at runtime
local ren = Cast3D.spawnCharacter("ren", { position = { 0, 0, 0 }, yaw = 180 })
Cast3D.wearSet(ren, "starter") -- rusty shortsword + leather vest
Cast3D.equip(ren, "code_katana") -- replaces the main-hand weapon
Cast3D.equip(ren, "iron_longsword", { sheathed = true }) -- on the back instead
Cast3D.unequip(ren, "head")
Cast3D.play(ren, "attack1") -- one-shot, returns to idle when it ends
Cast3D.play(ren, "run") -- loops
local mira = Cast3D.spawnCharacter("mira", { position = { 4, 0, 2 }, yaw = -90 }, { action = "sit_desk" })
Cast3D.applySceneLook("tvAnime") -- the whole-scene anime look (cel light, rim, ink line); idempotent
```
## Characters (`Cast3D.CHARACTERS`)
| id | name | model bundle | cel material | height |
|---|---|---|---|---|
| `ren` | Ren | `game.cast3d.models.ren` | `game.cast3d.materials.Material_0_ren_toon` | 1.75 m |
| `seraphine` | Seraphine | `game.cast3d.models.seraphine` | `..._seraphine_toon` | 1.76 m (default gear: iron longsword) |
| `gorvin` | Gorvin | `game.cast3d.models.gorvin` | `..._gorvin_toon` | 1.42 m |
| `dorian` | Dorian | `game.cast3d.models.dorian` | `..._dorian_toon` | 1.88 m (bow and quiver are part of his mesh) |
| `mira` | Mira | `game.cast3d.models.mira` | `..._mira_toon` | 1.62 m |
| `king` | King Aldric | `game.cast3d.models.king` | `..._king_toon` | 1.82 m |
Each model was generated from a full-body A-pose reference (`refs/<id>_apose.texture`, prompts reuse the sprite prompts of `game/stage/sprites/<id>_neutral.texture`) with mesh_gen `from_image`, then auto-rigged with mesh_gen `rig` (Mixamo-style 24-bone skeleton: Hips, Spine, Spine01, Spine02, neck, Head, Left/Right Shoulder, Arm, ForeArm, Hand, UpLeg, Leg, Foot, ToeBase). The unrigged meshes stay beside them as `models/<id>_mesh`.
## Actions (`Cast3D.CLIPS`)
`idle`, `walk`, `run`, `attack1`, `attack2`, `attack3` (the 3-swing sword combo), `heavy`, `dodge` (forward roll), `parry`, `block` (held guard, loops), `hit`, `death`, `cast` (spell), `blast` (two-palm energy blast), `talk` (gesturing, loops), `sit` (sit down and stay), `sit_desk` (seated at a desk, loops; Mira's reception desk).
`Cast3D.LOOPING` lists the looping ones; every other action plays once and returns to the actor's `after` action (default its idle). `dodge`, `hit` and `blast` are published humanoid clips (Banana 2077, comboKit); the rest were generated with anim_gen for these rigs. All of them retarget onto every cast rig.
## Attach points (`Cast3D.ATTACH`)
Slots follow inventoryKit's equipment slot names and seat on the engine's standard Humanoid avatar points, so they work on any humanoid body:
| slot | avatar point | bone on the cast rigs |
|---|---|---|
| `mainHand` | `rightGrip` | RightHand |
| `offHand` | `leftGrip` | LeftHand (second twin dagger) |
| `back` | `bodyBack` | Spine (sheathed weapon) |
| `head` | `hat` | Head |
| `chest` | `neckBase` | upper torso |
| `shoulders` | `neckBase` | upper torso |
| `cloak` | `neckBase` | upper torso |
## Gear (`Cast3D.GEAR`)
Weapons (slot `mainHand`): `rusty_shortsword`, `iron_longsword`, `crystal_blade`, `code_katana`, `oak_staff`, `twin_daggers` (pair: one per hand), `greatsword`, `spear`.
Armour: `leather_vest`, `chain_shirt`, `guild_coat` (chest), `codeweave_cloak` (cloak), `circlet`, `helmet` (head), `shoulder_pads` (shoulders).
Each entry holds the model bundle (`game.cast3d.gear.<id>`), its baked cel material, its slot, its longest side in metres (`size`), the point of its box that sits on the attach point (`pivot`) and an extra `rotation`/`position`, the same shape as inventoryKit's wear table. Weapons are modelled blade up and laid along the grip's +Z. Armour scales with the wearer's height.
Sets (`Cast3D.SETS`): `starter` (rusty shortsword, leather vest), `knight` (iron longsword, chain shirt, helmet, shoulder pads), `whisperer` (code-forged katana, code-weave cloak, circlet, guild coat).
To show inventoryKit gear on a cast member, map the item id to a `Cast3D.GEAR` id and call `Cast3D.equip`; or give inventoryKit items `model = game.cast3d.gear.<id>` with `fits: [righthand]` and the kit's own wear table seats them.
## The anime look
Two layers, both from ZeroMind packages (animeBlocks, which brings toonBlocks and styleKit):
- **In the material**: every character and gear piece wears a toonBlocks `toonLit` material baked by `tools/bake_cel.luau` (two hard bands, lavender shadow, warm rim, small highlight), keeping the generated colour texture. This shows in any scene and any capture.
- **Over the scene**: `Cast3D.applySceneLook(look)` puts an animeBlocks look on the active scene (default `tvAnime`), which draws the ink line, with an inverted hull on skinned characters for inner lines. The lead decides each scene's look; offscreen captures do not show it, `capture { source = "presented" }` does.
## How it is built
- `CastActor.component`: synced fields `character`, `action`, `after`, `nonce`, `gear`, `cel`, `speed`. Each peer swaps in the cel material, drives a `ClipPlayer` on the skinned mesh, and seats gear (temporary, unsynced entities) with `Humanoid:attach`.
- `tools/gen_refs.luau`: the A-pose reference images. `tools/bake_cel.luau`: the cel materials (re-run after regenerating a model).
- `Showcase.scene`: every character in a row plus Ren in the three sets. Load it in a sub-client to check the cast.
## Limits
- The generated rigs have no finger bones, so hands stay open while holding weapons.
- Armour is rigid (seated on one bone), so long hems (guild coat, cloak) can clip the legs during big moves.
- The cel material is per character, so `cel = false` on a CastActor brings back the generated PBR look.