@gtanczyk/diorama 0.4.1 → 0.5.0

package/app/src/actions/fix.ts

@@ -171,6 +171,20 @@ defineAction({
   },
 });
 
+defineAction({
+  name: 'hero_size_set',
+  description: 'Say how tall the hero stands in a place, against a thing painted there: times that thing\'s painted height ("about as tall as the candle jar": 1). '
+    + 'Use it when the hero is far too big or small for the place, or differs from place to place in one world (a desk seen whole and a close-up of a mug), '
+    + 'or when only a strip of floor is walkable because the hero would be taller than the picture at the front. Sets the place\'s scale. Kept across rebuilds. No repaint: reruns derive to verify for that place.',
+  input: z.object({ slug: Slug, place: z.string().min(1), like: z.string().min(1), times: z.number().positive().max(20) }),
+  job: true,
+  async run({ slug, place, like, times }, ctx) {
+    return fixPlace(ctx, slug, place, 'derive', `hero size ${times} x ${like}`, (c) => {
+      c.heroSize = { like, times };
+    });
+  },
+});
+
 defineAction({
   name: 'hero_start_set',
   description: 'Set where the hero begins in a place (painting pixels, on walkable floor; the nearest roomy cell of the main floor is used): '

package/app/src/commands/derive.ts

@@ -16,6 +16,7 @@ import { closeFaces, placeDepth } from '../scene/occlusion-check.ts';
 import { gridOf } from '../scene/verify.ts';
 import { unionAll } from '../image/raster.ts';
 import { WorldFiles } from '../world/files.ts';
+import { readBodies } from '../scene/cast.ts';
 
 type MasksJson = { things: Record<string, Omit<ThingIn, 'key' | 'mask'>> };
 
@@ -54,7 +55,8 @@ async function walkPicture(painting: Buffer, g: Geometry, footprint: ThingIn['ma
   // The hero's size at three depths, as little figures spread over the floor (far left, middle, near right):
   // stacked boxes in one column read as a path, not as a person.
   const rows = g.walk.map((row, r) => (row.includes('#') ? r : -1)).filter((r) => r >= 0);
-  for (const [q, across] of [[0.1, 0.2], [0.5, 0.5], [0.95, 0.8]] as const) {
+  // No walkable row at all (NO_FLOOR): no figures to draw; verify reports the missing floor.
+  for (const [q, across] of rows.length ? ([[0.1, 0.2], [0.5, 0.5], [0.95, 0.8]] as const) : []) {
     const r = rows[Math.floor(q * (rows.length - 1))];
     const cols = [...g.walk[r]].flatMap((ch, c) => (ch === '#' ? [c] : []));
     // The walkable cell nearest to a quarter, the middle and three quarters of the frame, so they stand apart.
@@ -94,6 +96,7 @@ defineCommand({
     const files = new WorldFiles(slug);
     const world = files.world();
     const places = world.places.filter((p) => only.length === 0 || only.includes(p.key));
+    const heroMetres = readBodies(files, fs.existsSync)[world.hero.key]?.height;
     await Promise.all(places.map(async (place) => {
       const at = (...parts: string[]) => files.place(place.key, ...parts);
       // NPCs are drawn by the runtime, not painted: moving one only moves its box (and where the hero talks to it).
@@ -121,7 +124,7 @@ defineCommand({
         console.log(`  ${place.key}: no depth model for walls (${e.message})`);
         return undefined;
       });
-      const out = await derive(files.memo, { place, layout: asPainted, things, floors, painting, plates, carry, lastScale, previousScale, ...(start && { start }), ...(upright && { upright }), ...(said && { said }) }, (line) => console.log(`  ${place.key}: ${line}`));
+      const out = await derive(files.memo, { place, layout: asPainted, things, floors, painting, plates, carry, lastScale, previousScale, ...(start && { start }), ...(upright && { upright }), ...(said && { said }), ...(heroMetres && { heroMetres }), ...(readCorrections(at()).heroSize && { heroSize: readCorrections(at()).heroSize }) }, (line) => console.log(`  ${place.key}: ${line}`));
       // Shadows only with a light: without one the runtime has nothing to darken by.
       const lit = out.shadows.light && maskArea(out.shadows.mask) > 0;
       if (lit) files.write(at('masks', 'shadows.png'), await maskToPng(out.shadows.mask));

package/app/src/commands/model.ts

@@ -149,6 +149,14 @@ async function makeModel(files: WorldFiles, key: string, take: number, given: st
   try {
     views = await paintViews(files.memo, key, who.looks ?? '', painting, take, creature, (name, png) => files.write(out(`${name}.png`), png));
   } catch (error) {
+    // A creature whose sides never showed one body: no model, the painted figure hops as it is (an older model too
+    // was made from such sides, so it goes).
+    const message = error instanceof Error ? error.message : String(error);
+    if (creature && message.startsWith('its 4 sides do not show one creature')) {
+      if (fs.existsSync(out('model.json'))) fs.renameSync(out('model.json'), out('model-rejected.json'));
+      console.log(`${key}: no 3D model: ${message}; the painted figure hops as it is`);
+      return message;
+    }
     // Refused even in calm words: the model made before stays (a changed prompt reran it), else the 2D rig walks.
     if (!refusedByFilter(error)) throw error;
     if (fs.existsSync(out('model.json')) && fs.existsSync(out('model.glb'))) {

package/app/src/commands/paint.ts

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import { writeBrief } from '../scene/brief.ts';
 import { seedRan } from '../scene/carry.ts';
-import { addsPerson, critique, paintedPeople, repaint } from '../scene/critic.ts';
+import { addsPerson, castLooks, critique, paintedPeople, repaint } from '../scene/critic.ts';
 import { readCorrections, writeCorrections } from '../scene/corrections.ts';
 import { Layout } from '../scene/layout.ts';
 import { paintPlace } from '../scene/paint.ts';
@@ -98,7 +98,7 @@ defineCommand({
         const again = await critique(files.memo, worded(place, words), brief, first);
         // People are looked for on the painting as the game shows it, with every fix in, not only the first one.
         const shown = fs.existsSync(files.place(place.key, 'painting.png')) ? fs.readFileSync(files.place(place.key, 'painting.png')) : first;
-        for (const p of shown === first || place.kind === 'drive' ? [] : await paintedPeople(files.memo, place.key, shown)) {
+        for (const p of shown === first || place.kind === 'drive' ? [] : await paintedPeople(files.memo, place.key, shown, castLooks(place))) {
           again.issues.push({ key: 'person', problem: 'unwanted', region: p.box, fix: `Paint out the ${p.what}: continue what is behind them (planks, water, wall), add nothing new` });
         }
         const had = new Set(found.issues.map((i) => JSON.stringify([i.region, i.fix])));

package/app/src/commands/studio.ts

@@ -58,6 +58,7 @@ function describe(e: StudioEvent, verbose: boolean): string | null {
     case 'agent.message': return `agent: ${String(e.text).slice(0, 200)}`;
     case 'agent.turn.end': return e.status === 'completed' ? null : `agent stopped: ${e.error ?? e.status}`;
     case 'agent.error': return `agent error: ${e.text}`;
+    case 'agent.limit': return `agent ${e.text}`;
     case 'agent.agent': return `agent is now ${e.label}`;
     case 'log': return verbose || e.stream === 'err' ? `  ${e.line}` : null;
     default: return null;

package/app/src/commands/voices.ts

@@ -14,7 +14,7 @@ import { resumePendingVoices } from '../sound/voices.ts';
 
 defineCommand({
   name: 'voices',
-  usage: 'voices <slug>            cast a voice per character (stock, or designed by ElevenLabs Voice Design for children, teens and the old) and speak every story line, checked by Muse Voice Transcribe; conversations, intro and endings [--all: every line; always for a world for kids, whose players cannot read] [--recast] [--draft: Flash and 2 takes; default final uses Multilingual v2 and up to 3 takes]',
+  usage: 'voices <slug>            cast a voice per character (stock, or designed by ElevenLabs Voice Design for children, teens and the old) and speak every story line, checked by Muse Voice Transcribe; every line the hero and the others say, intro and endings [--essential: only conversations, intro and endings, not the hero\'s looks, uses and locked doors] [--recast] [--draft: Flash and 2 takes; default final uses Multilingual v2 and up to 3 takes]',
   async run(args) {
     // Keep this generation at one quality even if Setup changes while it runs.
     process.env.DIORAMA_SOUND = soundQuality(args);
@@ -27,7 +27,9 @@ defineCommand({
     if (!elevenKey()) return void console.log('no ELEVENLABS_API_KEY: lines stay unspoken');
     const story = Story.parse(files.readJson(files.path('story.json')));
     const guard = await creditGuard(elevenKey(), 'voices');
-    const lines = storyLines(world, story, args.includes('--all') || world.audience === 'kids');
+    // Every line by default: a hero who answers out loud in conversations and is silent looking at things reads as broken.
+    // --essential keeps to conversations, intro and endings (a world for kids always gets every line).
+    const lines = storyLines(world, story, !args.includes('--essential') || world.audience === 'kids');
     const outFile = files.path('voices.json');
     const old = fs.existsSync(outFile) ? Voices.parse(files.readJson(outFile)) : undefined;
     let cast: Cast;

package/app/src/model/views.ts

@@ -158,6 +158,45 @@ async function paintCreatureViews(memo: Memo, key: string, looks: string, painti
     label: `${key}-view-${facing}`, size: SIZE, take, images: [front, back],
     prompt: `The same creature as in both pictures (front and back views), same colours and painted style, now seen exactly from the side in profile, facing to the ${facing} of the picture (${looks}), ${REST}. Same size and position in the frame as the pictures. ${PLAIN}`,
   }).then((png) => (onView?.(facing, png), png));
-  const [left, right] = await Promise.all([side('left'), side('right')]);
-  return { front, back, left, right };
+  const views: Record<ViewName, Buffer> = { front, back, left: front, right: front };
+  [views.left, views.right] = await Promise.all([side('left'), side('right')]);
+  // Muse can leave out or add a part between views (a mug drawn standing on a bottle loses the bottle in front and
+  // keeps it from the side): TRELLIS cannot make one body of that and the model comes out torn. Views that do not
+  // show the same creature as the front are painted again; still not one creature after that, there is no model.
+  for (let round = 0; round < CREATURE_ROUNDS; round++) {
+    const wrong = await checkCreature(memo, key, views, round);
+    const redo = Object.keys(wrong) as ViewName[];
+    if (!redo.length) return views;
+    console.log(`  ${key}: ${redo.map((v) => `${v} view: ${wrong[v]}`).join('; ')}; painting ${redo.length === 1 ? 'it' : 'them'} again`);
+    const t = take + 1 + round;
+    if (wrong.back) (views.back = await edit({
+      label: `${key}-view-back`, size: SIZE, take: t, images: [front],
+      prompt: `The same creature as in the picture (${looks}), with exactly the same parts and nothing more or less, same colours and painted style, in exactly the same pose, seen straight from behind: we see its back, its face is not visible. Same size and position in the frame as the picture. ${PLAIN}`,
+    }), onView?.('back', views.back));
+    await Promise.all((['left', 'right'] as const).filter((f) => wrong[f]).map(async (f) => {
+      views[f] = await edit({
+        label: `${key}-view-${f}`, size: SIZE, take: t, images: [front, views.back],
+        prompt: `The same creature as in both pictures (front and back views), with exactly the same parts as the front and nothing more or less, same colours and painted style, now seen exactly from the side in profile, facing to the ${f} of the picture (${looks}), ${REST}. Same size and position in the frame as the pictures. ${PLAIN}`,
+      });
+      onView?.(f, views[f]);
+    }));
+  }
+  const still = await checkCreature(memo, key, views, CREATURE_ROUNDS);
+  if (Object.keys(still).length) throw new Error(`its 4 sides do not show one creature (${Object.entries(still).map(([v, why]) => `${v}: ${why}`).join('; ')})`);
+  return views;
+}
+
+/** Rounds of repainting creature views that do not match the front. */
+const CREATURE_ROUNDS = 2;
+
+/** Which of the back and side views show a different creature from the front: a part left out or added (what it stands on, legs, a handle), another shape. */
+export async function checkCreature(memo: Memo, key: string, views: Record<ViewName, Buffer>, round = 0): Promise<Partial<Record<ViewName, string>>> {
+  const names: ViewName[] = ['front', 'back', 'left', 'right'];
+  const a = await askSparkJson<Record<string, { ok?: unknown; why?: unknown }>>(memo, {
+    label: `views-creature-check:${key}#${round}`, images: await Promise.all(names.map((v) => small(views[v]))),
+    prompt: 'Four pictures of one creature or living object, meant to be the same body seen from the front, from behind, from its left side and from its right side, so a 3D model can be built from them. '
+      + 'Compare pictures 2, 3 and 4 with picture 1 (the front). One is wrong when it shows a part the front does not, or lacks one the front has (something it stands on or in, a base, a bottle, a stand, legs, arms, a tail, a handle, a hat), or a clearly different body shape or size. Colours, light and the turned view itself are fine. '
+      + `Reply with JSON only: {${names.slice(1).map((v) => `"${v}": {"ok": true or false, "why": "a few words"}`).join(', ')}}`,
+  });
+  return Object.fromEntries(names.slice(1).flatMap((v) => (a[v]?.ok === false ? [[v, String(a[v]?.why ?? 'not the same creature as the front')]] : [])));
 }

package/app/src/scene/backdrop.ts

@@ -19,8 +19,10 @@ import { pasteInside } from './plates.ts';
 export const BACKDROP_GROW = 14;
 
 /**
- * Fills the masked pixels from their surroundings: a pyramid of averages of the known pixels,
- * read back from the finest level that has any. Smooth, never sharp; fine for a strip of a few px.
+ * Fills the masked pixels from their surroundings: a pyramid of averages of the known pixels (pull), then each
+ * level's empty cells read from the next coarser level, bilinearly (push), down to the hole's pixels. Smooth,
+ * never sharp. Read back nearest-cell, a big hole came out in square blocks of the coarse levels (64 px and more),
+ * which a tone correction carried into the backdrop as square patches round a lamp's light.
  * With `known`, only those pixels feed the fill.
  */
 export function smearFill(rgb: Uint8Array, W: number, H: number, hole: Mask, known?: Mask): Uint8Array {
@@ -46,18 +48,38 @@ export function smearFill(rgb: Uint8Array, W: number, H: number, hole: Mask, kno
     }
     levels.push(next);
   }
+  // Each level as colours: its own average where it has known pixels, else read from the level above it.
+  const colours = levels.map((l) => new Float32Array(l.w * l.h * 3));
+  const filled = levels.map((l) => Uint8Array.from(l.weight, (v) => (v > 0 ? 1 : 0)));
+  const sample = (k: number, fx: number, fy: number, out: Float32Array, at: number) => {
+    const l = levels[k];
+    const col = colours[k];
+    const x = Math.max(0, Math.min(l.w - 1, fx));
+    const y = Math.max(0, Math.min(l.h - 1, fy));
+    const [x0, y0] = [Math.floor(x), Math.floor(y)];
+    const [x1, y1] = [Math.min(l.w - 1, x0 + 1), Math.min(l.h - 1, y0 + 1)];
+    const [ax, ay] = [x - x0, y - y0];
+    for (let c = 0; c < 3; c++) {
+      const top = col[(y0 * l.w + x0) * 3 + c] * (1 - ax) + col[(y0 * l.w + x1) * 3 + c] * ax;
+      const bottom = col[(y1 * l.w + x0) * 3 + c] * (1 - ax) + col[(y1 * l.w + x1) * 3 + c] * ax;
+      out[at + c] = top * (1 - ay) + bottom * ay;
+    }
+  };
+  for (let k = levels.length - 1; k >= 1; k--) {
+    const l = levels[k];
+    for (let j = 0; j < l.w * l.h; j++) {
+      if (filled[k][j]) for (let c = 0; c < 3; c++) colours[k][j * 3 + c] = l.sum[j * 3 + c] / l.weight[j];
+      else if (k < levels.length - 1) sample(k + 1, ((j % l.w) + 0.5) / 2 - 0.5, (Math.floor(j / l.w) + 0.5) / 2 - 0.5, colours[k], j * 3);
+    }
+  }
   const out = rgb.slice();
+  if (levels.length === 1) return out;
+  const px = new Float32Array(3);
   for (let i = 0; i < W * H; i++) {
-    if (!hole.bits[i]) continue;
-    let [x, y] = [i % W, Math.floor(i / W)];
-    for (const l of levels) {
-      const j = y * l.w + x;
-      if (l.weight[j] > 0) {
-        for (let c = 0; c < 3; c++) out[i * 3 + c] = l.sum[j * 3 + c] / l.weight[j];
-        break;
-      }
-      [x, y] = [x >> 1, y >> 1];
-    }
+    // A known pixel in the hole (with `known`) keeps its own colour.
+    if (!hole.bits[i] || base.weight[i] > 0) continue;
+    sample(1, ((i % W) + 0.5) / 2 - 0.5, (Math.floor(i / W) + 0.5) / 2 - 0.5, px, 0);
+    for (let c = 0; c < 3; c++) out[i * 3 + c] = Math.round(px[c]);
   }
   return out;
 }

package/app/src/scene/corrections.ts

@@ -67,6 +67,12 @@ export const Corrections = z.object({
   take: z.number().int().min(0).optional(),
   /** Where the hero begins in this place (hero_start_set), instead of the front middle of the biggest floor. */
   start: XY.optional(),
+  /**
+   * How tall the hero stands here, against a thing painted in this place (hero_size_set): `times` that thing's painted
+   * height. The place's scale is set from it, over Spark's guess of a person. One world's places can come out ten
+   * times apart (a desk seen whole, people-sized, and a close-up of a mug, props-sized), and the hero with them.
+   */
+  heroSize: z.object({ like: z.string().min(1), times: z.number().positive().max(20) }).optional(),
   /** This place's own painting style over world.json's (style_set with scope place). */
   style: z.string().min(10).optional(),
 });

package/app/src/scene/critic.ts

@@ -43,7 +43,7 @@ Reply with JSON only: {"issues": [{"key": "...", "problem": "missing | wrong | f
   // The critic weighs the whole picture and lets a figure pass when the place's words name one ("a child floats
   // candle boats"); people are asked about on their own, as every one of them is a double or a stranger.
   // A drive's hero is painted at the wheel on purpose: no one is looked for there.
-  const people = place.kind === 'drive' ? [] : await paintedPeople(memo, place.key, painting);
+  const people = place.kind === 'drive' ? [] : await paintedPeople(memo, place.key, painting, castLooks(place));
   const near = (a: number[], b: number[]) => Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) < 120;
   const extra = people.filter((p) => !found.issues.some((i) => i.problem === 'unwanted' && near(i.region, p.box))).map((p) => ({
     key: 'person', problem: 'unwanted' as const, region: pad(p.box, 24),
@@ -52,6 +52,13 @@ Reply with JSON only: {"issues": [{"key": "...", "problem": "missing | wrong | f
   return { issues: [...found.issues, ...extra].slice(0, 6) };
 }
 
+/**
+ * How the place's NPCs look. A drawn world's NPC is often a thing (a steaming mug, a candle in a jar) that the place's
+ * words also name as part of the scene, so the painter paints it in and the critic, looking for people, lets it pass:
+ * the game then draws its figure beside the painted one, a double. They are looked for by their looks too.
+ */
+export const castLooks = (place: Place) => place.things.filter((t) => t.role === 'npc').map((t) => t.looks ?? t.key.replace(/-/g, ' '));
+
 const PERSON = /\b(child|children|kid|boy|girl|man|woman|men|women|person|people|figure|keeper|seller|vendor|fisherman|sailor|someone|crowd|silhouette)s?\b/i;
 
 /**
@@ -63,9 +70,12 @@ export const addsPerson = (i: { problem: string; fix: string }) => i.problem !==
 const People = z.object({ people: z.array(z.object({ what: z.string(), box: z.tuple([z.number(), z.number(), z.number(), z.number()]) })).max(6) });
 
 /** Every person or figure painted in, with a box: none belongs in a background, the game adds its people itself. */
-export async function paintedPeople(memo: Memo, key: string, painting: Buffer): Promise<Array<{ what: string; box: [number, number, number, number] }>> {
+export async function paintedPeople(memo: Memo, key: string, painting: Buffer, cast: string[] = []): Promise<Array<{ what: string; box: [number, number, number, number] }>> {
+  const others = cast.length
+    ? `\nAlso list each of these characters if it is painted in, however it is drawn (as an object, an animal or a creature, standing on or inside something else): ${cast.join('; ')}. The game draws them over the picture itself, so a painted one would be a double. Box only the character, not what it stands on.`
+    : '';
   const prompt = `This is a painted background (${FRAME.width}x${FRAME.height} px) for a 2D adventure. It must show no people at all.
-List every person or human figure painted in it: adults, children, sitting, crouching or far away, a silhouette in a window or a doorway. Not statues, scarecrows, posters or pictures of people.
+List every person or human figure painted in it: adults, children, sitting, crouching or far away, a silhouette in a window or a doorway. Not statues, scarecrows, posters or pictures of people.${others}
 For each give what it is in a few words ("a crouching child in a grey hoodie") and its box [x0, y0, x1, y1] in pixels, tight around the figure.
 Reply with JSON only: {"people": [{"what": "...", "box": [0, 0, 0, 0]}]}`;
   try {

package/app/src/scene/derive.ts

@@ -33,10 +33,15 @@ export type DeriveIn = { place: Place; layout: Layout; things: ThingIn[]; floors
    * Floor someone said is floor: brush strokes that add to a floor (the person's, the agent's, the free bridge's)
    * and floor cells the person added. It is walked on whatever thing's mask lies over it.
    */
-  said?: Mask };
+  said?: Mask;
+  /** How tall the hero stands (cast/figures.json), in metres; the scale is for a grown-up. Absent: a grown-up. */
+  heroMetres?: number;
+  /** The hero as tall as `times` this thing's painted height (corrections heroSize): sets the scale. */
+  heroSize?: { like: string; times: number } };
 export type Derived = { geometry: Geometry; grid: Grid; blobs: Blob[]; footprint: Mask; probes: Sample[]; shadows: Shadows };
 
 const { width: W, height: H } = FRAME;
+const round3 = (v: number) => Math.round(v * 1000) / 1000;
 /** The tallest the hero may be: three quarters of the picture. */
 export const NEAR_MAX_PX = Math.round(0.75 * H);
 /** How far (px) a layout light's point may lie outside the thing it belongs to: a glow drawn just off the lamp. */
@@ -362,14 +367,28 @@ export async function derive(memo: Memo, input: DeriveIn, log: (line: string) =>
     scale = { horizonY: Math.min(layout.horizon, topY - 40), pxPerY: 0.5, source: 'layout' };
     flag('scale: guessed from the layout horizon');
   }
+  // The person said how tall the hero is here, against a painted thing: the scale follows it (the horizon stays).
+  const heroMetres = input.heroMetres ?? PERSON_M;
+  const like = input.heroSize && things.find((t) => t.key === input.heroSize!.like);
+  const likeBox = like ? maskBox(like.mask) : undefined;
+  if (input.heroSize && !likeBox) flag(`hero size: no thing ${input.heroSize.like} with a mask here; the scale stays`);
+  if (input.heroSize && likeBox) {
+    const footY = likeBox[3];
+    const horizonY = scale.horizonY < footY - 20 ? scale.horizonY : Math.min(layout.horizon, footY - 40, topY - 40);
+    const personAt = (input.heroSize.times * (likeBox[3] - likeBox[1]) * PERSON_M) / heroMetres;
+    scale = { horizonY, pxPerY: round3(personAt / Math.max(1, footY - horizonY)), source: scale.source };
+    log(`scale from the hero's size: ${input.heroSize.times} x ${input.heroSize.like} (${Math.round((likeBox[3] - likeBox[1]) * input.heroSize.times)} px at y ${footY})`);
+  }
 
   // The frame gate: no standing where a good part of the hero would be outside the picture.
   const sized = scale;
+  // The gates are for the hero as tall as it is: a small one (a figurine among props) fits where a grown-up would not.
+  const heroShare = Math.min(1, heroMetres / PERSON_M);
   let framed = 0;
   grid.open.forEach((v, i) => {
     if (!v) return;
     const [x, y] = grid.centre(i);
-    const h = Math.max(8, sized.pxPerY * (y - sized.horizonY));
+    const h = Math.max(8, heroShare * sized.pxPerY * (y - sized.horizonY));
     if (x < 0.1 * h || x > W - 0.1 * h || y < 0.7 * h) {
       grid.open[i] = 0;
       shut[i] = 1;
@@ -378,7 +397,7 @@ export async function derive(memo: Memo, input: DeriveIn, log: (line: string) =>
   });
   // The near gate: in a close-up interior the front rows sit right under the camera, where the hero would be
   // taller than the picture (a bakery at 942 px). Those rows are foreground to look past, not floor to stand on.
-  const tooNear = [...grid.open.keys()].filter((i) => grid.open[i] && sized.pxPerY * (grid.centre(i)[1] - sized.horizonY) > NEAR_MAX_PX);
+  const tooNear = [...grid.open.keys()].filter((i) => grid.open[i] && heroShare * sized.pxPerY * (grid.centre(i)[1] - sized.horizonY) > NEAR_MAX_PX);
   if (tooNear.length && grid.count() - tooNear.length >= 200) {
     tooNear.forEach((i) => (grid.open[i] = 0, shut[i] = 1));
     framed += tooNear.length;

package/app/src/studio/agent.ts

@@ -5,7 +5,7 @@
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { antigravity, claude, codexLive, createAgentSession, detectAgents, museLive, type CodingAgent, withoutProviderCredentials, type AgentSession, type ApprovalDecision, type ApprovalRequest, type SessionState, type SessionTurn } from 'genaicode/agents';
+import { antigravity, claude, codexLive, createAgentSession, detectAgents, museLive, type CodingAgent, withoutProviderCredentials, type AgentSession, type ApprovalDecision, type ApprovalRequest, type SessionState, type SessionTurn, type AgentBudget, type RateLimit } from 'genaicode/agents';
 import { configDir, redact, withoutSecrets } from '../secrets.ts';
 import type { Events } from './events.ts';
 import { History } from './history.ts';
@@ -61,6 +61,22 @@ export function studioTool(request: ApprovalRequest): boolean {
  */
 export const shellTool = (name: string) => /(^|[/_.])(shell|bash|sh|exec|exec_command|repl|js)$/i.test(name);
 
+/** DIORAMA_AGENT_MAX_COST (dollars) and DIORAMA_AGENT_MAX_TOKENS cap each world's conversation; unset, nothing is capped. */
+export function agentBudget(env: NodeJS.ProcessEnv = process.env): AgentBudget | undefined {
+  const cost = Number(env.DIORAMA_AGENT_MAX_COST);
+  const tokens = Number(env.DIORAMA_AGENT_MAX_TOKENS);
+  const budget: AgentBudget = { ...(cost > 0 && { maxCostUsd: cost }), ...(tokens > 0 && { maxTokens: Math.floor(tokens) }) };
+  return Object.keys(budget).length ? budget : undefined;
+}
+
+/** An agent's plan limit close to running out or used up, in words for the feed; null while it is fine. */
+export function limitText(limit: RateLimit): string | null {
+  if (limit.status === 'ok') return null;
+  const used = limit.usedPercent === undefined ? '' : ` (${Math.round(limit.usedPercent)}% used)`;
+  const resets = limit.resetsAt === undefined ? '' : `, resets ${new Date(limit.resetsAt).toLocaleString()}`;
+  return `${limit.name ? `${limit.name} ` : ''}${limit.window} limit ${limit.status === 'exceeded' ? 'reached' : 'nearly used up'}${used}${resets}`;
+}
+
 /** Turns a session snapshot into what the page may see: secrets blanked. */
 const safe = (state: SessionState): SessionState => JSON.parse(redact(JSON.stringify(state))) as SessionState;
 
@@ -109,6 +125,8 @@ class Talk {
   /** Tools announced already: a running tool is announced when it starts and must not be again once it settles. */
   private tools = new Set<string>();
   private ended = new Set<number>();
+  /** Plan limits announced already, by limit and state, so a warning shows once. */
+  private limits = new Set<string>();
 
   /**
    * The Studio's tools as the Studio saw them called (arguments, outcome). Some agents report a tool call by
@@ -214,6 +232,13 @@ class Talk {
 
   /** The feed (Activity, the terminal) gets the gist: what was said, each tool, refusals, how a turn ended. */
   private announce(state: SessionState) {
+    for (const limit of state.rateLimits ?? []) {
+      const key = `${limit.name ?? ''}/${limit.window}/${limit.status}`;
+      const text = limitText(limit);
+      if (!text || this.limits.has(key)) continue;
+      this.limits.add(key);
+      this.publish('limit', { text });
+    }
     for (const turn of state.turns) {
       if (!this.seen.has(turn.id)) {
         this.seen.set(turn.id, 0);
@@ -416,6 +441,7 @@ export class AgentHub {
       agent,
       cwd,
       model: agentModel(name),
+      budget: agentBudget(),
       task: {
         env: withoutProviderCredentials(withoutSecrets(process.env)) as Record<string, string>,
         // genaicode hands the server to Muse as -c overrides, the token through an environment variable, never argv.

package/app/studio/agent.tsx

@@ -1,6 +1,6 @@
 // The Muse Code panel: genaicode's own chat (genaicode/react), fed the session state the Studio server keeps
 // for this world. The page holds no agent and no key: it sends what the person types and answers approvals.
-import { AgentChat, type ChatNotice, type SessionState, type SessionTurn } from 'genaicode/react';
+import { AgentChat, limitChips, type ChatNotice, type SessionState, type SessionTurn } from 'genaicode/react';
 import type { ComponentChildren } from 'preact';
 import { useEffect, useRef, useState } from 'preact/hooks';
 import { call, fileUrl, token } from './api.ts';
@@ -309,6 +309,8 @@ export function AgentPanel({ slug, replay, speed = 1, jobs = [], notices, afterT
               </select>
             )}
             <span class="grow" />
+            {/* The agent's plan limits and the conversation's budget, once near their end or reported. */}
+            {!replay && state && limitChips(state).map((chip) => <span key={chip.key} class="gc-chip gc-limit" data-level={chip.level} title={chip.title}>{chip.text}</span>)}
             {replay
               ? <span class="live on">{replayDone ? 'replay done' : 'replay'}</span>
               : <span class={`live ${live ? 'on' : ''}`}>{running ? 'working…' : live ? 'ready' : 'reconnecting'}</span>}

package/app/web/main.ts

@@ -2935,9 +2935,15 @@ class Game {
     const img = c.getImageData(0, 0, w, h);
     const d = img.data;
     const ramp = (v: number, a: number, b: number) => Math.max(0, Math.min(1, (v - a) / (b - a)));
+    // Only the flame's own pixels: near white-hot and strongly warm. Wood or paper lit warm by it (a letter by a
+    // candle) passed a looser test, and the whole box flared over them as a bright square. Faded to nothing at
+    // the box's edge, so what still passes never ends on a straight line.
     for (let i = 0; i < d.length; i += 4) {
       const luma = 0.3 * d[i] + 0.59 * d[i + 1] + 0.11 * d[i + 2];
-      d[i + 3] = Math.round(255 * ramp(luma, 140, 215) * ramp(d[i] - d[i + 2], 40, 100));
+      const k = i / 4;
+      const [u, v] = [((k % w) + 0.5) / w * 2 - 1, (Math.floor(k / w) + 0.5) / h * 2 - 1];
+      const edge = Math.max(0, 1 - (u * u + v * v)) ** 0.5;
+      d[i + 3] = Math.round(255 * ramp(luma, 170, 235) * ramp(d[i] - d[i + 2], 70, 130) * edge);
     }
     c.putImageData(img, 0, 0);
     return { canvas, x0, y0 };

package/docs/studio.md

@@ -34,7 +34,7 @@ The agent can use `job_inspect` to see a job's timestamped recent activity, how
 
 Every fix is kept in a file next to what it fixes and applied again by every later build, so a rebuild never loses it: `places/<place>/corrections.json` (rebuilding only that place from the step it feeds), `story-fixes.json`, `cast/fixes.json`. A place's thing list is edited the same way: Remove takes a prop off it (kept in the picture, or painted out with one Muse edit) and Add makes something painted a thing of its own (`removed` and `added` in `corrections.json`, which every step reads with world.json); exits, items and people belong to the story. A small repaint rebuilds only what it reaches (`app/src/scene/carry.ts`): each place step keeps the painting it last ran on (`places/<place>/.ran/`), compares the new one with it tile by tile, and asks again only about what the changed tiles reach (a thing's or floor's mask, a plate, the backdrop's cards, the light, the stairs); everything else is asked about the old painting, which the memo answers for nothing, and the place keeps its scale. Lighting the lanterns of a harbour takes about 100 s instead of 270 s, and a rebuild on the same painting asks nothing new. A change over a third of the painting rebuilds everything. A place whose steps have not kept their painting (built before this, or put back by an Undo) takes the painting on disk as theirs before a repaint, so that repaint carries too. **History** lists the jobs the world went through, the agent's included, each with who ran it, when and which places it changed, and puts the world back as it was before any of them (Redo takes that back right after); a locked world or place is left alone by the agent.
 
-The conversation is genaicode's chat with Muse Code (default), Claude Code or Codex, picked in its header before the first message (Setup's **Default agent**, or a pick here, is remembered in `~/.config/diorama/studio.json` for new worlds; a world keeps the agent it last talked with, and `DIORAMA_AGENT=codex` overrides both; `DIORAMA_AGY_MODEL=gemini-4-argon-high`, `DIORAMA_CODEX_MODEL`, `DIORAMA_MUSE_MODEL`, `DIORAMA_AGENT_CLAUDE_MODEL` or `DIORAMA_AGENT_MODEL` picks the agent's model); after it, "Hand over…" passes the conversation to another agent and a line marks where it changed hands. After a Studio restart the earlier turns come back on screen from `studio/sessions/`. The conversation is also kept in words in `studio/conversation.md`: a new agent session (another agent, or after the Studio restarts) is told to read it first, so nothing agreed is lost. The agent works through the same actions as the page, so its steps show live and its changes survive rebuilds; when a build leaves places unplayable it is woken to repair them, three tries a place. Every conversation is recorded in `studio/sessions/`: open one from "Recorded sessions", or `/w/<slug>?replay=<file>&speed=2`, to play it back for a film.
+The conversation is genaicode's chat with Muse Code (default), Claude Code or Codex, picked in its header before the first message (Setup's **Default agent**, or a pick here, is remembered in `~/.config/diorama/studio.json` for new worlds; a world keeps the agent it last talked with, and `DIORAMA_AGENT=codex` overrides both; `DIORAMA_AGY_MODEL=gemini-4-argon-high`, `DIORAMA_CODEX_MODEL`, `DIORAMA_MUSE_MODEL`, `DIORAMA_AGENT_CLAUDE_MODEL` or `DIORAMA_AGENT_MODEL` picks the agent's model); after it, "Hand over…" passes the conversation to another agent and a line marks where it changed hands. After a Studio restart the earlier turns come back on screen from `studio/sessions/`. The conversation is also kept in words in `studio/conversation.md`: a new agent session (another agent, or after the Studio restarts) is told to read it first, so nothing agreed is lost. The agent works through the same actions as the page, so its steps show live and its changes survive rebuilds; when a build leaves places unplayable it is woken to repair them, three tries a place. When the agent reports its plan limits (Claude Code's 5-hour and weekly limits, Codex's), the header shows how much is used and when it resets once a limit is near its end, and the terminal says so once. `DIORAMA_AGENT_MAX_COST` (dollars) and `DIORAMA_AGENT_MAX_TOKENS` cap what one world's conversation may spend: the header shows the budget, warns at 80%, and once it is used up a new message does not start. Every conversation is recorded in `studio/sessions/`: open one from "Recorded sessions", or `/w/<slug>?replay=<file>&speed=2`, to play it back for a film.
 
 **Setup** shows what this machine still needs, which agents it found, and the model calls sent across all worlds, priced once you enter the per-call prices from your billing pages. Keys are only ever typed in the terminal (`diorama setup`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtanczyk/diorama",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Turn a story prompt into playable painted point-and-click scenes with Meta Muse and SAM 3.1",
   "license": "Apache-2.0",
   "repository": {
@@ -54,7 +54,7 @@
     "@meta-sam/parser": "^0.1.0",
     "@preact/signals": "^2.11.3",
     "esbuild": "^0.25.0",
-    "genaicode": "^2.28.1",
+    "genaicode": "^2.29.0",
     "onnxruntime-web": "^1.31.1",
     "playwright": "^1.63.0",
     "preact": "^10.29.8",