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.

Add Kiln orientation and attachment helpers

Matt Kissinger4d4e431e699c
diff --git a/__tests__/primitives.test.ts b/__tests__/primitives.test.ts
index 1de35827..390faf5a 100644
--- a/__tests__/primitives.test.ts
+++ b/__tests__/primitives.test.ts
@@ -23,14 +23,24 @@ import {
createRoot,
createPivot,
createPart,
+ beamBetween,
+ createLadder,
+ createWingPair,
// geometries
boxGeo,
sphereGeo,
cylinderGeo,
+ cylinderXGeo,
+ cylinderZGeo,
coneGeo,
+ coneXGeo,
+ coneZGeo,
capsuleGeo,
+ capsuleXGeo,
+ capsuleZGeo,
torusGeo,
planeGeo,
+ wingGeo,
// materials
gameMaterial,
basicMaterial,
@@ -53,6 +63,13 @@ import {
buildSandboxGlobals,
} from '../primitives';
+function geometrySize(geometry: THREE.BufferGeometry): THREE.Vector3 {
+ geometry.computeBoundingBox();
+ const size = new THREE.Vector3();
+ geometry.boundingBox!.getSize(size);
+ return size;
+}
+
// =============================================================================
// Construction primitives
// =============================================================================
@@ -130,6 +147,77 @@ describe('createRoot / createPivot / createPart', () => {
});
});
+describe('attachment helpers', () => {
+ test('beamBetween creates a named cylinder centered between endpoints', () => {
+ const root = createRoot('R');
+ const beam = beamBetween(
+ 'Brace',
+ [1, 0, 0],
+ [1, 2, 0],
+ 0.05,
+ gameMaterial(0x333333),
+ { parent: root, segments: 6 }
+ ) as THREE.Mesh;
+
+ expect(beam.name).toBe('Mesh_Brace');
+ expect(beam.parent).toBe(root);
+ expect(beam.position.x).toBeCloseTo(1);
+ expect(beam.position.y).toBeCloseTo(1);
+ expect(beam.position.z).toBeCloseTo(0);
+ expect(geometrySize(beam.geometry).y).toBeCloseTo(2);
+ });
+
+ test('beamBetween rejects zero-length beams', () => {
+ expect(() =>
+ beamBetween('Bad', [0, 0, 0], [0, 0, 0], 0.05, gameMaterial(0x333333))
+ ).toThrow('start and end must be different points');
+ });
+
+ test('createLadder creates two continuous rails and evenly named rungs', () => {
+ const root = createRoot('R');
+ const ladder = createLadder('TowerLadder', {
+ bottom: [0, 0, 0],
+ top: [0, 2, 0],
+ width: 0.5,
+ rungCount: 4,
+ material: gameMaterial(0x555555),
+ parent: root,
+ });
+
+ expect(ladder.leftRail.name).toBe('Mesh_TowerLadderLeftRail');
+ expect(ladder.rightRail.name).toBe('Mesh_TowerLadderRightRail');
+ expect(ladder.rungs.map((r) => r.name)).toEqual([
+ 'Mesh_TowerLadderRung1',
+ 'Mesh_TowerLadderRung2',
+ 'Mesh_TowerLadderRung3',
+ 'Mesh_TowerLadderRung4',
+ ]);
+ expect(root.children.length).toBe(6);
+ });
+
+ test('createWingPair attaches mirrored wing roots at +/-rootZ', () => {
+ const root = createRoot('Aircraft');
+ const wings = createWingPair('MainWing', gameMaterial(0x556b2f), {
+ rootZ: 0.45,
+ rootX: 0.1,
+ rootY: 1.0,
+ span: 2,
+ rootChord: 0.8,
+ tipChord: 0.3,
+ sweep: 0.25,
+ dihedral: 0.08,
+ parent: root,
+ });
+
+ expect(wings.right.name).toBe('Mesh_MainWingRight');
+ expect(wings.left.name).toBe('Mesh_MainWingLeft');
+ expect(wings.right.position.z).toBeCloseTo(0.45);
+ expect(wings.left.position.z).toBeCloseTo(-0.45);
+ expect(root.children).toContain(wings.right);
+ expect(root.children).toContain(wings.left);
+ });
+});
+
// =============================================================================
// Geometry primitives
// =============================================================================
@@ -155,18 +243,43 @@ describe('geometry primitives produce real Three.js geometries', () => {
expect(g.parameters.radialSegments).toBe(12);
});
+ test('axis-specific cylinder helpers align length to requested axis', () => {
+ const x = geometrySize(cylinderXGeo(0.2, 0.2, 2, 12));
+ const z = geometrySize(cylinderZGeo(0.2, 0.2, 3, 12));
+ expect(x.x).toBeCloseTo(2);
+ expect(x.y).toBeLessThan(0.5);
+ expect(z.z).toBeCloseTo(3);
+ expect(z.y).toBeLessThan(0.5);
+ });
+
test('coneGeo with default segments', () => {
const g = coneGeo(1, 2);
expect(g).toBeInstanceOf(THREE.ConeGeometry);
expect(g.parameters.radialSegments).toBe(8);
});
+ test('axis-specific cone helpers point toward +X and +Z', () => {
+ const x = coneXGeo(0.5, 2, 8);
+ const z = coneZGeo(0.5, 2, 8);
+ const xSize = geometrySize(x);
+ const zSize = geometrySize(z);
+ expect(xSize.x).toBeCloseTo(2);
+ expect(zSize.z).toBeCloseTo(2);
+ });
+
test('capsuleGeo with default segments', () => {
const g = capsuleGeo(0.5, 1);
expect(g).toBeInstanceOf(THREE.CapsuleGeometry);
expect(g.getAttribute('position').count).toBeGreaterThan(0);
});
+ test('axis-specific capsule helpers align length to requested axis', () => {
+ const x = geometrySize(capsuleXGeo(0.2, 2, 6));
+ const z = geometrySize(capsuleZGeo(0.2, 3, 6));
+ expect(x.x).toBeGreaterThan(x.y);
+ expect(z.z).toBeGreaterThan(z.y);
+ });
+
test('torusGeo with custom segments', () => {
const g = torusGeo(1, 0.25, 16, 24);
expect(g).toBeInstanceOf(THREE.TorusGeometry);
@@ -178,6 +291,23 @@ describe('geometry primitives produce real Three.js geometries', () => {
const g = planeGeo(2, 2);
expect(g).toBeInstanceOf(THREE.PlaneGeometry);
});
+
+ test('wingGeo builds a swept trapezoid panel extending along +Z', () => {
+ const g = wingGeo({
+ span: 2,
+ rootChord: 0.8,
+ tipChord: 0.3,
+ sweep: 0.25,
+ thickness: 0.06,
+ dihedral: 0.08,
+ });
+ const size = geometrySize(g);
+
+ expect(g).toBeInstanceOf(THREE.BufferGeometry);
+ expect(size.z).toBeCloseTo(2);
+ expect(size.x).toBeGreaterThan(0.75);
+ expect(size.y).toBeGreaterThan(0.05);
+ });
});
// =============================================================================
@@ -454,8 +584,11 @@ describe('buildSandboxGlobals', () => {
const globals = buildSandboxGlobals();
const expected = [
'createRoot', 'createPivot', 'createPart',
- 'capsuleGeo', 'cylinderGeo', 'boxGeo', 'sphereGeo', 'coneGeo',
- 'torusGeo', 'planeGeo',
+ 'beamBetween', 'createLadder', 'createWingPair',
+ 'capsuleGeo', 'capsuleXGeo', 'capsuleZGeo',
+ 'cylinderGeo', 'cylinderXGeo', 'cylinderZGeo',
+ 'boxGeo', 'sphereGeo', 'coneGeo', 'coneXGeo', 'coneZGeo',
+ 'torusGeo', 'planeGeo', 'wingGeo',
'gameMaterial', 'basicMaterial', 'glassMaterial', 'lambertMaterial',
'rotationTrack', 'positionTrack', 'scaleTrack', 'createClip',
'spinAnimation', 'bobbingAnimation', 'idleBreathing',
diff --git a/index.ts b/index.ts
index 186c0e02..58483b79 100644
--- a/index.ts
+++ b/index.ts
@@ -71,12 +71,22 @@ export {
createPivot,
createPart,
capsuleGeo,
+ capsuleXGeo,
+ capsuleZGeo,
cylinderGeo,
+ cylinderXGeo,
+ cylinderZGeo,
boxGeo,
sphereGeo,
coneGeo,
+ coneXGeo,
+ coneZGeo,
torusGeo,
planeGeo,
+ wingGeo,
+ createWingPair,
+ beamBetween,
+ createLadder,
gameMaterial,
basicMaterial,
glassMaterial,
diff --git a/list-primitives.ts b/list-primitives.ts
index 327cbd9c..b2ed8e75 100644
--- a/list-primitives.ts
+++ b/list-primitives.ts
@@ -6,7 +6,7 @@
* discover the surface without reading `primitives.ts` directly.
*
* The list is hand-authored rather than JSDoc-parsed — the catalog is
- * small (25 entries) and hand-authoring gives cleaner `signature` /
+ * small and hand-authoring gives cleaner `signature` /
* `example` strings than we'd get from TS AST extraction. Drift is caught
* by `__tests__/list-primitives.test.ts` which asserts every entry
* matches a real sandbox global.
@@ -71,6 +71,39 @@ const PRIMITIVES: PrimitiveSpec[] = [
example:
"createPart('Barrel', cylinderGeo(0.1, 0.1, 1), gameMaterial(0x556b2f), { position: [0, 0.5, 0], parent: root });",
},
+ {
+ name: 'beamBetween',
+ signature:
+ 'beamBetween(name, start: [x,y,z], end: [x,y,z], radius, material, opts?: { segments, parent })',
+ returns: 'THREE.Object3D (prefixed `Mesh_`)',
+ category: 'structure',
+ description:
+ 'Creates a cylindrical rail/strut exactly between two endpoints. Use for braces, gun barrels, skid struts, cables, and scaffolding.',
+ example:
+ "beamBetween('SkidBraceA', [0.8, 0.3, 0.7], [0.8, 1.0, 0.45], 0.025, black, { parent: root });",
+ },
+ {
+ name: 'createLadder',
+ signature:
+ "createLadder(name, { bottom, top, material, width?, rungCount?, railRadius?, rungRadius?, widthAxis?, parent? })",
+ returns: '{ leftRail: Object3D, rightRail: Object3D, rungs: Object3D[] }',
+ category: 'structure',
+ description:
+ 'Builds two continuous rails plus evenly-spaced rungs. Use this instead of loose boxes for ladders.',
+ example:
+ "createLadder('TowerLadder', { bottom: [0,0,0], top: [0,2.2,0], width: 0.45, rungCount: 7, material: steel, parent: root });",
+ },
+ {
+ name: 'createWingPair',
+ signature:
+ 'createWingPair(name, material, { rootZ, span, rootChord, tipChord, sweep?, thickness?, dihedral?, rootX?, rootY?, parent? })',
+ returns: '{ right: Object3D, left: Object3D }',
+ category: 'structure',
+ description:
+ 'Creates mirrored trapezoid aircraft wings with roots attached at +/-rootZ. Use for aircraft wings and helicopter stub wings.',
+ example:
+ "createWingPair('MainWing', olive, { rootX: 0, rootY: 1.0, rootZ: 0.42, span: 2.4, rootChord: 0.9, tipChord: 0.35, sweep: 0.25, dihedral: 0.08, parent: root });",
+ },
// ---------------------------------------------------------------------------
// Geometry
@@ -102,6 +135,26 @@ const PRIMITIVES: PrimitiveSpec[] = [
'Y-axis cylinder. Use radiusTop != radiusBottom for cones / tapered pieces.',
example: 'const geo = cylinderGeo(0.25, 0.25, 1, 12);',
},
+ {
+ name: 'cylinderXGeo',
+ signature:
+ 'cylinderXGeo(radiusTop: number, radiusBottom: number, length: number, segments?: 8)',
+ returns: 'THREE.CylinderGeometry',
+ category: 'geometry',
+ description:
+ 'Cylinder pre-rotated to run along +X/-X. Use for fuselages, cannons, barrels, axles, and forward-facing tubes.',
+ example: 'const geo = cylinderXGeo(0.1, 0.1, 1.2, 12);',
+ },
+ {
+ name: 'cylinderZGeo',
+ signature:
+ 'cylinderZGeo(radiusTop: number, radiusBottom: number, length: number, segments?: 8)',
+ returns: 'THREE.CylinderGeometry',
+ category: 'geometry',
+ description:
+ 'Cylinder pre-rotated to run along +Z/-Z. Use for side-mounted weapons, rails, crossbars, and pipes.',
+ example: 'const geo = cylinderZGeo(0.08, 0.08, 0.9, 10);',
+ },
{
name: 'capsuleGeo',
signature: 'capsuleGeo(radius: number, height: number, segments?: 6)',
@@ -110,6 +163,24 @@ const PRIMITIVES: PrimitiveSpec[] = [
description: 'Stadium shape (cylinder with hemispherical caps). Good for limbs.',
example: 'const geo = capsuleGeo(0.1, 0.5, 6);',
},
+ {
+ name: 'capsuleXGeo',
+ signature: 'capsuleXGeo(radius: number, length: number, segments?: 6)',
+ returns: 'THREE.CapsuleGeometry',
+ category: 'geometry',
+ description:
+ 'Capsule pre-rotated to run along +X/-X. Use for aircraft bodies, rounded vehicle hulls, and missiles.',
+ example: 'const geo = capsuleXGeo(0.35, 2.4, 10);',
+ },
+ {
+ name: 'capsuleZGeo',
+ signature: 'capsuleZGeo(radius: number, length: number, segments?: 6)',
+ returns: 'THREE.CapsuleGeometry',
+ category: 'geometry',
+ description:
+ 'Capsule pre-rotated to run along +Z/-Z. Use for lateral pods, floats, and side tanks.',
+ example: 'const geo = capsuleZGeo(0.18, 1.1, 8);',
+ },
{
name: 'coneGeo',
signature: 'coneGeo(radius: number, height: number, segments?: 8)',
@@ -118,6 +189,24 @@ const PRIMITIVES: PrimitiveSpec[] = [
description: 'Y-axis cone (pointed up). Use for spikes, roofs, projectiles.',
example: 'const geo = coneGeo(0.3, 0.8, 8);',
},
+ {
+ name: 'coneXGeo',
+ signature: 'coneXGeo(radius: number, length: number, segments?: 8)',
+ returns: 'THREE.ConeGeometry',
+ category: 'geometry',
+ description:
+ 'Cone pre-rotated so its point faces +X. Use for noses, rockets, shells, and forward-facing tips.',
+ example: 'const geo = coneXGeo(0.18, 0.45, 12);',
+ },
+ {
+ name: 'coneZGeo',
+ signature: 'coneZGeo(radius: number, length: number, segments?: 8)',
+ returns: 'THREE.ConeGeometry',
+ category: 'geometry',
+ description:
+ 'Cone pre-rotated so its point faces +Z. Use for side-facing projectiles and tips.',
+ example: 'const geo = coneZGeo(0.12, 0.35, 10);',
+ },
{
name: 'torusGeo',
signature:
@@ -136,6 +225,17 @@ const PRIMITIVES: PrimitiveSpec[] = [
description: 'Flat quad. Faces +Z by default. Rotate to use as ground / decal.',
example: 'const geo = planeGeo(4, 4);',
},
+ {
+ name: 'wingGeo',
+ signature:
+ 'wingGeo(opts?: { span, rootChord, tipChord, sweep, thickness, dihedral })',
+ returns: 'THREE.BufferGeometry',
+ category: 'geometry',
+ description:
+ 'Trapezoid wing panel. Local root edge is at Z=0, span extends toward +Z, positive sweep moves the tip aft along -X.',
+ example:
+ 'const geo = wingGeo({ span: 2.2, rootChord: 0.8, tipChord: 0.3, sweep: 0.25, dihedral: 0.08 });',
+ },
{
name: 'gearGeo',
signature:
diff --git a/primitives.ts b/primitives.ts
index 4bd5da91..4967c4f3 100644
--- a/primitives.ts
+++ b/primitives.ts
@@ -11,6 +11,12 @@
import * as THREE from 'three';
+type Vec3Tuple = [number, number, number];
+
+function vectorToTuple(v: THREE.Vector3): Vec3Tuple {
+ return [v.x, v.y, v.z];
+}
+
// =============================================================================
// Geometry Helpers
// =============================================================================
@@ -96,6 +102,26 @@ export function capsuleGeo(
return new THREE.CapsuleGeometry(radius, height, 2, segments);
}
+export function capsuleXGeo(
+ radius: number,
+ length: number,
+ segments = 6
+): THREE.CapsuleGeometry {
+ const geo = capsuleGeo(radius, length, segments);
+ geo.rotateZ(-Math.PI / 2);
+ return geo;
+}
+
+export function capsuleZGeo(
+ radius: number,
+ length: number,
+ segments = 6
+): THREE.CapsuleGeometry {
+ const geo = capsuleGeo(radius, length, segments);
+ geo.rotateX(Math.PI / 2);
+ return geo;
+}
+
export function cylinderGeo(
radiusTop: number,
radiusBottom: number,
@@ -105,6 +131,28 @@ export function cylinderGeo(
return new THREE.CylinderGeometry(radiusTop, radiusBottom, height, segments);
}
+export function cylinderXGeo(
+ radiusTop: number,
+ radiusBottom: number,
+ length: number,
+ segments = 8
+): THREE.CylinderGeometry {
+ const geo = cylinderGeo(radiusTop, radiusBottom, length, segments);
+ geo.rotateZ(-Math.PI / 2);
+ return geo;
+}
+
+export function cylinderZGeo(
+ radiusTop: number,
+ radiusBottom: number,
+ length: number,
+ segments = 8
+): THREE.CylinderGeometry {
+ const geo = cylinderGeo(radiusTop, radiusBottom, length, segments);
+ geo.rotateX(Math.PI / 2);
+ return geo;
+}
+
export function boxGeo(
width: number,
height: number,
@@ -129,6 +177,26 @@ export function coneGeo(
return new THREE.ConeGeometry(radius, height, segments);
}
+export function coneXGeo(
+ radius: number,
+ length: number,
+ segments = 8
+): THREE.ConeGeometry {
+ const geo = coneGeo(radius, length, segments);
+ geo.rotateZ(-Math.PI / 2);
+ return geo;
+}
+
+export function coneZGeo(
+ radius: number,
+ length: number,
+ segments = 8
+): THREE.ConeGeometry {
+ const geo = coneGeo(radius, length, segments);
+ geo.rotateX(Math.PI / 2);
+ return geo;
+}
+
export function torusGeo(
radius: number,
tube: number,
@@ -147,6 +215,209 @@ export function planeGeo(
return new THREE.PlaneGeometry(width, height, widthSegments, heightSegments);
}
+export interface WingGeometryOptions {
+ span?: number;
+ rootChord?: number;
+ tipChord?: number;
+ sweep?: number;
+ thickness?: number;
+ dihedral?: number;
+}
+
+/**
+ * Trapezoid aircraft wing panel.
+ *
+ * Coordinate contract: +X forward, +Y up, +Z right. The root edge sits at
+ * local Z=0 and the panel extends toward +Z. Positive sweep moves the tip aft
+ * along -X. Positive dihedral raises the tip along +Y.
+ */
+export function wingGeo(options: WingGeometryOptions = {}): THREE.BufferGeometry {
+ const span = options.span ?? 1;
+ const rootChord = options.rootChord ?? 0.6;
+ const tipChord = options.tipChord ?? rootChord * 0.5;
+ const sweep = options.sweep ?? 0;
+ const thickness = options.thickness ?? 0.04;
+ const dihedral = options.dihedral ?? 0;
+
+ const rootLead = rootChord / 2;
+ const rootTrail = -rootChord / 2;
+ const tipLead = rootLead - sweep;
+ const tipTrail = tipLead - tipChord;
+ const halfThickness = thickness / 2;
+
+ const vertices = new Float32Array([
+ rootLead, halfThickness, 0,
+ rootTrail, halfThickness, 0,
+ tipLead, dihedral + halfThickness, span,
+ tipTrail, dihedral + halfThickness, span,
+ rootLead, -halfThickness, 0,
+ rootTrail, -halfThickness, 0,
+ tipLead, dihedral - halfThickness, span,
+ tipTrail, dihedral - halfThickness, span,
+ ]);
+
+ const indices = [
+ 0, 3, 2, 0, 1, 3, // top
+ 4, 6, 7, 4, 7, 5, // bottom
+ 0, 2, 6, 0, 6, 4, // leading edge
+ 1, 5, 7, 1, 7, 3, // trailing edge
+ 0, 4, 5, 0, 5, 1, // root cap
+ 2, 3, 7, 2, 7, 6, // tip cap
+ ];
+
+ const geo = new THREE.BufferGeometry();
+ geo.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
+ geo.setIndex(indices);
+ geo.computeVertexNormals();
+ return geo;
+}
+
+export interface WingPairOptions extends WingGeometryOptions {
+ rootX?: number;
+ rootY?: number;
+ /** Fuselage half-width / root offset. Roots attach at +/-rootZ. */
+ rootZ: number;
+ parent?: THREE.Object3D;
+}
+
+export function createWingPair(
+ name: string,
+ material: THREE.Material,
+ options: WingPairOptions
+): { right: THREE.Object3D; left: THREE.Object3D } {
+ const { parent, rootX = 0, rootY = 0, rootZ, ...wingOptions } = options;
+ const rightGeo = wingGeo(wingOptions);
+ const leftGeo = wingGeo(wingOptions);
+ leftGeo.scale(1, 1, -1);
+ leftGeo.computeVertexNormals();
+
+ return {
+ right: createPart(`${name}Right`, rightGeo, material, {
+ position: [rootX, rootY, rootZ],
+ parent,
+ }),
+ left: createPart(`${name}Left`, leftGeo, material, {
+ position: [rootX, rootY, -rootZ],
+ parent,
+ }),
+ };
+}
+
+export interface BeamBetweenOptions {
+ segments?: number;
+ parent?: THREE.Object3D;
+}
+
+export function beamBetween(
+ name: string,
+ start: Vec3Tuple,
+ end: Vec3Tuple,
+ radius: number,
+ material: THREE.Material,
+ options: BeamBetweenOptions = {}
+): THREE.Object3D {
+ const a = new THREE.Vector3(...start);
+ const b = new THREE.Vector3(...end);
+ const direction = b.clone().sub(a);
+ const length = direction.length();
+
+ if (length <= 0) {
+ throw new Error(`beamBetween("${name}"): start and end must be different points`);
+ }
+
+ const mesh = new THREE.Mesh(
+ cylinderGeo(radius, radius, length, options.segments ?? 8),
+ material
+ );
+ mesh.name = `Mesh_${name}`;
+ mesh.position.copy(a.add(b).multiplyScalar(0.5));
+ mesh.quaternion.setFromUnitVectors(
+ new THREE.Vector3(0, 1, 0),
+ direction.normalize()
+ );
+
+ if (options.parent) options.parent.add(mesh);
+ return mesh;
+}
+
+export interface LadderOptions {
+ bottom: Vec3Tuple;
+ top: Vec3Tuple;
+ material: THREE.Material;
+ width?: number;
+ rungCount?: number;
+ railRadius?: number;
+ rungRadius?: number;
+ segments?: number;
+ widthAxis?: 'x' | 'z';
+ parent?: THREE.Object3D;
+}
+
+export function createLadder(
+ name: string,
+ options: LadderOptions
+): { leftRail: THREE.Object3D; rightRail: THREE.Object3D; rungs: THREE.Object3D[] } {
+ const {
+ bottom,
+ top,
+ material,
+ width = 0.42,
+ rungCount = 6,
+ railRadius = 0.025,
+ rungRadius = 0.02,
+ segments = 6,
+ widthAxis = 'x',
+ parent,
+ } = options;
+
+ const bottomVec = new THREE.Vector3(...bottom);
+ const topVec = new THREE.Vector3(...top);
+ const offset =
+ widthAxis === 'x'
+ ? new THREE.Vector3(width / 2, 0, 0)
+ : new THREE.Vector3(0, 0, width / 2);
+
+ const leftBottom = bottomVec.clone().sub(offset);
+ const leftTop = topVec.clone().sub(offset);
+ const rightBottom = bottomVec.clone().add(offset);
+ const rightTop = topVec.clone().add(offset);
+
+ const leftRail = beamBetween(
+ `${name}LeftRail`,
+ vectorToTuple(leftBottom),
+ vectorToTuple(leftTop),
+ railRadius,
+ material,
+ { parent, segments }
+ );
+ const rightRail = beamBetween(
+ `${name}RightRail`,
+ vectorToTuple(rightBottom),
+ vectorToTuple(rightTop),
+ railRadius,
+ material,
+ { parent, segments }
+ );
+
+ const rungs: THREE.Object3D[] = [];
+ for (let i = 0; i < rungCount; i++) {
+ const t = (i + 1) / (rungCount + 1);
+ const center = bottomVec.clone().lerp(topVec, t);
+ rungs.push(
+ beamBetween(
+ `${name}Rung${i + 1}`,
+ vectorToTuple(center.clone().sub(offset)),
+ vectorToTuple(center.clone().add(offset)),
+ rungRadius,
+ material,
+ { parent, segments }
+ )
+ );
+ }
+
+ return { leftRail, rightRail, rungs };
+}
+
// =============================================================================
// Materials
// =============================================================================
@@ -553,12 +824,22 @@ export function buildSandboxGlobals(
createPivot: wrap('createPivot', createPivot),
createPart: wrap('createPart', createPart),
capsuleGeo: wrap('capsuleGeo', capsuleGeo),
+ capsuleXGeo: wrap('capsuleXGeo', capsuleXGeo),
+ capsuleZGeo: wrap('capsuleZGeo', capsuleZGeo),
cylinderGeo: wrap('cylinderGeo', cylinderGeo),
+ cylinderXGeo: wrap('cylinderXGeo', cylinderXGeo),
+ cylinderZGeo: wrap('cylinderZGeo', cylinderZGeo),
boxGeo: wrap('boxGeo', boxGeo),
sphereGeo: wrap('sphereGeo', sphereGeo),
coneGeo: wrap('coneGeo', coneGeo),
+ coneXGeo: wrap('coneXGeo', coneXGeo),
+ coneZGeo: wrap('coneZGeo', coneZGeo),
torusGeo: wrap('torusGeo', torusGeo),
planeGeo: wrap('planeGeo', planeGeo),
+ wingGeo: wrap('wingGeo', wingGeo),
+ createWingPair: wrap('createWingPair', createWingPair),
+ beamBetween: wrap('beamBetween', beamBetween),
+ createLadder: wrap('createLadder', createLadder),
gameMaterial: wrap('gameMaterial', gameMaterial),
basicMaterial: wrap('basicMaterial', basicMaterial),
glassMaterial: wrap('glassMaterial', glassMaterial),
diff --git a/prompt.ts b/prompt.ts
index c60ea076..f46d014d 100644
--- a/prompt.ts
+++ b/prompt.ts
@@ -95,6 +95,18 @@ function animate(root) { // optional
}
</file-format>
+<coordinate-contract>
+World coordinates are strict:
+- +X = forward / nose / muzzle direction
+- +Y = up
+- +Z = asset right side
+- Ground rests at Y=0
+
+Vehicles, aircraft, weapons, boats, and buildings must follow this frame. If a
+part points forward, build it along +X. If a part spans left/right, build it
+along Z. Do not make each asset invent its own forward axis.
+</coordinate-contract>
+
<api>
// Scene (no imports needed - globals)
createRoot(name: string): Object3D
@@ -109,14 +121,26 @@ createPart("Name", geometry, material, { position: [x,y,z], parent: parentObj })
// Geometry (returns BufferGeometry)
boxGeo(width, height, depth)
sphereGeo(radius, widthSegs=8, heightSegs=6)
-cylinderGeo(radiusTop, radiusBot, height, segments=8)
-coneGeo(radius, height, segments=8)
-capsuleGeo(radius, height, segments=6)
+cylinderGeo(radiusTop, radiusBot, height, segments=8) // Y-axis
+cylinderXGeo(radiusTop, radiusBot, length, segments=8) // X-axis
+cylinderZGeo(radiusTop, radiusBot, length, segments=8) // Z-axis
+coneGeo(radius, height, segments=8) // Y-axis, point +Y
+coneXGeo(radius, length, segments=8) // point +X
+coneZGeo(radius, length, segments=8) // point +Z
+capsuleGeo(radius, height, segments=6) // Y-axis
+capsuleXGeo(radius, length, segments=6) // X-axis
+capsuleZGeo(radius, length, segments=6) // Z-axis
torusGeo(radius, tube, radialSegs=8, tubularSegs=12)
planeGeo(width, height, widthSegs=1, heightSegs=1)
+wingGeo({ span, rootChord, tipChord, sweep, thickness, dihedral }) // root at Z=0, span extends +Z
gearGeo({ teeth=12, rootRadius=0.8, tipRadius=1.0, boreRadius=0.2, height=0.3, toothWidthFrac=0.5 }) // parametric gear, flat-shaded
bladeGeo({ length=1.5, baseWidth=0.1, thickness=0.015, tipLength=0.25, edgeBevel=0 }) // tapered sword blade with pointed tip
+// Attachment helpers
+beamBetween(name, start: [x,y,z], end: [x,y,z], radius, material, { segments?, parent? })
+createLadder(name, { bottom, top, material, width?, rungCount?, railRadius?, rungRadius?, widthAxis?, parent? })
+createWingPair(name, material, { rootZ, span, rootChord, tipChord, sweep?, thickness?, dihedral?, rootX?, rootY?, parent? })
+
// Materials
gameMaterial(0xcolor, {metalness?, roughness?, emissive?, flatShading?})
lambertMaterial(0xcolor, {flatShading?, emissive?})
@@ -199,9 +223,29 @@ For animations, track names must use "Joint_" prefix:
- Name parts descriptively (Body, LeftArm, Wheel)
</quality>
+<attachment-rules>
+- Use cylinderXGeo / capsuleXGeo / coneXGeo for forward-facing bodies, barrels,
+ aircraft fuselages, missiles, and weapon muzzles. Do not hand-rotate Y-axis
+ cylinders unless you have a specific reason.
+- Use cylinderZGeo / capsuleZGeo / coneZGeo for side-facing rails, pods, floats,
+ and crossbars.
+- Use beamBetween() for struts, braces, cables, skid supports, scaffolding, and
+ diagonal rails. Endpoints must touch the parts they connect to.
+- Use createLadder() for ladders. A ladder must have two continuous rails and
+ repeated rungs spanning between those rails. Do not fake ladders with random
+ boxes.
+- Use createWingPair() for aircraft wings and helicopter stub wings. Set rootZ
+ to the fuselage half-width so the wing roots touch the body. Wings must not
+ float near the body, pass through the centerline, or angle as detached planks.
+- Any visually-attached part should overlap or touch its parent by about 0.02
+ units. Floating parts are invalid even if the named-parts check passes.
+- Low triangle count is not the goal by itself. Spend triangles where silhouette
+ matters: cockpits, wheels, rotors, wings, organic rocks, and curved aircraft.
+</attachment-rules>
+
<rules>
- Colors as hex: 0xff0000
-- Y-up, ground at Y=0
+- Coordinates: +X forward, +Y up, +Z right, ground at Y=0
- Animate pivots only (Joint_* names)
- Loops: end keyframe = start keyframe
- Track names: "Joint_Name" format (must exist in scene)