@volter/game-editor 0.5.82 → 0.5.83

package/dist/assets/{xstate-animation-binding-Dionc_fC.js → xstate-animation-binding-Bhz1Uhhw.js}

@@ -1 +1 @@
-import{collectMachineAnimationMeta as V,clipNamesOf as L,isBlendTreeAnimationMeta as S,asBlendTreeDef as z}from"./xstate-animation-meta-XEmD_qc_.js";import{cW as J,p as Z,c as _,cQ as ee,l as te,dk as ne,cf as ie,cd as oe}from"./three.core-3arARmh6.js";import"./index-V4J7xfRg.js";import"./index-nmcBqr7Y.js";import"./_commonjsHelpers-D6-XlEtG.js";import"./index-D_NuPfjr.js";import"./jsx-runtime-DPjLkJKQ.js";import"./index-CtzuWnCS.js";import"./index-CinJrH5C.js";import"./index-FUuS4qwW.js";import"./client-DNXj_opT.js";class M extends Error{constructor(i,c){super(i),this.stateId=c,this.name="AnimationBindingError"}}function ae(n){const i=n.logic;if(i?.root)return i;const c=n.getSnapshot();if(c?.machine?.root)return c.machine;throw new M("[bindXStateAnimation] the actor exposes no state machine — only a state-machine actor carries the `meta.animation` this binder reads")}const W=n=>n.layer??"base",B=n=>n.weight??1,I=n=>n.blendMode??"override";function T(n){try{return ne.parseTrackName(n.name).nodeName??""}catch{const i=n.name.indexOf(".");return i<0?n.name:n.name.slice(0,i)}}function C(n,i,c){const o=new Set,l=[];for(const f of i){let u=!1;n.traverse(m=>{m.name===f&&(u=!0,m.traverse(d=>{d.name&&o.add(d.name)}))}),c.has(f)&&(u=!0,o.add(f)),u||l.push(f)}return{names:o,missing:l}}function se(n,i,c,o){const l=new Set(n.tracks.map(T)),f=i.include?C(c,i.include,l):void 0,u=i.exclude?C(c,i.exclude,l):void 0,m=[...f?.missing??[],...u?.missing??[]];if(m.length)throw new M(`[bindXStateAnimation] state "${o}" boneMask names unknown bones/objects: ${m.join(", ")}`,o);const d=n.tracks.filter(p=>{const w=T(p);return(!f||f.names.has(w))&&!u?.names.has(w)});if(d.length===0)throw new M(`[bindXStateAnimation] state "${o}" boneMask removes every track from clip "${n.name}"`,o);return new te(n.name,n.duration,d.map(p=>p.clone()))}function re(n){return n.reduce((i,c)=>c.weight>i.weight?c:i,n[0])}function Se(n,i,c,o={}){const l=i.getRoot(),f=o.root??(l instanceof J?l:void 0);if(!f)throw new M("[bindXStateAnimation] a THREE.Object3D `root` option is required when the mixer uses AnimationObjectGroup");const u=ae(n).root,m=V(u),d=new Map(m.map(t=>[t.stateId,t.meta]));for(const t of m)for(const e of L(t.meta))if(!c.has(e))throw new M(`[bindXStateAnimation] state "${t.stateId}" references clip "${e}", which is not present in the supplied clips map. Known clips: ${[...c.keys()].join(", ")||"(none)"}`,t.stateId);const p=new Map;function w(t,e,s){return W(e)!=="base"||!!e.boneMask||I(e)==="additive"?`${t}\0${s}`:s}for(const{stateId:t,meta:e}of m)for(const s of L(e)){const a=w(t,e,s);if(p.has(a))continue;const r=c.get(s);let h=e.boneMask?se(r,e.boneMask,f,t):r;(h!==r||a!==s)&&(h===r&&(h=r.clone()),h.name=`${r.name}@${W(e)}:${t}`),I(e)==="additive"?(Z.makeClipAdditive(h),h.blendMode=_):h.blendMode=ee,p.set(a,h)}const g=new Map;function K(t,e,s,a){let r=g.get(t);if(!r){const h=p.get(t);if(!h)throw new M(`[bindXStateAnimation] prepared clip "${t}" not found`);const v=i.clipAction(h);v.setEffectiveWeight(0),v.play(),r={action:v,clip:h},g.set(t,r)}return r.action.setLoop(e?ie:oe,1/0),r.action.clampWhenFinished=!e,r.action.timeScale=s,r.action.weight=a,r.action}function N(t){const e=o.selectParameters?o.selectParameters(t):t;return new Map(Object.entries(e??{}))}function D(t,e,s){return(S(e)?ce(z(e.blendTree),N(s)):[{clip:e.clip,weight:1}]).map(({clip:r,weight:h})=>({clip:r,weight:h,actionKey:w(t,e,r)}))}const y=new Map;let O=!1;function R(t,e,s){for(const a of t){if(a.actionKey===e)continue;const r=g.get(a.actionKey)?.action;r&&(s>0?r.fadeOut(s):r.setEffectiveWeight(0))}}function k(t,e){if(!S(t.meta))return;t.natural=D(t.stateId,t.meta,e);const s=B(t.meta);for(const a of t.natural)g.get(a.actionKey)?.action.setEffectiveWeight(a.weight*s)}function P(t,e,s){const a=W(e),r=y.get(a)??null,h=D(t,e,s),v=re(h),H=S(e)?!0:e.loop,Q=S(e)?1:e.speed,x=B(e);for(const b of h)K(b.actionKey,H,Q,x);const $=g.get(v.actionKey).action;$.reset().setEffectiveWeight(x);for(const b of h)b.actionKey!==v.actionKey&&g.get(b.actionKey).action.reset().setEffectiveWeight(0);const A=e.crossfade?.duration??0,U=e.crossfade?.warp??!1;if(!r)A>0&&$.fadeIn(A);else{R(r.natural,r.dominantActionKey,A);const b=g.get(r.dominantActionKey)?.action;b&&A>0?b.crossFadeTo($,A,U):(b?.setEffectiveWeight(0),$.setEffectiveWeight(x))}const j={layer:a,stateId:t,meta:e,natural:h,dominantActionKey:v.actionKey,crossfadeRemaining:A};y.set(a,j),S(e)&&A<=0&&k(j,s)}function q(t){return Object.keys(t.getMeta()).filter(e=>d.has(e))}function X(t){const e=new Map;for(const s of q(t)){const a=d.get(s),r=W(a),h=e.get(r);if(h)throw new M(`[bindXStateAnimation] animated states "${h}" and "${s}" are both active on layer "${r}". Give parallel regions distinct meta.animation.layer names.`,s);e.set(r,s)}for(const[s,a]of y)e.has(s)||(R(a.natural,void 0,0),y.delete(s));for(const[s,a]of e)y.get(s)?.stateId!==a&&P(a,d.get(a),t.context)}const F=n.getSnapshot();X(F);const G=n.subscribe(t=>{O||X(t)});function E(t){if(O)return;const e=t,s=n.getSnapshot().context;for(const a of y.values())a.crossfadeRemaining>0?(a.crossfadeRemaining=Math.max(0,a.crossfadeRemaining-e),a.crossfadeRemaining<=0&&k(a,s)):k(a,s);i.update(e)}const Y={tick:E,actor:n,getParameters:()=>N(n.getSnapshot().context),getActiveLayers:()=>[...y.values()].map(t=>({layer:t.layer,stateId:t.stateId,clips:t.natural.map(e=>e.clip),clipWeights:t.natural.map(e=>({clip:e.clip,weight:g.get(e.actionKey)?.action.getEffectiveWeight()??0})),weight:B(t.meta),blendMode:I(t.meta),...t.meta.boneMask?{boneMask:t.meta.boneMask}:{}})),dispose(){if(!O){O=!0,o.systems?.remove("animation",E),G.unsubscribe();for(const{action:t,clip:e}of g.values())t.stop(),i.uncacheAction(e,t.getRoot());g.clear(),y.clear()}}};return o.systems?.add("animation",E),Y}function ce(n,i){switch(n.type){case"1D":return le(n,i);case"2D":return fe(n,i);case"direct":return de(n);default:return n.children.map(c=>({clip:c.clip,weight:1/n.children.length}))}}function le(n,i){const c=Number(i.get(n.parameter)??0),o=[...n.children].sort((f,u)=>f.threshold-u.threshold),l=o.map(f=>({clip:f.clip,weight:0}));if(o.length===0)return l;if(o.length===1||c<=o[0].threshold)return l[0].weight=1,l;if(c>=o[o.length-1].threshold)return l[l.length-1].weight=1,l;for(let f=0;f<o.length-1;f++){const u=o[f],m=o[f+1];if(c>=u.threshold&&c<=m.threshold){const d=m.threshold-u.threshold,p=d>0?(c-u.threshold)/d:0;return l[f].weight=1-p,l[f+1].weight=p,l}}return l}function fe(n,i){const c=Number(i.get(n.parameter)??0),o=Number(i.get(n.parameterY??"")??0),l=n.children,f=l.map(d=>({clip:d.clip,weight:0}));let u=0;const m=[];for(const d of l){const p=c-d.threshold,w=o-(d.thresholdY??0),g=Math.sqrt(p*p+w*w),K=g<.001?1e3:1/g;m.push(K),u+=K}if(u>0)for(let d=0;d<f.length;d++)f[d].weight=m[d]/u;return f}function de(n){const i=n.children.map(o=>({clip:o.clip,weight:o.weight??0})),c=i.reduce((o,l)=>o+l.weight,0);if(c>0)for(const o of i)o.weight/=c;return i}export{M as AnimationBindingError,Se as bindXStateAnimation,ce as evaluateBlendTree,ae as machineOfXStateActor};
+import{collectMachineAnimationMeta as V,clipNamesOf as L,isBlendTreeAnimationMeta as S,asBlendTreeDef as z}from"./xstate-animation-meta-CvDlYgrt.js";import{cW as J,p as Z,c as _,cQ as ee,l as te,dk as ne,cf as ie,cd as oe}from"./three.core-3arARmh6.js";import"./index-C5tasxXb.js";import"./index-nmcBqr7Y.js";import"./_commonjsHelpers-D6-XlEtG.js";import"./index-D_NuPfjr.js";import"./jsx-runtime-DPjLkJKQ.js";import"./index-CtzuWnCS.js";import"./index-CinJrH5C.js";import"./index-FUuS4qwW.js";import"./client-DNXj_opT.js";class M extends Error{constructor(i,c){super(i),this.stateId=c,this.name="AnimationBindingError"}}function ae(n){const i=n.logic;if(i?.root)return i;const c=n.getSnapshot();if(c?.machine?.root)return c.machine;throw new M("[bindXStateAnimation] the actor exposes no state machine — only a state-machine actor carries the `meta.animation` this binder reads")}const W=n=>n.layer??"base",B=n=>n.weight??1,I=n=>n.blendMode??"override";function T(n){try{return ne.parseTrackName(n.name).nodeName??""}catch{const i=n.name.indexOf(".");return i<0?n.name:n.name.slice(0,i)}}function C(n,i,c){const o=new Set,l=[];for(const f of i){let u=!1;n.traverse(m=>{m.name===f&&(u=!0,m.traverse(d=>{d.name&&o.add(d.name)}))}),c.has(f)&&(u=!0,o.add(f)),u||l.push(f)}return{names:o,missing:l}}function se(n,i,c,o){const l=new Set(n.tracks.map(T)),f=i.include?C(c,i.include,l):void 0,u=i.exclude?C(c,i.exclude,l):void 0,m=[...f?.missing??[],...u?.missing??[]];if(m.length)throw new M(`[bindXStateAnimation] state "${o}" boneMask names unknown bones/objects: ${m.join(", ")}`,o);const d=n.tracks.filter(p=>{const w=T(p);return(!f||f.names.has(w))&&!u?.names.has(w)});if(d.length===0)throw new M(`[bindXStateAnimation] state "${o}" boneMask removes every track from clip "${n.name}"`,o);return new te(n.name,n.duration,d.map(p=>p.clone()))}function re(n){return n.reduce((i,c)=>c.weight>i.weight?c:i,n[0])}function Se(n,i,c,o={}){const l=i.getRoot(),f=o.root??(l instanceof J?l:void 0);if(!f)throw new M("[bindXStateAnimation] a THREE.Object3D `root` option is required when the mixer uses AnimationObjectGroup");const u=ae(n).root,m=V(u),d=new Map(m.map(t=>[t.stateId,t.meta]));for(const t of m)for(const e of L(t.meta))if(!c.has(e))throw new M(`[bindXStateAnimation] state "${t.stateId}" references clip "${e}", which is not present in the supplied clips map. Known clips: ${[...c.keys()].join(", ")||"(none)"}`,t.stateId);const p=new Map;function w(t,e,s){return W(e)!=="base"||!!e.boneMask||I(e)==="additive"?`${t}\0${s}`:s}for(const{stateId:t,meta:e}of m)for(const s of L(e)){const a=w(t,e,s);if(p.has(a))continue;const r=c.get(s);let h=e.boneMask?se(r,e.boneMask,f,t):r;(h!==r||a!==s)&&(h===r&&(h=r.clone()),h.name=`${r.name}@${W(e)}:${t}`),I(e)==="additive"?(Z.makeClipAdditive(h),h.blendMode=_):h.blendMode=ee,p.set(a,h)}const g=new Map;function K(t,e,s,a){let r=g.get(t);if(!r){const h=p.get(t);if(!h)throw new M(`[bindXStateAnimation] prepared clip "${t}" not found`);const v=i.clipAction(h);v.setEffectiveWeight(0),v.play(),r={action:v,clip:h},g.set(t,r)}return r.action.setLoop(e?ie:oe,1/0),r.action.clampWhenFinished=!e,r.action.timeScale=s,r.action.weight=a,r.action}function N(t){const e=o.selectParameters?o.selectParameters(t):t;return new Map(Object.entries(e??{}))}function D(t,e,s){return(S(e)?ce(z(e.blendTree),N(s)):[{clip:e.clip,weight:1}]).map(({clip:r,weight:h})=>({clip:r,weight:h,actionKey:w(t,e,r)}))}const y=new Map;let O=!1;function R(t,e,s){for(const a of t){if(a.actionKey===e)continue;const r=g.get(a.actionKey)?.action;r&&(s>0?r.fadeOut(s):r.setEffectiveWeight(0))}}function k(t,e){if(!S(t.meta))return;t.natural=D(t.stateId,t.meta,e);const s=B(t.meta);for(const a of t.natural)g.get(a.actionKey)?.action.setEffectiveWeight(a.weight*s)}function P(t,e,s){const a=W(e),r=y.get(a)??null,h=D(t,e,s),v=re(h),H=S(e)?!0:e.loop,Q=S(e)?1:e.speed,x=B(e);for(const b of h)K(b.actionKey,H,Q,x);const $=g.get(v.actionKey).action;$.reset().setEffectiveWeight(x);for(const b of h)b.actionKey!==v.actionKey&&g.get(b.actionKey).action.reset().setEffectiveWeight(0);const A=e.crossfade?.duration??0,U=e.crossfade?.warp??!1;if(!r)A>0&&$.fadeIn(A);else{R(r.natural,r.dominantActionKey,A);const b=g.get(r.dominantActionKey)?.action;b&&A>0?b.crossFadeTo($,A,U):(b?.setEffectiveWeight(0),$.setEffectiveWeight(x))}const j={layer:a,stateId:t,meta:e,natural:h,dominantActionKey:v.actionKey,crossfadeRemaining:A};y.set(a,j),S(e)&&A<=0&&k(j,s)}function q(t){return Object.keys(t.getMeta()).filter(e=>d.has(e))}function X(t){const e=new Map;for(const s of q(t)){const a=d.get(s),r=W(a),h=e.get(r);if(h)throw new M(`[bindXStateAnimation] animated states "${h}" and "${s}" are both active on layer "${r}". Give parallel regions distinct meta.animation.layer names.`,s);e.set(r,s)}for(const[s,a]of y)e.has(s)||(R(a.natural,void 0,0),y.delete(s));for(const[s,a]of e)y.get(s)?.stateId!==a&&P(a,d.get(a),t.context)}const F=n.getSnapshot();X(F);const G=n.subscribe(t=>{O||X(t)});function E(t){if(O)return;const e=t,s=n.getSnapshot().context;for(const a of y.values())a.crossfadeRemaining>0?(a.crossfadeRemaining=Math.max(0,a.crossfadeRemaining-e),a.crossfadeRemaining<=0&&k(a,s)):k(a,s);i.update(e)}const Y={tick:E,actor:n,getParameters:()=>N(n.getSnapshot().context),getActiveLayers:()=>[...y.values()].map(t=>({layer:t.layer,stateId:t.stateId,clips:t.natural.map(e=>e.clip),clipWeights:t.natural.map(e=>({clip:e.clip,weight:g.get(e.actionKey)?.action.getEffectiveWeight()??0})),weight:B(t.meta),blendMode:I(t.meta),...t.meta.boneMask?{boneMask:t.meta.boneMask}:{}})),dispose(){if(!O){O=!0,o.systems?.remove("animation",E),G.unsubscribe();for(const{action:t,clip:e}of g.values())t.stop(),i.uncacheAction(e,t.getRoot());g.clear(),y.clear()}}};return o.systems?.add("animation",E),Y}function ce(n,i){switch(n.type){case"1D":return le(n,i);case"2D":return fe(n,i);case"direct":return de(n);default:return n.children.map(c=>({clip:c.clip,weight:1/n.children.length}))}}function le(n,i){const c=Number(i.get(n.parameter)??0),o=[...n.children].sort((f,u)=>f.threshold-u.threshold),l=o.map(f=>({clip:f.clip,weight:0}));if(o.length===0)return l;if(o.length===1||c<=o[0].threshold)return l[0].weight=1,l;if(c>=o[o.length-1].threshold)return l[l.length-1].weight=1,l;for(let f=0;f<o.length-1;f++){const u=o[f],m=o[f+1];if(c>=u.threshold&&c<=m.threshold){const d=m.threshold-u.threshold,p=d>0?(c-u.threshold)/d:0;return l[f].weight=1-p,l[f+1].weight=p,l}}return l}function fe(n,i){const c=Number(i.get(n.parameter)??0),o=Number(i.get(n.parameterY??"")??0),l=n.children,f=l.map(d=>({clip:d.clip,weight:0}));let u=0;const m=[];for(const d of l){const p=c-d.threshold,w=o-(d.thresholdY??0),g=Math.sqrt(p*p+w*w),K=g<.001?1e3:1/g;m.push(K),u+=K}if(u>0)for(let d=0;d<f.length;d++)f[d].weight=m[d]/u;return f}function de(n){const i=n.children.map(o=>({clip:o.clip,weight:o.weight??0})),c=i.reduce((o,l)=>o+l.weight,0);if(c>0)for(const o of i)o.weight/=c;return i}export{M as AnimationBindingError,Se as bindXStateAnimation,ce as evaluateBlendTree,ae as machineOfXStateActor};

package/dist/assets/{xstate-animation-meta-XEmD_qc_.js → xstate-animation-meta-CvDlYgrt.js}

@@ -1 +1 @@
-import{dY as b,dZ as u,t as o,u as c,v as n,w as l,c5 as r,c4 as m,c3 as f}from"./index-V4J7xfRg.js";import"./index-nmcBqr7Y.js";import"./_commonjsHelpers-D6-XlEtG.js";import"./index-D_NuPfjr.js";import"./jsx-runtime-DPjLkJKQ.js";import"./index-CtzuWnCS.js";import"./index-CinJrH5C.js";import"./index-FUuS4qwW.js";import"./client-DNXj_opT.js";const d=o({clip:n().min(1).describe("Animation clip name this child plays"),threshold:r().describe("1D/2D blend position on the primary parameter axis"),thresholdY:r().optional().describe("2D blend position on the secondary parameter axis (2D blend trees only)"),weight:r().min(0).optional().describe('Explicit weight for "direct" blend trees (ignored by 1D/2D)')}).strict(),y=o({type:l("1D").describe("Interpolates linearly between sorted children by threshold"),parameter:n().min(1).describe("Context/selector value driving the blend"),children:c(d).min(2,"1D blend tree needs at least 2 children to interpolate between")}).strict(),v=o({type:l("2D").describe("Inverse-distance-weights children by (parameter, parameterY) position"),parameter:n().min(1).describe("Primary axis context/selector value"),parameterY:n().min(1).describe("Secondary axis context/selector value"),children:c(d.extend({thresholdY:r()})).min(1,"2D blend tree needs at least 1 child")}).strict(),g=o({type:l("direct").describe("Each child has an explicit weight, normalized to sum to 1"),parameter:n().default(""),children:c(d.extend({weight:r().min(0)})).min(1,"direct blend tree needs at least 1 child")}).strict(),A=b("type",[y,v,g]);function P(e){return e}const p=o({duration:r().min(0).default(0).describe("Seconds to blend from the previously active clip into this state on entry, applied via native `AnimationAction.crossFadeTo`/`fadeIn` (E2). 0 = instant activation, no fade."),warp:m().default(!1).describe("Passed through to AnimationAction.crossFadeTo's `warp` param — linearly warps timeScale across the two clips during the blend so differing clip lengths line up. Default false.")}).strict().describe("Blend-in/out/crossfade timing for entering this state"),x=o({include:c(n().min(1)).min(1).optional().describe("Bone/object names whose complete descendant subtrees are retained"),exclude:c(n().min(1)).min(1).optional().describe("Bone/object names whose complete descendant subtrees are removed")}).strict().refine(e=>!!(e.include?.length||e.exclude?.length),{message:"boneMask needs at least one include or exclude bone name"}).describe("Filters animation tracks by named Object3D/Bone subtrees"),h={layer:n().min(1).optional().describe("Composition layer name; omitted means the single base layer"),weight:r().min(0).max(1).optional().describe("Layer weight multiplier from 0 to 1; defaults to 1"),blendMode:f(["override","additive"]).optional().describe("Native Three normal/override or additive action blending; defaults to override"),boneMask:x.optional().describe("Optional include/exclude filter applied to every clip track in this state")},w=o({clip:n().min(1).describe("Single clip to play while this XState state is active"),loop:m().default(!0).describe("Loop the clip (THREE.LoopRepeat) vs play once (THREE.LoopOnce, clamped on last frame)"),speed:r().positive().default(1).describe("Playback speed multiplier (AnimationAction.timeScale)"),crossfade:p.optional(),...h}).strict(),S=o({blendTree:A.describe("Multiple clips blended by a live context/selector-driven parameter"),crossfade:p.optional(),...h}).strict(),D=u([w,S]);function M(e){return"clip"in e}function $(e){return"blendTree"in e}class T extends Error{constructor(a,i,t){super(a),this.stateId=i,this.issues=t,this.name="AnimationMetaValidationError"}}function B(e,a){const i=D.safeParse(a);if(!i.success){const t=i.error.issues.map(s=>`${s.path.length?s.path.join("."):"(root)"}: ${s.message}`).join("; ");throw new T(`[xstate-animation] invalid meta.animation for state "${e}": ${t}`,e,i.error.issues)}return i.data}function R(e){const a=[],i=t=>{t.meta&&"animation"in t.meta&&t.meta.animation!==void 0&&a.push({stateId:t.id,meta:B(t.id,t.meta.animation)});for(const s of Object.values(t.states??{}))i(s)};return i(e),a}function H(e){return M(e)?[e.clip]:e.blendTree.children.map(a=>a.clip)}export{A as AnimationBlendTreeSchema,T as AnimationMetaValidationError,D as StateAnimationMetaSchema,P as asBlendTreeDef,H as clipNamesOf,R as collectMachineAnimationMeta,$ as isBlendTreeAnimationMeta,M as isClipAnimationMeta,B as parseStateAnimationMeta};
+import{dZ as b,d_ as u,u as o,v as c,w as n,x as l,c6 as r,c5 as m,c4 as f}from"./index-C5tasxXb.js";import"./index-nmcBqr7Y.js";import"./_commonjsHelpers-D6-XlEtG.js";import"./index-D_NuPfjr.js";import"./jsx-runtime-DPjLkJKQ.js";import"./index-CtzuWnCS.js";import"./index-CinJrH5C.js";import"./index-FUuS4qwW.js";import"./client-DNXj_opT.js";const d=o({clip:n().min(1).describe("Animation clip name this child plays"),threshold:r().describe("1D/2D blend position on the primary parameter axis"),thresholdY:r().optional().describe("2D blend position on the secondary parameter axis (2D blend trees only)"),weight:r().min(0).optional().describe('Explicit weight for "direct" blend trees (ignored by 1D/2D)')}).strict(),y=o({type:l("1D").describe("Interpolates linearly between sorted children by threshold"),parameter:n().min(1).describe("Context/selector value driving the blend"),children:c(d).min(2,"1D blend tree needs at least 2 children to interpolate between")}).strict(),v=o({type:l("2D").describe("Inverse-distance-weights children by (parameter, parameterY) position"),parameter:n().min(1).describe("Primary axis context/selector value"),parameterY:n().min(1).describe("Secondary axis context/selector value"),children:c(d.extend({thresholdY:r()})).min(1,"2D blend tree needs at least 1 child")}).strict(),g=o({type:l("direct").describe("Each child has an explicit weight, normalized to sum to 1"),parameter:n().default(""),children:c(d.extend({weight:r().min(0)})).min(1,"direct blend tree needs at least 1 child")}).strict(),A=b("type",[y,v,g]);function Y(e){return e}const p=o({duration:r().min(0).default(0).describe("Seconds to blend from the previously active clip into this state on entry, applied via native `AnimationAction.crossFadeTo`/`fadeIn` (E2). 0 = instant activation, no fade."),warp:m().default(!1).describe("Passed through to AnimationAction.crossFadeTo's `warp` param — linearly warps timeScale across the two clips during the blend so differing clip lengths line up. Default false.")}).strict().describe("Blend-in/out/crossfade timing for entering this state"),x=o({include:c(n().min(1)).min(1).optional().describe("Bone/object names whose complete descendant subtrees are retained"),exclude:c(n().min(1)).min(1).optional().describe("Bone/object names whose complete descendant subtrees are removed")}).strict().refine(e=>!!(e.include?.length||e.exclude?.length),{message:"boneMask needs at least one include or exclude bone name"}).describe("Filters animation tracks by named Object3D/Bone subtrees"),h={layer:n().min(1).optional().describe("Composition layer name; omitted means the single base layer"),weight:r().min(0).max(1).optional().describe("Layer weight multiplier from 0 to 1; defaults to 1"),blendMode:f(["override","additive"]).optional().describe("Native Three normal/override or additive action blending; defaults to override"),boneMask:x.optional().describe("Optional include/exclude filter applied to every clip track in this state")},w=o({clip:n().min(1).describe("Single clip to play while this XState state is active"),loop:m().default(!0).describe("Loop the clip (THREE.LoopRepeat) vs play once (THREE.LoopOnce, clamped on last frame)"),speed:r().positive().default(1).describe("Playback speed multiplier (AnimationAction.timeScale)"),crossfade:p.optional(),...h}).strict(),S=o({blendTree:A.describe("Multiple clips blended by a live context/selector-driven parameter"),crossfade:p.optional(),...h}).strict(),D=u([w,S]);function M(e){return"clip"in e}function $(e){return"blendTree"in e}class T extends Error{constructor(a,i,t){super(a),this.stateId=i,this.issues=t,this.name="AnimationMetaValidationError"}}function B(e,a){const i=D.safeParse(a);if(!i.success){const t=i.error.issues.map(s=>`${s.path.length?s.path.join("."):"(root)"}: ${s.message}`).join("; ");throw new T(`[xstate-animation] invalid meta.animation for state "${e}": ${t}`,e,i.error.issues)}return i.data}function R(e){const a=[],i=t=>{t.meta&&"animation"in t.meta&&t.meta.animation!==void 0&&a.push({stateId:t.id,meta:B(t.id,t.meta.animation)});for(const s of Object.values(t.states??{}))i(s)};return i(e),a}function H(e){return M(e)?[e.clip]:e.blendTree.children.map(a=>a.clip)}export{A as AnimationBlendTreeSchema,T as AnimationMetaValidationError,D as StateAnimationMetaSchema,Y as asBlendTreeDef,H as clipNamesOf,R as collectMachineAnimationMeta,$ as isBlendTreeAnimationMeta,M as isClipAnimationMeta,B as parseStateAnimationMeta};

package/dist-node/cli.js

@@ -2027,8 +2027,11 @@ function projectRelative(project, absolute) {
 }
 async function serveBlenderMcp(project, ensureEditor, command) {
   const runtimeIdentity = `Blender ${BUNDLE_default.blender} (source ${BUNDLE_default.source}), compiled to WebAssembly and running headless in the editor tab; three.js takes its photographs. Factory bpy.context.scene.render.engine: '${BUNDLE_default.factoryEngine}'. Documents are .blend. save_as_mainfile records the actual saved path in bpy.data.filepath; open_mainfile reopens it.`;
+  const photographs = `A photograph is shown to the person in the editor, never in another app: get_viewport_screenshot returns one, and an image file written inside the project opens as an editor document with \`npx ${command} eval 'editor.openAsset("<project-relative path>")'\`. Do not run the OS \`open\` on it.`;
+  const instructions = `${runtimeIdentity}
+${photographs}`;
   const tools = blender_mcp_tools_default.map(
-    (tool) => tool.name === "execute_blender_code" ? { ...tool, description: `${runtimeIdentity}
+    (tool) => tool.name === "execute_blender_code" ? { ...tool, description: `${instructions}
 ${tool.description}` } : tool
   );
   const defaults = blender_mcp_defaults_default;
@@ -2041,7 +2044,7 @@ ${tool.description}` } : tool
     { name: "BlenderMCP", version: BLENDER_MCP_VERSION },
     {
       capabilities: { tools: {}, prompts: {} },
-      instructions: runtimeIdentity
+      instructions
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
@@ -2310,7 +2313,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 var package_default = {
   name: "@volter/game-editor",
   author: "Volter AI, Inc.",
-  version: "0.5.82",
+  version: "0.5.83",
   publishConfig: {
     access: "public"
   },
@@ -2359,22 +2362,22 @@ var package_default = {
     }
   },
   dependencies: {
-    "@volter/editor-core": "0.5.82",
-    "@volter/editor-game": "0.5.82",
-    "@volter/editor-react": "0.5.82",
-    "@volter/editor-threejs": "0.5.82",
-    "@volter/editor-xstate": "0.5.82",
-    "@volter/editor-blender": "0.1.22",
-    "@volter/dawproject": "0.5.82",
-    "@volter/editor-dawproject": "0.5.82",
-    "@volter/blender-engine": "0.1.20",
-    "@volter/editor-project": "0.5.82",
-    "@volter/editor-sdk": "0.5.82",
-    "@volter/editor-live": "0.5.82",
-    "@volter/game-live": "0.5.82",
+    "@volter/editor-core": "0.5.83",
+    "@volter/editor-game": "0.5.83",
+    "@volter/editor-react": "0.5.83",
+    "@volter/editor-threejs": "0.5.83",
+    "@volter/editor-xstate": "0.5.83",
+    "@volter/editor-blender": "0.1.23",
+    "@volter/dawproject": "0.5.83",
+    "@volter/editor-dawproject": "0.5.83",
+    "@volter/blender-engine": "0.1.21",
+    "@volter/editor-project": "0.5.83",
+    "@volter/editor-sdk": "0.5.83",
+    "@volter/editor-live": "0.5.83",
+    "@volter/game-live": "0.5.83",
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@volter/game-runtime": "0.5.82",
-    "@volter/threejs-runtime": "0.5.82",
+    "@volter/game-runtime": "0.5.83",
+    "@volter/threejs-runtime": "0.5.83",
     undici: "7.29.1",
     typescript: "5.9.3",
     "@colyseus/schema": "^4.0.14",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/game-editor",
   "author": "Volter AI, Inc.",
-  "version": "0.5.82",
+  "version": "0.5.83",
   "publishConfig": {
     "access": "public"
   },
@@ -50,22 +50,22 @@
     }
   },
   "dependencies": {
-    "@volter/editor-core": "0.5.82",
-    "@volter/editor-game": "0.5.82",
-    "@volter/editor-react": "0.5.82",
-    "@volter/editor-threejs": "0.5.82",
-    "@volter/editor-xstate": "0.5.82",
-    "@volter/editor-blender": "0.1.22",
-    "@volter/dawproject": "0.5.82",
-    "@volter/editor-dawproject": "0.5.82",
-    "@volter/blender-engine": "0.1.20",
-    "@volter/editor-project": "0.5.82",
-    "@volter/editor-sdk": "0.5.82",
-    "@volter/editor-live": "0.5.82",
-    "@volter/game-live": "0.5.82",
+    "@volter/editor-core": "0.5.83",
+    "@volter/editor-game": "0.5.83",
+    "@volter/editor-react": "0.5.83",
+    "@volter/editor-threejs": "0.5.83",
+    "@volter/editor-xstate": "0.5.83",
+    "@volter/editor-blender": "0.1.23",
+    "@volter/dawproject": "0.5.83",
+    "@volter/editor-dawproject": "0.5.83",
+    "@volter/blender-engine": "0.1.21",
+    "@volter/editor-project": "0.5.83",
+    "@volter/editor-sdk": "0.5.83",
+    "@volter/editor-live": "0.5.83",
+    "@volter/game-live": "0.5.83",
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@volter/game-runtime": "0.5.82",
-    "@volter/threejs-runtime": "0.5.82",
+    "@volter/game-runtime": "0.5.83",
+    "@volter/threejs-runtime": "0.5.83",
     "undici": "7.29.1",
     "typescript": "5.9.3",
     "@colyseus/schema": "^4.0.14",

package/template/src/lib/reflections/ReflectionProbe.tsx

@@ -1,8 +1,7 @@
 import { type ThreeElements, useFrame, useThree } from '@react-three/fiber';
-import type { ReflectionProbeConfig } from '@volter/threejs-runtime/adapter/reflection-probe';
 import { type ReactNode, useLayoutEffect, useRef, useState } from 'react';
 import type * as THREE from 'three';
-import { createReflectionProbeMark } from './probe-controller';
+import { createReflectionProbeMark, type VolumeReflectionProbeConfig } from './probe-controller';
 import {
   acquireReflectionProbeRegistry,
   type ReflectionProbeRegistryLease,
@@ -60,6 +59,15 @@ export type ReflectionProbeProps = Omit<ThreeElements['group'], 'children'> & {
   readonly blendDistance?: number;
   readonly priority?: number;
   readonly intensity?: number;
+  /**
+   * The diffuse light the volume material takes from this probe: its capture
+   * (default), the constant `diffuseColor`, or none. See `ReflectionProbeDiffuse`.
+   */
+  readonly diffuse?: 'capture' | 'color' | 'none';
+  /** Scales the probe's diffuse light in the volume material; defaults to `intensity`. */
+  readonly diffuseIntensity?: number;
+  /** Linear RGB of the `color` diffuse. */
+  readonly diffuseColor?: [number, number, number];
   readonly parallaxProjection?: boolean;
   /** Full local-space projection-box dimensions. */
   readonly parallaxSize?: [number, number, number];
@@ -73,6 +81,19 @@ export type ReflectionProbeProps = Omit<ThreeElements['group'], 'children'> & {
   readonly captureShadows?: boolean;
 };
 
+/** The diffuse fields a probe states, leaving out the ones it does not (they keep their defaults). */
+function diffuseConfig(
+  diffuse: ReflectionProbeProps['diffuse'],
+  diffuseIntensity: number | undefined,
+  diffuseColor: [number, number, number] | undefined,
+): Partial<VolumeReflectionProbeConfig> {
+  return {
+    ...(diffuse === undefined ? {} : { diffuse }),
+    ...(diffuseIntensity === undefined ? {} : { diffuseIntensity }),
+    ...(diffuseColor === undefined ? {} : { diffuseColor }),
+  };
+}
+
 export function ReflectionProbe({
   name = 'Reflection Probe',
   children,
@@ -82,6 +103,9 @@ export function ReflectionProbe({
   blendDistance = 1,
   priority = 0,
   intensity = 1,
+  diffuse,
+  diffuseIntensity,
+  diffuseColor,
   parallaxProjection = true,
   parallaxSize = [10, 6, 10],
   parallaxOffset = [0, 0, 0],
@@ -109,6 +133,7 @@ export function ReflectionProbe({
       blendDistance,
       priority,
       intensity,
+      ...diffuseConfig(diffuse, diffuseIntensity, diffuseColor),
       parallaxProjection,
       parallaxSize,
       parallaxOffset,
@@ -121,13 +146,14 @@ export function ReflectionProbe({
       captureShadows,
     }),
   );
-  const config: ReflectionProbeConfig = {
+  const config: VolumeReflectionProbeConfig = {
     shape,
     size,
     radius,
     blendDistance,
     priority,
     intensity,
+    ...diffuseConfig(diffuse, diffuseIntensity, diffuseColor),
     parallaxProjection,
     parallaxSize,
     parallaxOffset,
@@ -149,6 +175,9 @@ export function ReflectionProbe({
     blendDistance,
     priority,
     intensity,
+    diffuse,
+    diffuseIntensity,
+    diffuseColor,
     parallaxProjection,
     parallaxSize,
     parallaxOffset,
@@ -170,8 +199,8 @@ export function ReflectionProbe({
     unobserve.current = acquired.registry.observe((probes: readonly ReflectionProbeRuntime[]) => {
       const self = probes.find((probe) => probe.node === object);
       const published = self?.ready ? self.texture : null;
-      // Runs every update; React re-renders only when the published texture
-      // actually changes identity, which is once per capture at most.
+      // Runs whenever the registry changes; React re-renders only when the
+      // published texture actually changes identity, once per capture at most.
       setEnvMap((current) => (current === published ? current : published));
     });
     return () => {

package/template/src/lib/reflections/index.ts

@@ -3,6 +3,7 @@ export {
   type ReflectionProbeProps,
   type ReflectionProbePublication,
 } from './ReflectionProbe';
+export type { ReflectionProbeDiffuse, VolumeReflectionProbeConfig } from './probe-controller';
 export {
   acquireReflectionProbeRegistry,
   createReflectionProbeRegistry,

package/template/src/lib/reflections/probe-controller.ts

@@ -4,17 +4,53 @@ import type {
   ReflectionProbeSnapshot,
 } from '@volter/threejs-runtime/adapter/reflection-probe';
 
+/**
+ * How a probe lights the diffuse term of the volume material that blends it,
+ * carried in its mark's config beside the format-neutral fields. Every field
+ * is optional; left out, a probe lights the diffuse from its capture, scaled
+ * by its `intensity`, as the reflected term is.
+ */
+export interface ReflectionProbeDiffuse {
+  /**
+   * Where the probe's diffuse light comes from: its `capture` (the default), the
+   * constant `color` below, or `none` — the probe lights no diffuse, and a
+   * fragment that only it covers keeps the environment's.
+   */
+  readonly diffuse?: 'capture' | 'color' | 'none';
+  /** Scales the probe's diffuse light. Defaults to the probe's `intensity`. */
+  readonly diffuseIntensity?: number;
+  /** Linear RGB radiance of the `color` diffuse. */
+  readonly diffuseColor?: readonly [number, number, number];
+}
+
+/** A probe's config as the capability's own element states it. */
+export type VolumeReflectionProbeConfig = ReflectionProbeConfig & ReflectionProbeDiffuse;
+
 export interface MutableReflectionProbeMark extends ReflectionProbeMark {
   updateConfig(config: ReflectionProbeConfig): void;
   setCaptureStatus(snapshot: ReflectionProbeSnapshot): void;
 }
 
-/** One live projection of a component's JSX props and capture state. */
+/**
+ * The config as a capture sees it: everything but the diffuse fields, which
+ * only the volume material reads (from the probe's uniforms, not its capture).
+ */
+function captureSignature(config: ReflectionProbeConfig): string {
+  const { diffuse, diffuseIntensity, diffuseColor, ...captured } = config as VolumeReflectionProbeConfig;
+  return JSON.stringify(captured);
+}
+
+/**
+ * One live projection of a component's JSX props and capture state. A config
+ * change that a capture sees queues a recapture (outside Manual); one that
+ * only changes the diffuse fields takes effect without one.
+ */
 export function createReflectionProbeMark(
   initial: ReflectionProbeConfig,
 ): MutableReflectionProbeMark {
   let config = initial;
   let configSignature = JSON.stringify(initial);
+  let capturedSignature = captureSignature(initial);
   let revision = 0;
   let snapshot: ReflectionProbeSnapshot = {
     status: initial.captureMode === 'manual' ? 'idle' : 'queued',
@@ -47,12 +83,17 @@ export function createReflectionProbeMark(
       const signature = JSON.stringify(next);
       if (signature === configSignature) return;
       const previousMode = config.captureMode;
+      const nextCaptured = captureSignature(next);
+      const recapture = nextCaptured !== capturedSignature;
       config = next;
       configSignature = signature;
-      if (next.captureMode !== 'manual') {
+      capturedSignature = nextCaptured;
+      // A diffuse-only change needs no capture: the registry sees the new config
+      // and the volume material rewrites its uniforms.
+      if (recapture && next.captureMode !== 'manual') {
         revision += 1;
         snapshot = { status: 'queued', lastCapturedAt: snapshot.lastCapturedAt };
-      } else if (previousMode !== 'manual' && snapshot.status !== 'ready') {
+      } else if (next.captureMode === 'manual' && previousMode !== 'manual' && snapshot.status !== 'ready') {
         // Entering Manual never performs an implicit capture. A valid existing
         // result remains valid; otherwise the explicit Recapture button is the
         // only operation that advances the capture revision.

package/template/src/lib/reflections/reflection-probe-registry.ts

@@ -71,9 +71,17 @@ interface ProbeState extends ReflectionProbeRuntime {
   ready: boolean;
   capturedRevision: number;
   readonly capturedTransform: Matrix4;
+  /** The node's world matrix and the mark's config as observers were last told them. */
+  readonly publishedTransform: Matrix4;
+  publishedConfig: ReflectionProbeMark['config'] | null;
 }
 
-/** Called every update, and again the moment a capture window opens/closes. */
+/**
+ * Called when an observer starts observing, and again whenever what it reads
+ * changes: a probe added or removed, a capture window opening or closing (and
+ * the result it published), a probe's node moved or its config changed. A
+ * frame in which nothing changed calls no observer.
+ */
 export type ReflectionProbeObserver = (
   probes: readonly ReflectionProbeRuntime[],
   capturing: boolean,
@@ -129,6 +137,8 @@ function makeProbe(node: Object3D, mark: ReflectionProbeMark): ProbeState {
     parallaxOffset: new Vector3(),
     captureOffset: new Vector3(),
     capturedTransform: new Matrix4().makeScale(0, 0, 0),
+    publishedTransform: new Matrix4().makeScale(0, 0, 0),
+    publishedConfig: null,
     filtered: null,
     atlases: new Map(),
     texture: null,
@@ -174,6 +184,10 @@ function releaseProbeResources(probe: ProbeState): void {
   probe.ready = false;
 }
 
+/**
+ * Bring the probe's volume up to date with its node and config; true when
+ * that changed what an observer reads since it was last told.
+ */
 function refreshProbe(probe: ProbeState): boolean {
   const config = probe.mark.config;
   const cubeSize = cubeSizeOf(probe.mark);
@@ -194,9 +208,15 @@ function refreshProbe(probe: ProbeState): boolean {
   probe.parallaxExtents.fromArray(config.parallaxSize).multiplyScalar(0.5);
   probe.parallaxOffset.fromArray(config.parallaxOffset);
   probe.captureOffset.fromArray(config.captureOffset);
-  const moved = !probe.capturedTransform.equals(probe.node.matrixWorld);
-  if (moved && config.captureMode === 'on-change') probe.ready = false;
-  return moved;
+  if (config.captureMode === 'on-change' && movedSinceCapture(probe)) probe.ready = false;
+  const changed = probe.publishedConfig !== config || !probe.publishedTransform.equals(probe.node.matrixWorld);
+  probe.publishedConfig = config;
+  probe.publishedTransform.copy(probe.node.matrixWorld);
+  return changed;
+}
+
+function movedSinceCapture(probe: ProbeState): boolean {
+  return !probe.capturedTransform.equals(probe.node.matrixWorld);
 }
 
 /** The cube target and camera, created here because only a capture needs them. */
@@ -300,7 +320,7 @@ export function createReflectionProbeRegistry(
     for (let offset = 0; offset < probes.length; offset += 1) {
       const index = (cursor + offset) % probes.length;
       const probe = probes[index]!;
-      const moved = refreshProbe(probe);
+      const moved = movedSinceCapture(probe);
       const mode = probe.mark.config.captureMode;
       const due =
         mode === 'realtime' ||
@@ -336,10 +356,15 @@ export function createReflectionProbeRegistry(
     update(frameToken) {
       if (disposed || frameToken === lastFrame || !canCaptureEnvironment(renderer)) return;
       lastFrame = frameToken;
-      for (const probe of probes) refreshProbe(probe);
+      let changed = false;
+      for (const probe of probes) {
+        const ready = probe.ready;
+        if (refreshProbe(probe) || probe.ready !== ready) changed = true;
+      }
       const due = nextCapture();
       if (due) capture(due);
-      notify(false);
+      // A capture opened a window (and published a result): closing it tells every observer.
+      if (due || changed) notify(false);
     },
     dispose() {
       if (disposed) return;