Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

feat(kiln): animation parity across categories — not just characters

Matt Kissingerd15149410de2
diff --git a/__tests__/prompt.test.ts b/__tests__/prompt.test.ts
index a53ac55d..7ff8ca84 100644
--- a/__tests__/prompt.test.ts
+++ b/__tests__/prompt.test.ts
@@ -18,6 +18,9 @@ import {
KILN_BOTH_SYSTEM_PROMPT,
KILN_REFINE_DIRECTIVE,
ARCHITECTURE_CONTEXT,
+ PROP_CONTEXT,
+ ENVIRONMENT_CONTEXT,
+ VFX_CONTEXT,
KILN_API_SECTION,
KILN_API_SECTION_UNIFIED,
KILN_VISUAL_QA_UNIFIED,
@@ -125,6 +128,30 @@ describe('buildUserPrompt', () => {
expect(prompt).not.toContain(ARCHITECTURE_CONTEXT);
});
+ test('appends the per-category rig context for prop / environment / vfx', () => {
+ const prop = buildUserPrompt({ prompt: 'a treasure chest', mode: 'glb', category: 'prop' });
+ expect(prop).toContain(PROP_CONTEXT);
+ expect(prop.indexOf('## Task')).toBeLessThan(prop.indexOf(PROP_CONTEXT));
+ const env = buildUserPrompt({ prompt: 'a palm frond', mode: 'glb', category: 'environment' });
+ expect(env).toContain(ENVIRONMENT_CONTEXT);
+ const vfx = buildUserPrompt({ prompt: 'a magic pulse ring', mode: 'glb', category: 'vfx' });
+ expect(vfx).toContain(VFX_CONTEXT);
+ // Each category gets only its own block, never another's.
+ expect(prop).not.toContain(VFX_CONTEXT);
+ expect(env).not.toContain(PROP_CONTEXT);
+ });
+
+ test('per-category rig context is dropped when refining (existingCode set)', () => {
+ const prompt = buildUserPrompt({
+ prompt: 'open the lid',
+ mode: 'glb',
+ category: 'prop',
+ existingCode: 'function build() { return createRoot("Chest"); }',
+ });
+ expect(prompt).not.toContain(PROP_CONTEXT);
+ expect(prompt).toContain('## Edit Request');
+ });
+
test('does not append the architecture directive when refining (existingCode set)', () => {
const prompt = buildUserPrompt({
prompt: 'add a second floor',
diff --git a/prompt.ts b/prompt.ts
index 431e13b6..a5c6b111 100644
--- a/prompt.ts
+++ b/prompt.ts
@@ -837,14 +837,44 @@ export const ARCHITECTURE_CONTEXT =
'you could pass through, and any built-in fixtures rest on the floor. Fix anything sealed, buried, ' +
'or floating, then view the interior again.';
+/** PROP build context — make movable parts distinct and correctly hinged so they
+ * read well statically AND can be animated about their real pivot. */
+export const PROP_CONTEXT =
+ 'This is a PROP. Build any part that can move — a lid, door, drawer, hatch, wheel, gear, lever, ' +
+ 'handle, or hinge — as its OWN distinct piece seated at its real hinge or axle, never fused into the ' +
+ 'body. A chest or box lid hinges along its BACK TOP edge; a door swings on its side jamb; a wheel or ' +
+ 'gear turns on its axle; a lever or handle pivots at its base. If you animate it, put a createPivot ' +
+ 'exactly at that hinge or axle line, parent only the moving mesh under the joint, and leave the static ' +
+ 'body unpivoted so just the part moves — not the whole object.';
+
+/** ENVIRONMENT build context — sway-prone pieces as separate, base-anchored parts. */
+export const ENVIRONMENT_CONTEXT =
+ 'This is an ENVIRONMENT element. Build sway-prone or moving pieces — foliage, fronds, grass tufts, ' +
+ 'branches, flags, banners, vines, or water — as separate parts anchored at their base. If you animate ' +
+ 'them, pivot at the base or anchor (a flag at its mast edge, a frond at its stalk, grass at the ground) ' +
+ 'with a gentle, looping sway; when several elements move, offset their phase so they do not all swing ' +
+ 'in lockstep.';
+
+/** VFX build context — emitter-like parts driven by transform on Joint_ pivots. */
+export const VFX_CONTEXT =
+ 'This is a VFX / effect asset. Build the moving or emitting elements — pulses, rings, sparks, swirls, ' +
+ 'beams, or shards — as distinct parts. If you animate them, drive the motion through Joint_ pivots ' +
+ '(spin, orbit, pulse, or scale) about a sensible center, and keep every loop seamless (the end pose ' +
+ 'matches the start) so it reads as a continuous effect.';
+
/**
* Per-category context appended to fresh-generation prompts by
- * {@link buildUserPrompt}. Intentionally sparse: only categories whose guidance
- * is owned by core live here (today just `architecture`, because its primitives
- * are core helpers). `character` deliberately stays studio-side.
+ * {@link buildUserPrompt}. Core owns every category whose guidance reaches all
+ * consumers (CLI / batch / bench / editor / the deployed runtime) — `architecture`
+ * (its primitives are core helpers) plus `prop` / `vfx` / `environment` (their
+ * moving-part rig guidance). `character` deliberately stays studio-side (the studio
+ * prepends CHARACTER_CONTEXT into the prompt string before the wire).
*/
export const CATEGORY_CONTEXT: Partial<Record<AssetCategory, string>> = {
architecture: ARCHITECTURE_CONTEXT,
+ prop: PROP_CONTEXT,
+ environment: ENVIRONMENT_CONTEXT,
+ vfx: VFX_CONTEXT,
};
export function buildUserPrompt(request: KilnGenerateRequest): string {
diff --git a/tools/registry.ts b/tools/registry.ts
index 04dcba07..cbc95870 100644
--- a/tools/registry.ts
+++ b/tools/registry.ts
@@ -497,13 +497,16 @@ export const kilnScreenshotAnimationDef: KilnToolDef = {
name: 'kiln_screenshot_animation',
description:
'SEE one animation clip move: renders the named clip as six frames sampled evenly from start to end ' +
- '(each labeled with its phase %) from one camera, as a 3x2 grid. Use this after building an animated ' +
- 'character to verify the MOTION — a static screenshot cannot show it. Read the side (right) view to ' +
- 'check that a walk swings the legs forward and back (not splayed sideways and not sliding the body ' +
- 'sideways), that knees bend backward at the joint (not forward like a bird), that an attack swings ' +
- 'down and FORWARD through the front (not behind the back), and that a held weapon tracks the hand ' +
- 'through the swing. args: clip (required, the clip name), camera (default right; also front/back/left/' +
- 'top/three-quarter), perFrame (optional, separate high-res frames). If unresolvedTracks comes back ' +
+ '(each labeled with its phase %) from one camera, as a 3x2 grid. Use this after animating ANY asset to ' +
+ 'verify the MOTION — a static screenshot cannot show it — whether it is a character walking, a door or ' +
+ 'chest lid swinging on its hinge, a wheel/gear/turret/windmill turning on its axle, a lever or hatch ' +
+ 'throwing, or a flag/frond/branch swaying. Read the side (right) view and confirm each moving part ' +
+ 'travels the way it should about its OWN real pivot, and that the static base stays put. For a ' +
+ 'character specifically: a walk swings the legs forward and back (not splayed sideways and not sliding ' +
+ 'the body sideways), knees bend backward at the joint (not forward like a bird), an attack swings down ' +
+ 'and FORWARD through the front (not behind the back), and a held weapon tracks the hand through the ' +
+ 'swing. args: clip (required, the clip name), camera (default right; also front/back/left/top/' +
+ 'three-quarter), perFrame (optional, separate high-res frames). If unresolvedTracks comes back ' +
'non-empty the clip targets joints that do not exist (a name mismatch) and looks frozen — fix the ' +
'track names. Flat-shaded CPU render; writes no files.',
inputSchema: screenshotAnimationInput,