Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

8.6 KB
Raw Blame

If you know three.js

67js does not copy the three.js API, but every common three.js idea has a 67js call. This page maps one to the other. A test checks that each 67js name below exists, so the page cannot drift from the code.

The main difference: three.js keeps a tree of objects that you change. 67js keeps a flat list of parts, which are plain objects with a name, a geometry, a 16 number matrix and a material. You change the list and call renderer.updateParts(parts), then draw with renderer.render(frame). The camera and the lights are not objects in the scene. They are fields of the frame and of the environment option.

If you would rather write three.js-shaped code, the optional addon packages/three-compat accepts the common names and builds the 67js parts for you. It is at the end of this page.

Scene, objects and meshes

three.js 67js
new THREE.Scene() A parts array: const parts = [].
new THREE.Group() A shared matrix. Multiply it into each child matrix, or use createSceneGraph(), which keeps named nodes with a parent and retained world matrices.
new THREE.Mesh(geometry, material) A part { name, geometry, matrix, material }. name must be unique.
scene.add(mesh) parts.push(part), then new Renderer67(canvas, parts).
mesh.position.set(x, y, z) The last four numbers of part.matrix: matrix[12], matrix[13], matrix[14].
mesh.rotation, mesh.scale The other numbers of part.matrix, which is column-major.
Change a mesh after the first frame Change the part, then call renderer.updateParts(parts).

Geometry

three.js 67js
new THREE.BoxGeometry(w, h, d) box() is a cube of side 1 with rounded edges. Scale it in the matrix, and use box(0) for sharp edges.
new THREE.SphereGeometry(radius, widthSegments, heightSegments) sphere(segments, rings) has radius 1. Scale it in the matrix.
new THREE.CylinderGeometry(r, r, height, segments) cylinder(segments) has radius 1 and height 1.
new THREE.TorusGeometry(radius, tube) torus(tubeRadius) has a ring radius of 1. tubeRadius is tube / radius.
new THREE.PlaneGeometry(w, h) box(0) scaled flat.
new THREE.ConeGeometry() createModel() from 67js/addons/model.
new THREE.BufferGeometry() An object with positions, normals and indices. See Parts and geometry.

Materials

three.js 67js
new THREE.MeshStandardMaterial({ color, metalness, roughness }) material: { color, metallic, roughness }. color is three linear numbers from 0 to 1, not a hex number.
emissive and emissiveIntensity material.emission and material.emissiveColor.
map, normalMap material.map and material.normalMap, each { image, colorSpace }.
transparent and opacity material.alphaMode set to 'blend', and material.opacity.
alphaTest material.alphaMode set to 'mask', and material.alphaCutoff.
side: THREE.DoubleSide material.doubleSided set to true.
new THREE.MeshPhysicalMaterial({ clearcoat, transmission, ior }) The same material with material.clearcoat, material.transmission and material.ior. The fields are listed in docs/material-maps.md in the repository.
ShaderMaterial None. 67js has no custom shaders.

Cameras

The camera is a frame passed to renderer.render(frame).

three.js 67js
new THREE.PerspectiveCamera(fov, aspect, near, far) renderer.render({ eye, target, fov, near, far }). frame.fov is the vertical angle in degrees. The aspect comes from the canvas.
new THREE.OrthographicCamera(...) frame.projection set to 'orthographic', and frame.orthographicHeight.
camera.position.set(x, y, z) frame.eye.
camera.lookAt(x, y, z) frame.target.
camera.up frame.up.
renderer.setSize(w, h) and a window resize handler Size the canvas in CSS, then call renderer.resize().
camera.updateProjectionMatrix() Not needed. renderer.render() reads the frame every time.

Lights

The lights are fields of the environment option of Renderer67, or of frame.environment for one frame. The studio rig (a key light, two fills and ambient light) is on by default.

three.js 67js
new THREE.AmbientLight(color, intensity) environment.ambientIntensity.
new THREE.HemisphereLight() environment.ambientIntensity.
new THREE.DirectionalLight(color, intensity) environment.lightDirection, environment.keyIntensity and environment.keyColor. It casts shadows.
new THREE.PointLight(color, intensity, distance) An entry of environment.pointLights: { position, color, intensity, range }. At most 16.
new THREE.SpotLight(...) An entry of environment.spotLights: { position, direction, angle, penumbra, intensity }. At most 8.
new THREE.RectAreaLight(...) An entry of environment.areaLights: { position, direction, width, height, intensity }. At most 7.
light.castShadow = true castShadow: true on a point, spot or area light. The key light always casts.
scene.background environment.skyTop and environment.skyBottom.
scene.fog environment.fogColor and environment.fogDensity.

Light units differ, so a copied intensity is not the same brightness. Tune by eye. The lighting contract lists the fields.

Loaders

three.js 67js
new GLTFLoader().load(url, onLoad) loadGltf(url) from 67js/addons/gltf. It returns an asset, and asset.parts are ordinary parts.
gltf.scene asset.parts.
gltf.animations and new THREE.AnimationMixer(scene) createAnimationMixer(parts), or createAnimationPlayer(clip, parts).
DRACOLoader, KTX2Loader The decoders option of loadGltf. See Import and export models.
new THREE.TextureLoader().load(url) Load an Image yourself and put it in material.map.
RGBELoader and scene.environment createEnvironmentMap() and the environment.map option.

The render loop

three.js 67js
renderer.setAnimationLoop(fn) Call requestAnimationFrame yourself, change the parts, call renderer.updateParts(parts) and renderer.render(frame).
renderer.render(scene, camera) renderer.render(frame).
new THREE.Clock() and clock.getDelta() performance.now(). For motion that must repeat exactly, pass absolute time to sampleAnimationClip().
renderer.setPixelRatio(ratio) The pixelRatio option of Renderer67.
renderer.dispose() renderer.dispose().
new THREE.WebGLRenderer({ antialias: true }) new Renderer67(canvas, parts, { samples: 4 }).

Controls and render targets

three.js 67js
new OrbitControls(camera, canvas) Keep a yaw, a pitch and a distance, then compute frame.eye from them on pointermove and wheel. Cameras and framing has the code. cameraView() and fitPerspectiveDistance() frame a subject.
new THREE.WebGLRenderTarget(w, h) None. Renderer67 draws to its canvas. Read the picture with canvas.toBlob(). For a PNG job in an agent, use the scene_render_submit tool.
EffectComposer and passes frame.effects, built with resolveEffects().
renderer.shadowMap.enabled Shadows are always on. A part leaves them with castShadow: false.

Names the addon refuses

packages/three-compat is an optional addon that accepts the common three.js names and builds 67js parts, materials, cameras and lights from them. It has no import of three and no dependency on the core: you pass it the 67js exports.

import * as core from '67js';
import { loadGltf } from '67js/addons/gltf';
import { createThreeCompat } from '@codepawlhq/67js-three-compat';

const THREE = createThreeCompat({ ...core, loadGltf });

It accepts Scene, Group, Mesh, the box, plane, sphere, cylinder and torus geometries, MeshStandardMaterial, MeshPhysicalMaterial, both cameras, the light classes, GLTFLoader, OrbitControls and WebGLRenderer with setAnimationLoop. For any other three.js name it throws an error that names the 67js call to use. For example, THREE.MeshBasicMaterial tells you to use MeshStandardMaterial with emissive, which is material.emission in 67js.

To move a scene you already have, the three.js bridge imports a three.js object tree as 67js parts and builds three.js meshes from parts.

The addon is a bridge for code that an agent writes from memory. For new code, write parts directly: it is shorter and has no extra layer.