Write your own World
world.html is a plain HTML page. Anything the scene kit
cannot draw (a machine, a room, a game, a custom robot) can be a page of your
own, written by hand or by an AI.
With an AI
Section titled “With an AI”Press Copy AI prompt, in the 3D introduction or in the World bar. The prompt is a complete brief, built from your project at that moment:
- Your project, read from the canvas: every board, every part (with short settings such as an LED’s colour), the wiring as nets (which pins are joined, through breadboards too), and the firmware files.
- What a World can read and write, for the parts you have and for every part a World supports, so the AI can tell you which part to add and how to wire it.
- The rules: where the page runs, the
window.velxioAPI, physics on simulated time, and both ways to write a World (a kit scene or a free page). - How to answer: the complete
world.html, the new firmware if it has to change, and the wiring changes pin to pin.
Paste it into ChatGPT, Claude, Gemini or any other chat, and write what you want to build at the end, in any language. For example, with an ESP32 and four servos on the canvas: “a robot arm that picks the red cube and drops it in the box”. Then open the World, switch to HTML, replace everything with the answer and press Run.
Where the page runs
Section titled “Where the page runs”- A sandboxed iframe with no access to Velxio’s API, your account or your
cookies.
localStoragemay be missing. - Scripts and styles load only from
cdn.jsdelivr.net,cdnjs.cloudflare.com,unpkg.comandesm.sh, plus inline code. three.js comes fromhttps://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js. window.velxioalready exists when your scripts run. It is the only link to the circuit.
The velxio API
Section titled “The velxio API”const info = await velxio.ready();// { boards: [{ id, kind }],// parts: [{ id, type, board, outputs: [...], inputs: [{ key, kind, min, max, unit }] }],// theme: 'dark' | 'light' }
velxio.onFrame((f) => { // about 125 times per second // f.t simulated seconds since the board booted (null while stopped) // f.dt simulated seconds since the previous frame // f.running true while the firmware runs // f.parts { [id]: { drive, rpm } } for motors, { [id]: { angle } } for servos, // { [id]: { on, brightness } } for LEDs});
velxio.set(partId, values); // write a sensor: only the keys it lists, values clampedvelxio.press(partId); // pushbuttons and switchesvelxio.release(partId);velxio.on('reset', fn); // the firmware restarted: put the world back at its startvelxio.on('theme', fn); // Velxio switched between dark and lightvelxio.on('visibility', fn); // stop drawing while hidden, keep the physics on framesvelxio.telemetry({ ... }); // optional state to show in Velxioconsole.log(...); // goes to the World logRules for a World that behaves
Section titled “Rules for a World that behaves”- Physics on simulated time. Add up
f.dtand step with a fixed step (2 ms works well), clamping the backlog at 0.25 s. Draw withrequestAnimationFrame, but never move anything by wall time: the simulator can run slower or faster than real time. - Move only while
f.runningis true, and put everything back at its start onreset. - Write a sensor only when its value changes, and a distance sensor at most every 30 ms of simulated time. Measure from the scene: sample the floor under a line sensor, cast a ray for a distance sensor.
- Map a motor’s drive to wheel speed with a little inertia (a first-order lag of about 80 ms) and a small deadband. A differential robot turns by the difference between its two sides.
- One self-contained file that resizes with the window and shows the readings that matter in a small overlay.
A minimal free World
Section titled “A minimal free World”<!doctype html><html><head> <meta name="viewport" content="width=device-width, initial-scale=1"> <style>html,body{margin:0;height:100%;overflow:hidden;background:#15171a;color:#ddd;font:12px system-ui}</style></head><body> <script type="module"> const info = await velxio.ready(); // build the scene from info.parts ... const STEP = 0.002; let acc = 0; velxio.onFrame((f) => { if (!f.running) return; acc = Math.min(acc + f.dt, 0.25); while (acc >= STEP) { // step the physics: read f.parts[id].drive or f.parts[id].angle acc -= STEP; } // velxio.set('<sensor id>', { ... }) when a reading changed }); velxio.on('reset', () => { /* back to the start */ }); // requestAnimationFrame loop: draw only </script></body></html>The Romeo ESP32-S3 line follower is a complete free World: a three.js scene with its own robot model, three line sensors on a taped loop, and a URM09 that sees a box you can drop on the track.