divs (each
// with its own pivot transform), then drops cubes inside the bone they
// belong to. At animation time, each bone's local rotation/translation
// is interpolated between keyframes and applied as a CSS transform.
// CSS preserve-3d composes transforms down the tree so child cubes
// follow their parent bone correctly.
//
// Coord system note: bbmodel uses -Z forward and Y up; CSS uses +Z
// forward (toward camera) and Y *down*. We z-negate translations + y-
// negate so the visual matches the data — same convention used in the
// non-animated path (see bbmodelToVoxelCubes).
function _findKeyframes(animator, channel) {
// Collect + sort keyframes for one channel of one bone.
const out = [];
for (const kf of (animator?.keyframes || [])) {
if (kf.channel !== channel) continue;
const p = (kf.data_points && kf.data_points[0]) || {};
out.push({
t: Number(kf.time) || 0,
x: Number(p.x) || 0,
y: Number(p.y) || 0,
z: Number(p.z) || 0,
});
}
out.sort((a, b) => a.t - b.t);
return out;
}
function _lerpKeyframes(kfs, t) {
if (!kfs.length) return null;
if (t <= kfs[0].t) return kfs[0];
if (t >= kfs[kfs.length - 1].t) return kfs[kfs.length - 1];
// Linear binary search would be faster but lists are usually short.
for (let i = 1; i < kfs.length; i++) {
if (t < kfs[i].t) {
const a = kfs[i - 1], b = kfs[i];
const r = (t - a.t) / Math.max(1e-6, b.t - a.t);
return {
t,
x: a.x + (b.x - a.x) * r,
y: a.y + (b.y - a.y) * r,
z: a.z + (b.z - a.z) * r,
};
}
}
return kfs[kfs.length - 1];
}
function _animatorForBone(anim, boneName) {
// Animator entries are keyed by bone uuid (not name); search by name.
const animators = anim?.animators || {};
for (const k in animators) {
const a = animators[k];
if (a && a.name === boneName) return a;
}
return null;
}
function _Bone({ node, byUuid, anim, time, scale, parentOrigin = [0, 0, 0], atlas = null }) {
// node.origin = world-space pivot in bbmodel coords. Converted to
// local-relative-to-parent so nested transforms compose correctly.
const origin = node.origin || [0, 0, 0];
const localPivot = [
(origin[0] - parentOrigin[0]) * scale,
(origin[1] - parentOrigin[1]) * scale,
-(origin[2] - parentOrigin[2]) * scale, // Z-flip
];
// Animation channels for this bone, evaluated at `time`.
let rot = { x: 0, y: 0, z: 0 };
let pos = { x: 0, y: 0, z: 0 };
if (anim) {
const a = _animatorForBone(anim, node.name);
if (a) {
const r = _lerpKeyframes(_findKeyframes(a, "rotation"), time);
const p = _lerpKeyframes(_findKeyframes(a, "position"), time);
if (r) rot = r;
if (p) pos = p;
}
}
// Compose: translate to pivot → rest rotation → animate rotation/translation
// → so cubes are positioned around the pivot. The rest rotation
// (node.rotation) is the bone's bind-pose orientation — previously
// ignored, so a rigged-in-place model imported as bind-rotated bones
// (e.g. raised-arm idle, tilted head) would show un-rotated in preview
// even though the GLB renders rotated. CSS coord mapping for bbmodel
// extrinsic XYZ Euler under the preview's Y/Z mirror: rx_css = +rx,
// ry_css = -ry, rz_css = -rz (see _bbRotationToCss for derivation).
//
// The existing anim rotation lines (rot.x/y/z below) are kept as-is to
// preserve whatever convention the animation pipeline was authored
// against — flipping signs here could regress currently-playable anims.
const restRot = node.rotation || [0, 0, 0];
const restRx = Number(restRot[0]) || 0;
const restRy = Number(restRot[1]) || 0;
const restRz = Number(restRot[2]) || 0;
const restRotCss = (restRx || restRy || restRz)
? ` rotateZ(${-restRz}deg) rotateY(${-restRy}deg) rotateX(${restRx}deg)`
: "";
const transform = [
`translate3d(${localPivot[0]}px, ${-localPivot[1]}px, ${localPivot[2]}px)`,
`translate3d(${pos.x * scale}px, ${-pos.y * scale}px, ${-pos.z * scale}px)`,
`rotateZ(${rot.z}deg)`,
`rotateY(${rot.y}deg)`,
`rotateX(${rot.x}deg)`,
].join(" ") + restRotCss;
// Cubes attached directly to THIS bone (children that are uuid strings).
const cubeChildren = (node.children || []).filter((c) => typeof c === "string");
const groupChildren = (node.children || []).filter((c) => typeof c === "object" && c);
return (
{cubeChildren.map((uuid) => {
const el = byUuid[uuid];
if (!el) return null;
const f = el.from || [0, 0, 0];
const t = el.to || [0, 0, 0];
// Cube position relative to the BONE's pivot (which is now origin
// in our local space — so we subtract `origin`).
const cx = ((f[0] + t[0]) / 2 - origin[0]) * scale;
const cy = ((f[1] + t[1]) / 2 - origin[1]) * scale;
const cz = -((f[2] + t[2]) / 2 - origin[2]) * scale;
const w = Math.abs(t[0] - f[0]) * scale;
const h = Math.abs(t[1] - f[1]) * scale;
const d = Math.abs(t[2] - f[2]) * scale;
// Cube hue: position-based hash so per-cube colors are stable.
const hash = (Math.abs(f[0] * 31 + f[1] * 17 + f[2] * 7) | 0) >>> 0;
const palette = ["#7a8c4e","#a8a59a","#3b3a55","#cf7a3f","#5a587a",
"#6f8048","#8a9c5c","#7c7a72","#3b4655","#a98b4e"];
const color = palette[hash % palette.length];
// Per-cube rotation pivot: element.origin minus cube center, in
// preview-Y-up units (matching Cube's x/y/z param frame). The
// bone's own rotation is handled by the wrapper transform above;
// here we only need the cube-local pivot offset.
const cubeCenterBb = [
(f[0] + t[0]) / 2,
(f[1] + t[1]) / 2,
(f[2] + t[2]) / 2,
];
const originBb = el.origin || cubeCenterBb;
const fitScale = scale / VOXEL_SIZE;
const pivotOffset = [
((Number(originBb[0]) || 0) - cubeCenterBb[0]) * fitScale,
((Number(originBb[1]) || 0) - cubeCenterBb[1]) * fitScale,
-((Number(originBb[2]) || 0) - cubeCenterBb[2]) * fitScale,
];
return (
);
})}
{groupChildren.map((g, i) => (
<_Bone key={g.uuid || i}
node={g} byUuid={byUuid} anim={anim}
time={time} scale={scale}
parentOrigin={origin} atlas={atlas} />
))}
);
}
/** Drop-in replacement for VoxelPreview that animates real bone TRS.
* Falls back to the static VoxelPreview cubes path when bbmodel has
* no outliner / animations (e.g. before the first generate). */
function AnimatedVoxelPreview({ bbmodel, animation, time = 0, autoSpin = true, textureB64 = null }) {
const atlas = _resolveAtlas(bbmodel, textureB64);
const view = useViewControls();
if (!bbmodel || !(bbmodel.outliner || []).length) {
// Empty state: degrade to the empty placeholder VoxelPreview ships.
return ;
}
if (!(bbmodel.elements || []).length) {
return ;
}
// Build {uuid: element}.
const byUuid = {};
for (const el of (bbmodel.elements || [])) {
if (el && el.uuid) byUuid[el.uuid] = el;
}
// Center and scale the rig from its visual bounds instead of the model origin.
let minX = +Infinity, maxX = -Infinity;
let minY = +Infinity, maxY = -Infinity;
let minZ = +Infinity, maxZ = -Infinity;
for (const el of (bbmodel.elements || [])) {
const f = el.from || [0, 0, 0], t = el.to || [0, 0, 0];
minX = Math.min(minX, f[0], t[0]); maxX = Math.max(maxX, f[0], t[0]);
minY = Math.min(minY, f[1], t[1]); maxY = Math.max(maxY, f[1], t[1]);
minZ = Math.min(minZ, f[2], t[2]); maxZ = Math.max(maxZ, f[2], t[2]);
}
const boundsSpan = Math.max(maxX - minX, maxY - minY, maxZ - minZ, 1);
// Match the static path's silhouette scale so swapping between static
// and animated previews doesn't snap the model to a different size.
const fitScale = PREVIEW_FIT / boundsSpan;
const scale = fitScale * VOXEL_SIZE;
const cx = (minX + maxX) / 2;
const cy = (minY + maxY) / 2;
const cz = (minZ + maxZ) / 2;
// When a real animation is playing OR user has dragged, suppress the
// CSS turnaround keyframe — we control the scene transform directly.
const sceneStyle = animation
? { ...view.sceneStyle, animation: "none" }
: view.sceneStyle;
return (
{/* Recenter rig at origin */}
{(bbmodel.outliner || []).map((node, i) =>
isObject(node) ? (
<_Bone key={node.uuid || i}
node={node} byUuid={byUuid}
anim={animation} time={time}
scale={scale} parentOrigin={[0, 0, 0]}
atlas={atlas} />
) : null,
)}
视距 {view.zCam >= 0 ? "+" : ""}{view.zCam.toFixed(0)}
);
}
function isObject(x) { return x && typeof x === "object"; }
/**
* Shared mouse / wheel interaction state for the voxel preview.
* - Wheel: dolly (translateZ camera). Range [-600, 800].
* - Left drag: pan (translate the scene wrap on screen X/Y). Reset on dblclick.
* - Right drag: orbit (yaw/pitch rotation of the scene). Reset on dblclick.
* - Once the user starts dragging, the CSS `turnaround` keyframe is
* suppressed via inline animation:none so user input doesn't fight
* the auto-spin.
*
* Returns:
* stageProps — bind to .voxel-stage (onWheel, onMouseDown, onContextMenu, onDoubleClick)
* wrapTransform — string to set on .voxel-scene-wrap (existing translateZ + new pan)
* sceneStyle — { animation, transform } to set on .voxel-scene
* zCam — current dolly value (for the bottom-right HUD pill)
*/
function useViewControls(initialYaw = 35, initialPitch = -25) {
const [zCam, setZCam] = React.useState(0);
const [pan, setPan] = React.useState({ x: 0, y: 0 });
const [rot, setRot] = React.useState({ yaw: initialYaw, pitch: initialPitch });
const [interacted, setInteracted] = React.useState(false);
const dragRef = React.useRef(null); // {button, lastX, lastY} during drag
const onWheel = (e) => {
e.preventDefault();
setZCam((z) => Math.max(-600, Math.min(800, z - e.deltaY * 0.5)));
};
const onMouseDown = (e) => {
// Only react to left (0) and right (2). Middle (1) reserved.
if (e.button !== 0 && e.button !== 2) return;
e.preventDefault();
dragRef.current = { button: e.button, lastX: e.clientX, lastY: e.clientY };
setInteracted(true);
const onMove = (mv) => {
const st = dragRef.current;
if (!st) return;
const dx = mv.clientX - st.lastX;
const dy = mv.clientY - st.lastY;
st.lastX = mv.clientX;
st.lastY = mv.clientY;
if (st.button === 0) {
// Left: pan in screen space.
setPan((p) => ({ x: p.x + dx, y: p.y + dy }));
} else {
// Right: orbit. dx → yaw (Y rotation), dy → pitch (X rotation).
// Clamp pitch to ±89° so the scene doesn't flip past vertical.
setRot((r) => ({
yaw: r.yaw + dx * 0.4,
pitch: Math.max(-89, Math.min(89, r.pitch - dy * 0.4)),
}));
}
};
const onUp = () => {
window.removeEventListener("mousemove", onMove);
window.removeEventListener("mouseup", onUp);
dragRef.current = null;
};
window.addEventListener("mousemove", onMove);
window.addEventListener("mouseup", onUp);
};
const onContextMenu = (e) => {
// Suppress the browser context menu so right-drag-orbit doesn't get
// interrupted by it.
e.preventDefault();
};
const onDoubleClick = () => {
setZCam(0);
setPan({ x: 0, y: 0 });
setRot({ yaw: initialYaw, pitch: initialPitch });
setInteracted(false);
};
const stageProps = { onWheel, onMouseDown, onContextMenu, onDoubleClick };
const wrapTransform = `translate(${pan.x}px, ${pan.y}px) translateZ(${zCam}px)`;
const sceneStyle = {
animation: interacted ? "none" : undefined,
transform: `rotateX(${rot.pitch}deg) rotateY(${rot.yaw}deg)`,
};
return { stageProps, wrapTransform, sceneStyle, zCam, interacted };
}
window.VoxelPreview = VoxelPreview;
window.AnimatedVoxelPreview = AnimatedVoxelPreview;
window.VOXEL_MODELS = Object.keys(MODELS);
window.bbmodelToVoxelCubes = bbmodelToVoxelCubes;