@homie-rocks/studio 0.24.4 → 0.25.0

package/CHANGELOG.md

@@ -17,9 +17,63 @@ To bring a studio up to date, tell Claude: "Upgrade my studio to the newest Homi
 `npx -y @homie-rocks/studio@latest upgrade`, which shows what's new since the version your studio pins (from this
 file) and what the upgrade would change, and changes nothing until you agree.
 
+## [0.25.0] - 2026-10-03
+
+**Plugin 0.26.0** · [#38](https://github.com/homie-rocks/homie/pull/38)
+
+Animated characters for 3D games: free CC0 heroes or one generated and auto-rigged on your fal account, on one skeleton standard with the library's clips retargeted onto it, and a shared player that runs, jumps and swings with IK feet and springs.
+
+### Added
+
+- A skeleton standard (`lib/rig.mjs`): a humanoid family with VRM 1.0 bone names, a mini family for one-piece limbs (Kenney's mini and blocky characters), a quadruped and a rigid "parts" family. A rig from Mixamo, KayKit, Blender, Unreal or Meshy is mapped onto it by name and by its hierarchy, and recorded with a skeleton id (`humanoid-3fa2c1`): characters with the same skeleton share one clip library.
+- `homie-studio assets add` takes animated characters from the free library (KayKit's adventurers and skeletons, Kenney's mini and blocky characters, all CC0) and `--file <model> --kind character --rigged` for your own. The shipped character is phone-sized: joints renamed to the standard, helper bones dropped, skinned parts and the accessories you keep (`--keep sword,shield`) merged into one draw call, its clips moved out.
+- Clip libraries: `public/anims/<skeleton>.glb` holds one clip per verb (idle, walk, run, jump, fall, land, attack, cast, hit, die, ...), 30 frames a second, compressed, with where each clip came from. Clips are retargeted at build time from the library's CC0 sources onto any humanoid or mini skeleton (rest-pose alignment per bone, hips scaled by leg height, loops kept in place).
+- `homie-studio cast <id>`: the characters, with their proportions, silhouette, palette, skeleton family and clips. `homie-studio anim plan|add|preview <id>`: each character's clips against the verbs the game needs, more verbs retargeted on, and looping previews (animated WebP) with a sheet.
+- `@homie-rocks/studio/animate`: one shared three.js `AnimationMixer` player. `loadCharacter` finds a character's clip library from the model; `createCharacter` blends idle, walk and run by speed, plays upper-body actions while running, an additive hit flinch and hit-stop, jump, fall and land with squash and stretch on a spring, lean into turns, look-at, springs and two-bone IK feet, and a cheaper crowd mode past a dozen characters. `ANIM_TUNING` is what the Game Lab tunes.
+- A 3D starter with animated heroes, `hero-rush-3d`: knights, mages, rogues and barbarians race for coins in a clearing, jump, dodge and swing at each other, on a phone (Jump and Swing buttons) and a computer, multiplayer with skeleton bots in empty seats. Each round opens on a close-up of your own hero that pulls back to play, and the Game Lab has takes for the jump and the swing.
+- Generated characters (paid, on your own fal account): the models skill's `character` command makes an A-pose concept in the game's style (`--like` a library character's thumbnail), then Meshy 7.1 image-to-3D with its auto-rig (about US$1.40 with textures and the rig), then free: made phone-sized, mapped to the standard and given the library's clips. Both calls have receipts under the budget.
+- MCP tools and cards: `cast_plan` (the cast card), `character_make` (the lineup with a character beside the others), `anim_plan`, `anim_add` and `anim_preview` (an Animation card of looping clips: Add is free, Feel opens the Game Lab on that move, New against Today).
+- An `animate` skill: the skeleton standard, retargeting, clip rights (KayKit and Kenney CC0; Quaternius's own licence since 2026-08-28 is not CC0 and is not used; text-to-motion models are not offered, because the ones available are non-commercial in effect).
+- In Claude Code, `/cast` and `/clips`, and the Studio pane's Art tab shows the characters (skeleton, bones, clips) and the skinning cost on a phone.
+
+### Changed
+
+- `assets check` checks skinned meshes: more than four bone influences per vertex, a character without its clip library or missing a verb the game needs, clip libraries over 1 MB (3 MB is a problem) or over 30 frames a second, and the skinning cost of every player's character at once against a phone's budget (skinned vertices and bones), with crowd mode past twelve characters.
+- A rigged model is measured by its skin (its joints' positions), so a character exported in centimetres is no longer 100 times too big, and it is centred by a wrapper node instead of moving its skeleton.
+- The lineup poses rigged characters in their idle clip and draws their silhouettes from the posed skin.
+- `style init` on a starter keeps what the starter already draws (its `style.json`: render, palette, materials, light, camera, fonts) as the automatic picks, and the clip decision lists the clips the game has.
+- The fal price check adds a model page's add-ons (Meshy's textures and rig) and quotes the higher of fal's pricing API and the page.
+
+### Upgrade notes
+
+- Nothing to do: games without characters are unchanged. To animate a 3D game's characters, tell Claude: "Give my game animated characters."
+
+## [0.24.5] - 2026-10-03
+
+**Plugin 0.25.5** · [#39](https://github.com/homie-rocks/homie/pull/39) · [release-2026-10-03-studio-0.24.5](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-03-studio-0.24.5)
+
+Room chat keeps off your game's HUD: on a phone the Chat pill is a round icon, as the room button is, and your game can say where the strip of new lines sits, or keep new lines in the Chat sheet, so a game with a busy HUD keeps typed chat.
+
+### Added
+
+- game.json `"screen": { "chat": … }` says where room chat's strip of new lines sits on each screen: `at` (a corner, `top-center` or `bottom-center`), `x` / `y` to move it in from its side and its edge, and `"lines": "sheet-only"` to keep new lines in the Chat sheet while the pill counts them. `desk`, `phone`, `sideways` and `tv` (the big screen's corner of lines) each take their own, changing only what they name. A game whose HUD or controls sit where the strip shows no longer has to keep chat to emoji to stay clear. `chat/CHAT.md` has every field; the template's AGENTS.md and the game skill say when to use it.
+- `homie-studio build` warns about a wrong field in `screen.chat` (the play page uses the default there), and says so when a place or `"sheet-only"` is written in game.json `"chat"` (the room's rules) instead.
+
+### Changed
+
+- The Chat pill follows the room button: on a phone (either way up), and beside a room button your game keeps an icon (`screen.share` `"label": false`), it is a round icon with the count of new lines on its corner. On a computer it still says "Chat", unless the word would take the room button's band off the screen or into the middle third of its width, where games keep a clock or a title; then it stays the icon until the window changes size.
+
+### Fixed
+
+- On a phone, the Chat pill's word no longer covers the HUD beside the room button: the first digit of a clock, the last letter of a title.
+
+### Upgrade notes
+
+- Nothing to do: a game without `screen.chat` shows the strip where it did. If you kept a game's chat to emoji only so the strip stayed off its HUD, tell Claude: "Put room chat where my game has room, and let players type again." It places the strip with `screen.chat` and resets the game's chat rules (`homie-studio chat rules <game> --reset`).
+
 ## [0.24.4] - 2026-10-03
 
-**Plugin 0.25.4** · [#37](https://github.com/homie-rocks/homie/pull/37)
+**Plugin 0.25.4** · [#37](https://github.com/homie-rocks/homie/pull/37) · [release-2026-10-03-studio-0.24.4](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-03-studio-0.24.4)
 
 Your AI guides think with Cloudflare's Clef decision model, which does what a player asks; Clef runs on your own computer while you build; and your games can ask it for their own decisions (tactics, a director's call, a turn) in about a quarter of a second.
 

package/README.md

@@ -316,8 +316,9 @@ npx homie-studio chat remove night-rush pub-3 <line id>                 # take a
 npx homie-studio chat words                                             # the built-in word list the floor holds
 ```
 
-- **The play page:** a Chat pill beside the room button (the corner `screen.share` keeps clear of the HUD), its
-  sheet (the last minutes, the reactions, the quick lines, typing, Report), a short ticker of new lines, and two
+- **The play page:** a Chat pill beside the room button (the corner `screen.share` keeps clear of the HUD; a round
+  icon on a phone), its sheet (the last minutes, the reactions, the quick lines, typing, Report), a short strip of
+  new lines (game.json `screen.chat` puts it where the game has room, or keeps new lines in the sheet), and two
   switches each player keeps: "Show my messages over my character" and "Show chat on this screen". The big screen
   shows the lines in a corner; the watch page has a Chat button; homie.rocks shows a room's chat on its card.
 - **Rules** per game (game.json `"chat"`) and per server, in the office or with `chat rules`: off, emoji, quick
@@ -600,7 +601,7 @@ npx homie-studio assets remove crown-thief lantern       # the record and the co
 
 A game's look is a set of decisions (`games/<id>/codex/decisions.json`, private like the codex, drawn in its Art
 direction tab): render style, palette, shape, proportions, materials, light, camera, fonts and effects; the cast, its
-library family, scale and phone budgets; rigs and animation (later phases). Each starts as an automatic pick with a
+library family, scale and phone budgets; the skeleton standard and the clips each role needs. Each starts as an automatic pick with a
 why. A person's nudge makes it steered, their lock freezes it, and the first asset built on an automatic one pins it.
 Every asset records the revision of each decision it was made under, so changing one lists exactly what went stale and
 what remaking it would cost; nothing is remade by itself. `games/<id>/style.json` (public) is the palette, fonts, light
@@ -630,6 +631,52 @@ The local MCP's `style_explore`, `decision_set`, `assets_plan`, `assets_find`, `
 `asset_check`, `asset_lineup` and `asset_rights` do the same with cards. Generated props (on the person's own fal
 account, under a budget, receipted) are the Homie plugin's `models` skill.
 
+## Characters, rigs and clips (`homie-studio cast`, `homie-studio anim`)
+
+```sh
+npx homie-studio assets find "knight" --kind character   # animated CC0 characters: KayKit, Kenney
+npx homie-studio assets add heroes kaykit-adventurers/knight --as knight --height 1.45 \
+  --keep "1H_Sword,Round_Shield,Knight_Helmet,Knight_Cape" --verbs idle,walk,run,jump,attack,hit,die
+npx homie-studio assets add heroes --file ./hero.glb --kind character --rigged --license own --as hero
+npx homie-studio cast heroes                               # proportions, palette, skeleton family, every character
+npx homie-studio anim plan heroes                          # each character's clips against the verbs the game needs
+npx homie-studio anim add heroes knight --verbs block,dodge # more, retargeted onto its skeleton (free)
+npx homie-studio anim preview heroes --asset knight        # looping previews and a sheet: .studio/art/<id>/anim/
+```
+
+A rigged character comes in as two files: `public/models/<asset>.glb` (its joints renamed to the skeleton standard:
+VRM 1.0 humanoid names, a mini family for one-piece limbs, a quadruped family; helper bones that move nothing removed;
+every part and every held thing it keeps merged into one skinned mesh, one draw call; phone-sized) and its skeleton's
+clip library `public/anims/<skeleton>.glb`, shared by every character with that skeleton. Clips are its own where it
+has them, else retargeted at build time from the starter library's CC0 humanoid clips (KayKit's): every bone turns in
+the world the way the source's turned from its rest, after the two rest poses are lined up bone by bone, so a T-pose
+clip plays on an A-pose rig; a one-piece limb aims where the source's whole limb points. It is plain matrix math in
+Node (no renderer), so it runs in CI and a cloud session too. `assets check` holds characters to four influences a
+vertex, the tier's bones, a clip library of 1 MB at 30 samples a second, every verb the game's `anim.clips` names,
+and the skinning a room costs on a phone (players times the heaviest character: 60,000 vertices and 1,200 bones a
+frame).
+
+In the game, `@homie-rocks/studio/animate`:
+
+```ts
+import { crowd, loadCharacter, ANIM_TUNING } from '@homie-rocks/studio/animate';
+const knight = await loadCharacter(models, './models/knight.glb', { tune: T });   // finds its clip library itself
+scene.add(knight.root);
+// each frame: knight.root.position.set(x, h, z); knight.face(yaw, dt); knight.move(speed); knight.air(onGround, vy); knight.update(dt);
+// events: knight.jump(); knight.act('attack', { from: 0.15 }); knight.hit(dx, dz); knight.die(); knight.hold('win');
+crowd(characters, camera);                                  // far and off-screen characters pose less often
+```
+
+Idle, walk and run blend by ground speed at the rate the feet need; an action while moving plays on the upper body;
+a hit is an additive flinch with a hit-stop; jump, fall and land squash and stretch on springs; it leans into turns,
+turns its head toward a point, swings tails and capes on springs and plants humanoid feet on slopes. Every number is
+an `ANIM_TUNING` entry for the game's tunables.json, so the Game Lab tunes it New beside Today.
+`game new <id> --from hero-rush-3d` is the arena with KayKit's animated heroes and skeletons: run, jump, swing, a
+cheer for the winner. The local MCP's `cast_plan`, `anim_plan` (looping previews; Feel opens the Game Lab on the
+move), `anim_add`, `anim_preview` and `character_make` do the same with cards. A generated, rigged character (a concept
+in the locked style, then Meshy's mesh and auto-rig on the person's own fal account, about US$1.44, priced and
+receipted) is the Homie plugin's `models` skill; rigs, clips and feel are its `animate` skill.
+
 ## Checks on a computer without a GPU
 
 `check`, `port check` and `look` run Chrome headless. On a Mac they use its GPU. On Linux (a Claude Code cloud