@homie-rocks/studio 0.24.5 → 0.26.0

package/CHANGELOG.md

@@ -17,9 +17,62 @@ 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.26.0] - 2026-10-03
+
+**Plugin 0.27.0** · [#40](https://github.com/homie-rocks/homie/pull/40)
+
+A game's first minute: Play never opens on a blank screen, a bright game gets a bright landing in its own palette, and in Hero Rush 3D a new player's first round is a race they are in.
+
+### Added
+
+- The arrival card. From the play page's first paint (and the big screen's), the game's own look covers its frame while the room connects and the game loads: its title and pitch, its key art (the landing's hero still, a trailer's poster or its cover, drifting slowly), a progress line that says what is happening ("Finding a room…", "Room 4 · 3 playing · 2 AI", "Loading the game…", "Joining Room 4…", the game's own "Loading the heroes… 60%"), and the controls for this device from `landing.controls`. It is drawn in the game's palette (style.json), else its landing's colours, else the studio's, and it fades the moment the game is playable. `?arrive=0` leaves it out.
+- The netplay helper tells the play page when the game is playable (NETPLAY.md section 21): by itself once the browser is seated and has the room's state, or, for a game that keeps loading after that (models, textures, a baked world), at the game's own `net.playable()` (`createNetplay({ arrival: 'game' })`), with `net.loading(fraction, 'the heroes')` for the progress line. Nothing crosses the relay; the wire stays revision 8.
+- `homie-studio perf` measures the time to the first meaningful frame (`load.look`: the arrival card on the screen), and its time to playable waits for the card to lift. The perf skill's goals include it ("it opens on a blank screen").
+
+### Changed
+
+- A game with its own palette (style.json) and no `landing.scheme` or `landing.theme` of its own gets its landing in that palette: its paper as the page, its ink as the words, its accents, light or dark as its paper is, when the ink reads on the paper (4.5:1). Its footage keeps its colour, and the words sit on a soft panel of its paper. A bright game is no longer shown on the studio's dark page. A scheme or colours the owner set, a page of the studio's own and `site/theme.css` still win; a game without a style.json keeps the studio's look.
+- Hero Rush 3D: the bots never swamp a new player. In somebody's first round in the room, when nobody set the AI dial, the bots play a level easier. A bot far ahead of the best person in the room eases off (it walks, reacts later, swings less, then races for the coins near that person, or keeps near them, up their screen, without taking coins) and plays at its dial again once it is within its lead: Rookie −1, Steady 1, Fair 2, Strong 5, Maxed none. Scores stay honest (no score is ever changed, no coin given, taken or faked), and every bot is labelled, the phone's compact board too ("bot" or "AI" after the name). A casual player's first round at the default dial ended 61 coins behind the best bot before, and about 4 behind now; a player who chases the coins still wins clearly, and Maxed bots still beat a casual player.
+- Hero Rush 3D on a phone held upright: the camera follows lower and closer (30 degrees, about 5.5 m across), so every hero reads as a character (a mage was the top of its hat), and your name chip says what you are ("You · Mage"). The game passes `arrival: 'game'`: the card lifts on your own hero in its real model, never a stand-in. Your own hero is asked for first, the moment your seat is known, then the other heroes, then the skeletons (on an emulated slow phone your real hero is drawn at about 1.4 s instead of 2.1 s, the same bytes), the in-game title card is gone (the arrival card has the title), the "×2" mark moves off your hero and the controls hint sits above the touch buttons.
+
+### Upgrade notes
+
+- Nothing to do: `homie-studio upgrade` brings the arrival card to every game, and a game built before 0.26.0 lifts it once it has a seat. A game whose world keeps loading after its first state can say when it is ready: `createNetplay({ …, arrival: 'game' })`, `net.loading(p, 'what')` while it loads, and `net.playable()` once its world and the player's own body are drawn. A game made from Hero Rush 3D before 0.26.0 keeps its own code: tell Claude "bring the starter's first-round bots and phone camera into my game" if you want them.
+
+## [0.25.0] - 2026-10-03
+
+**Plugin 0.26.0** · [#38](https://github.com/homie-rocks/homie/pull/38) · [release-2026-10-03-studio-0.25.0](https://github.com/homie-rocks/homie/releases/tag/release-2026-10-03-studio-0.25.0)
+
+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)
+**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.
 

package/README.md

@@ -96,11 +96,14 @@ licence its owner picked in game.json `"license"`: `"remix-with-credit"` (the de
 `"no-remix"`, which `game remix` refuses. Every page ends with "Made with Homie". Anything the studio puts in `site/` wins: a whole page, a partial, its tokens, its CSS, its
 files. `site/SITE.md` says all of it.
 
-The play page writes its room into the address, and a small room button at the edge shares it: Invite, Big
-screen and the room code. game.json's `screen.share` puts it where each game has room, per device (a corner or
+The play page never opens blank (0.26.0): from its first paint an arrival card shows the game's own look (its title,
+pitch and key art in its palette, a progress line that says what is happening, and the controls for the device) until
+the game says it is playable (`NETPLAY.md` section 21; `worker/arrival.mjs`). It writes its room into the address, and
+a small room button at the edge shares it: Invite, Big screen and the room code. game.json's `screen.share` puts it where each game has room, per device (a corner or
 the top's middle, moved in by `x` / `y`, or kept a small icon), so it never covers a scoreboard. A game whose
 picture is white or cream gets a light landing (`landing.scheme: "light"`). Every card and the directory show a
-game's landing still. Every HTML answer is `no-transform`, and the site's pages are never framed by another
+game's landing still. A game with its own palette (style.json) and no landing colours of its own gets its landing
+in that palette, light or dark as its paper is (0.26.0). Every HTML answer is `no-transform`, and the site's pages are never framed by another
 site. A game made with Homie's arcade controls that knocks for a Homie box (`/__homie/call`) is told
 `not-a-homie`, at the site's root as under the game.
 
@@ -519,7 +522,8 @@ rules, the bots, the snapshots) and a replica, both a computer (1280x800 at 2x)
 on a fast computer is less than its rate). They play the same seeded presses through a warm-up and a measured
 window, and each run's JSON says, per browser: the time between animation frames (median, p95, p99, the share over 33
 and 50 ms), the game's JavaScript per frame (every requestAnimationFrame callback timed), the main thread per frame
-(Chrome's TaskDuration), time to the first frame, to a seat and to playable, the game's files on the wire, the heap
+(Chrome's TaskDuration), time to the first meaningful frame (`load.look`: the play page's arrival card), to the
+game's first frame, to a seat and to playable, the game's files on the wire, the heap
 after a garbage collection, and netplay messages and kilobytes a second each way. `--profile` adds a CPU profile per
 browser in a window of its own (a `.cpuprofile` for Chrome DevTools) and its hottest functions, read through the
 game's source map when the build kept one (`homie-studio build --maps` keeps it in `.studio/maps/<id>/`, never in
@@ -601,7 +605,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
@@ -631,6 +635,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
@@ -712,7 +762,7 @@ npx homie-studio port check my-game --url http://127.0.0.1:8787   # the owner te
 | `lib/port-check.mjs` | `port check`: held and alternating directions on keys, Android Chrome and iPhone WebKit touch, UI cover, two browsers finishing a round, a killed host, a late joiner, the big screen. |
 | `port/` | The port toolkit (`@homie-rocks/studio/port`, or `window.HomiePort` from `homie-port.js` in a static game): `createRoom`, the touch kit, keys, camera rules, bots, a HUD, sandbox shims, first-touch audio, `exposePort`; `fitView` and `createLabels` (`port/view.ts`): a flat world on every screen (the whole of it where it reads, else filling a phone held upright and following the player) and names that never pile up when bodies crowd (yours placed first, the rest moved or faded). |
 | `worker/index.mjs` | The site Worker and the `Table` (netplay relay, `room.mjs`) and `Lobby` Durable Objects; `/<game>/tv` is the big screen with a join QR (`qr.mjs`); `/<game>/watch` watches a live room from any player's view (NETPLAY.md section 16); `/music/<slug>/` and `/videos/<slug>/` are song and video pages (their files served with byte ranges, from the site's files or, once moved, from the studio's R2 at the same address; a loose file from `media put` at `/media/<key>`). `seats.mjs`: room sizes (up to 32). |
-| `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page. |
+| `worker/site.mjs`, `lib/site.mjs`, `lib/markdown.mjs`, `site/SITE.md` | The site: its sections, each game's landing, posts and their feeds, the look (theme tokens) and what the studio's `site/` folder overrides; the safe markdown posts are written in. `worker/pages.mjs`: the play page; `worker/arrival.mjs`: its arrival card. |
 | `worker/stats.mjs`, `worker/stats-page.mjs`, `lib/stats.mjs` | The studio's own stats: what is counted and how, the owner-only `/api/stats` and `/_studio/stats`, and `homie-studio stats`. |
 | `lib/media.mjs`, `media/MEDIA.md` | The `music/` and `videos/` manifests: which entries get a page, and where each file's bytes come from (the site itself up to 25 MiB a file, the studio's R2, or a link). `media list` shows it; `media move` puts the big ones in R2 and records each one's SHA-256; `media put` uploads a loose file to `/media/<key>`. |
 | `netplay/` | The netplay contract (`NETPLAY.md`) and its game helper (`@homie-rocks/studio/netplay`). |