Playbook and Three.js code kit for detailed dioramas: classic pixel art, stroked toon or pixel + stroke; two intake gates for look and model sourcing; free orbit, palette snap and ink; animated toy-scale cast; per-entity frame QA.
JavaScript agent-skillagent-skill-repositoryagent-skillsai-agentscreative-codingdioramagame-artpixel-artpixelationprocedural-artprocedural-generationskillthree-jsthreejswebgl
/**
* Reusable detail assemblies. All colours come from the caller's materials so
* the palette stays the single source of truth.
*/
import * as THREE from 'three';
export function mesh(parent, geo, mat, x, y, z, opts = {}) {
const m = new THREE.Mesh(geo, mat);
m.position.set(x, y, z);
if (opts.rotation) m.rotation.set(...opts.rotation);
if (opts.scale) m.scale.set(...opts.scale);
m.castShadow = opts.castShadow ?? true;
m.receiveShadow = opts.receiveShadow ?? true;
parent.add(m);
return m;
}
/** A straight bone/rope/bar between two points. */
export function seg(parent, a, b, r0, r1, mat, opts = {}) {
const dir = new THREE.Vector3().subVectors(b, a);
const len = Math.max(0.001, dir.length());
const mid = new THREE.Vector3().addVectors(a, b).multiplyScalar(0.5);
const m = mesh(
parent,
new THREE.CylinderGeometry(r1, r0, len, opts.segments ?? 5),
mat,
mid.x,
mid.y,
mid.z,
opts
);
m.quaternion.setFromUnitVectors(new THREE.Vector3(0, 1, 0), dir.normalize());
return m;
}
/** Horizontal iron band around a shaft. */
export function band(parent, radius, tube, mat, y, opts = {}) {
return mesh(
parent,
new THREE.TorusGeometry(radius, tube, 4, opts.segments ?? 10),
mat,
0,
y,
0,
{ rotation: [Math.PI / 2, 0, 0], ...opts }
);
}
/** A ring of rivets/studs around a horizontal circle. */
export function rivets(parent, mat, count, radius, y, size = 0.03, opts = {}) {
const g = new THREE.Group();
g.position.y = y;
parent.add(g);
for (let i = 0; i < count; i++) {
const a = (i / count) * Math.PI * 2;
mesh(g, new THREE.SphereGeometry(size, 4, 3), mat, Math.sin(a) * radius, 0, Math.cos(a) * radius, {
castShadow: false,
...opts,
});
}
return g;
}
/** Simple spoked wheel in the YZ plane, axle along X. */
export function wheel(parent, mat, rimMat, x, y, z, radius = 0.3, width = 0.06, spokes = 6) {
const g = new THREE.Group();
g.position.set(x, y, z);
parent.add(g);
mesh(g, new THREE.TorusGeometry(radius, width, 4, 12), mat, 0, 0, 0, {
rotation: [0, Math.PI / 2, 0],
});
mesh(g, new THREE.TorusGeometry(radius + 0.02, 0.018, 4, 12), rimMat, 0, 0, 0, {
rotation: [0, Math.PI / 2, 0],
castShadow: false,
});
for (let i = 0; i < spokes; i++) {
mesh(g, new THREE.BoxGeometry(0.035, radius * 1.9, 0.035), mat, 0, 0, 0, {
rotation: [(i / spokes) * Math.PI, 0, 0],
castShadow: false,
});
}
mesh(g, new THREE.CylinderGeometry(0.06, 0.06, width * 1.6, 6), rimMat, 0, 0, 0, {
rotation: [0, 0, Math.PI / 2],
castShadow: false,
});
return g;
}
/** A tied rectangular hay bale, with straw tufts. */
export function bale(parent, mat, tieMat, x, y, z, opts = {}) {
const w = opts.w ?? 0.6;
const h = opts.h ?? 0.3;
const d = opts.d ?? 0.46;
const g = new THREE.Group();
g.position.set(x, y, z);
if (opts.rotation) g.rotation.y = opts.rotation;
parent.add(g);
mesh(g, new THREE.BoxGeometry(w, h, d), mat, 0, 0, 0);
for (const s of [-1, 1]) {
mesh(g, new THREE.BoxGeometry(0.032, h * 1.04, d * 1.04), tieMat, s * w * 0.25, 0, 0, {
castShadow: false,
});
}
for (let i = 0; i < 5; i++) {
mesh(g, new THREE.BoxGeometry(0.015, 0.11, 0.015), mat, -w * 0.35 + i * w * 0.17, h * 0.6, d * 0.3, {
rotation: [0.2, 0, 0.4 - i * 0.2],
castShadow: false,
});
}
return g;
}
/** A horned skull facing +Z. Mount it on trophyBoard(), never in mid-air. */
export function skull(parent, boneMat, inkMat, x, y, z, s = 1) {
const g = new THREE.Group();
g.position.set(x, y, z);
parent.add(g);
mesh(g, new THREE.SphereGeometry(0.22 * s, 7, 6), boneMat, 0, 0, 0, { scale: [1, 0.92, 1.04] });
mesh(g, new THREE.BoxGeometry(0.34 * s, 0.09 * s, 0.16 * s), boneMat, 0, 0.09 * s, 0.12 * s);
mesh(g, new THREE.BoxGeometry(0.19 * s, 0.14 * s, 0.22 * s), boneMat, 0, -0.12 * s, 0.18 * s, {
rotation: [0.12, 0, 0],
});
mesh(g, new THREE.BoxGeometry(0.17 * s, 0.07 * s, 0.18 * s), boneMat, 0, -0.2 * s, 0.2 * s);
for (const side of [-1, 1]) {
mesh(g, new THREE.BoxGeometry(0.075 * s, 0.09 * s, 0.06 * s), inkMat, side * 0.085 * s, 0.03 * s, 0.2 * s, {
castShadow: false,
});
const a = new THREE.Vector3(side * 0.16 * s, 0.11 * s, 0.02 * s);
const b = new THREE.Vector3(side * 0.31 * s, 0.25 * s, 0);
const c = new THREE.Vector3(side * 0.41 * s, 0.43 * s, -0.02 * s);
const d = new THREE.Vector3(side * 0.35 * s, 0.56 * s, -0.01 * s);
seg(g, a, b, 0.06 * s, 0.048 * s, boneMat);
seg(g, b, c, 0.048 * s, 0.034 * s, boneMat);
seg(g, c, d, 0.034 * s, 0.02 * s, boneMat);
}
return g;
}
/** A rope/chain run through points. Returns the segment group. */
export function rope(parent, points, radius, mat, opts = {}) {
const g = new THREE.Group();
parent.add(g);
for (let i = 1; i < points.length; i++) {
seg(g, points[i - 1], points[i], radius, radius * 0.92, mat, {
segments: opts.segments ?? 4,
castShadow: opts.castShadow ?? true,
});
if (i < points.length - 1) {
mesh(g, new THREE.SphereGeometry(radius * 1.05, 4, 3), mat, points[i].x, points[i].y, points[i].z, {
castShadow: false,
});
}
}
return g;
}
/** A trophy board with studs and a rope loop; place a skull on its face. */
export function trophyBoard(parent, woodMat, ironMat, x, y, z, w = 0.62, h = 0.72) {
const g = new THREE.Group();
g.position.set(x, y, z);
parent.add(g);
mesh(g, new THREE.BoxGeometry(w, h, 0.07), woodMat, 0, 0, 0);
for (const sx of [-1, 1]) {
for (const sy of [-1, 1]) {
mesh(g, new THREE.SphereGeometry(0.028, 4, 3), ironMat, sx * w * 0.38, sy * h * 0.38, 0.045, {
castShadow: false,
});
}
}
mesh(g, new THREE.TorusGeometry(0.06, 0.012, 3, 6), ironMat, 0, h * 0.5, 0, {
rotation: [Math.PI / 2, 0, 0],
castShadow: false,
});
return g;
}
let _shadowTex = null;
function shadowTexture() {
if (_shadowTex) return _shadowTex;
const c = document.createElement('canvas');
c.width = c.height = 64;
const ctx = c.getContext('2d');
const g = ctx.createRadialGradient(32, 32, 2, 32, 32, 31);
g.addColorStop(0, 'rgba(0,0,0,0.72)');
g.addColorStop(0.55, 'rgba(0,0,0,0.28)');
g.addColorStop(1, 'rgba(0,0,0,0)');
ctx.fillStyle = g;
ctx.fillRect(0, 0, 64, 64);
_shadowTex = new THREE.CanvasTexture(c);
return _shadowTex;
}
/** Ground-projected contact shadow. Put it on the surface the object stands on. */
export function contactShadow(parent, x, y, z, size = 1, opacity = 0.62) {
const mat = new THREE.MeshBasicMaterial({
map: shadowTexture(),
transparent: true,
opacity,
depthWrite: false,
color: 0x000000,
});
const m = new THREE.Mesh(new THREE.PlaneGeometry(size, size), mat);
m.rotation.x = -Math.PI / 2;
m.position.set(x, y + 0.018, z);
m.renderOrder = 1;
parent.add(m);
return m;
}
const _radialTex = new Map();
/**
* Soft radial-alpha texture for halos, light pools and glow cards.
* `rgb` is an "r,g,b" string so the texture bakes the palette colour.
*/
export function softDiscTexture(rgb = '255,255,255', size = 64) {
const key = `${rgb}|${size}`;
if (_radialTex.has(key)) return _radialTex.get(key);
const c = document.createElement('canvas');
c.width = c.height = size;
const ctx = c.getContext('2d');
const g = ctx.createRadialGradient(size / 2, size / 2, size * 0.03, size / 2, size / 2, size * 0.49);
g.addColorStop(0, `rgba(${rgb},1)`);
g.addColorStop(0.45, `rgba(${rgb},0.55)`);
g.addColorStop(1, `rgba(${rgb},0)`);
ctx.fillStyle = g;
ctx.fillRect(0, 0, size, size);
const tex = new THREE.CanvasTexture(c);
tex.colorSpace = THREE.SRGBColorSpace;
_radialTex.set(key, tex);
return tex;
}
/**
* A glow card with a soft edge. Use this instead of an untextured additive
* PlaneGeometry: a flat quad reads as a light-grey rectangle at the palette snap.
* Add it to the prop so it moves with the lamp/board/sign.
*/
export function haloPlane(parent, width, height, rgb, opacity = 0.35, x = 0, y = 0, z = 0, opts = {}) {
const mat = new THREE.MeshBasicMaterial({
map: softDiscTexture(rgb),
transparent: true,
opacity,
blending: THREE.AdditiveBlending,
depthWrite: false,
side: THREE.DoubleSide,
color: 0xffffff,
});
const m = new THREE.Mesh(new THREE.PlaneGeometry(width, height), mat);
m.position.set(x, y, z);
if (opts.rotation) m.rotation.set(...opts.rotation);
m.renderOrder = opts.renderOrder ?? 3;
parent.add(m);
return m;
}