# Bestiary
The monsters and bosses of "Kicked Out of the Hero's Party": sixteen kinds across the Crypt, the Forest Ruin and the Corrupted Code Vault, each an aiKit enemy with SecondWind health, actionCombatKit telegraphs and a rigged, cel-shaded anime body that animates from the enemy's live state on every peer. Dungeon builders and encounter code call `Bestiary.spawn` (a full synced enemy) or `Bestiary.dress` (a body for an enemy other code made); the HUD and story code listen to `Bestiary.on("phase" | "died" | "bossAppeared" | "telegraph" | "staggered")` and read `Bestiary.bossInfo` for boss bars.
```luau
local Bestiary = require("game.bestiary.Bestiary")
local warden = Bestiary.spawn("crypt_warden", { 0, 0, -12 }, { yaw = 180 })
Bestiary.on("phase", function(ev) if ev.kind == "crypt_warden" and ev.index == 2 then --[[ Software Whispering moment ]] end end)
Bestiary.dress(arpgEnemy, "skeleton_soldier")
```
## Kinds (`Bestiary.KINDS`)
| dungeon | id | name | aiKit preset | hp | role |
|---|---|---|---|---|---|
| crypt | `skeleton_soldier` | Skeleton Soldier | chaser | 60 | sword grunt (rusty shortsword) |
| crypt | `ghoul_brute` | Ghoul Brute | chaser | 240 | big slow brute, every 3rd swing unparryable |
| crypt | `crypt_cultist` | Crypt Cultist | healer | 55 | caster, heals allies (oak staff) |
| crypt | `bone_archer` | Bone Archer | ranged | 45 | kiting shooter |
| crypt | `crypt_warden` | The Crypt Warden | boss | 1400 | BOSS, greatsword, 3 phases |
| forest | `stone_sentinel` | Moss Sentinel | chaser | 180 | stone tank |
| forest | `thorn_dryad` | Thorn Dryad | healer | 60 | caster |
| forest | `wolfkin_runner` | Wolf-kin Runner | chaser | 70 | fast runner |
| forest | `mushroom_brute` | Toadstool Brute | chaser | 220 | brute |
| forest | `bridge_golem` | The Bridge Golem | boss | 1800 | BOSS, 4.2 m, 3 phases |
| vault | `glitch_phantom` | Glitch Phantom | ambusher | 50 | flickering wireframe ambusher |
| vault | `corrupted_knight` | Corrupted Knight | chaser | 200 | elite (code katana) |
| vault | `null_swarmling` | Null Swarmling | swarm | 18 | pack swarmer |
| vault | `firewall_mage` | Firewall Mage | ranged | 70 | turret-like caster |
| vault | `dorian_corrupted` | Dorian | boss | 1500 | BOSS, chapter 3 duel, cast model in the glitch material |
| vault | `seraphine_corrupted` | Seraphine | boss | 2400 | FINAL BOSS, cast model in the glitch material |
Each row also holds model, material, height, telegraph windup, damage, range, cooldown, move speeds, attack clips, gear, xp and, for bosses, `title` and `phases` ({ name, above, line }).
## API
| call | does |
|---|---|
| `Bestiary.spawn(id, pos, opts?)` | synced enemy: Brain (`bestiary_<id>` preset), SecondWind health (death style `stay`), Telegraphed, MonsterBody. opts: yaw, name, team, route, health, damageScale, warning, leash, bossBar, active |
| `Bestiary.dress(enemy, id, opts?)` | body for an existing enemy; switches its Brain to a look-less copy of its preset |
| `Bestiary.presetName(id)` | defines and returns the aiKit preset |
| `Bestiary.bossInfo(id)` | `{ name, title, label, phases = "0.6 0.3", phaseNames }` |
| `Bestiary.phaseAt(id, fraction)` | phase index and name at a health fraction |
| `Bestiary.kindOf(enemy)` | kind id of a dressed enemy |
| `Bestiary.on(evt, fn)` | events on every peer: `phase` {entity, kind, index, name, line}, `died`, `bossAppeared` {entity, kind, name, title}, `telegraph`, `staggered` |
## How the body animates
`MonsterBody.component` (synced fields `kind`, `despawnAfterDeath`, `bossBar`) builds the body on each peer as a local, unsynced entity that follows the enemy, so late joiners and every screen get it from the fields alone. Each frame it reads: speed (position change) for idle / walk / run; the Telegraphed windup (`telegraph.windup`) for a slowed attack anticipation with a hot rim glow, then the strike at full speed; health drops for a hit react and white flash; `telegraph.staggered` for a stagger; death (SecondWind) for the death clip then a dissolve. Clips are the cast's humanoid clips (`game/cast3d/anims`).
Bosses get a barsKit `boss` bar (name, title, phase marks) on every screen within 40 m, and `phase` events when aiKit's boss brain changes phase.
## Files
- `models/<id>` rigged bundles (mesh_gen from_image + rig), `refs/<id>_apose` the reference images, `materials/<id>` glitchToon materials, `shaders/glitchToon` the shader.
- `tools/gen_refs.luau`, `tools/gen_models.luau`, `tools/bake_materials.luau` rebuild them.
- `Bestiary.scene` shows every kind in a row.
# 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.