Write code that runs in an R3 project
r3_code_writeAdd or replace a Code component: JavaScript that makes a project DO something. It runs on ONE event you choose (event): RENDER_BEFORE (default) every frame, for movement (held keys: this.keysPressed); KEY_DOWN / KEY_UP once per press / release; MOUSE_CLICK, SWIPE, MUSIC_BEAT, PHYSICS_COLLISION once per click, swipe, beat, collision. A script per event: r3_docs_read("HOWTO_CODE_EVENTS.md"). Kept at once in the live copy every open R3 tab runs, nothing to save (r3_editor_code is the same tool); the answer gives its seq and codeVersion.
r3_project_load names the entityRefs code uses; r3_docs_read("CODE_PATTERNS.md") is the API (a guessed one saves, then silently does nothing).
The code: a function body that RETURNS its hooks:
this.start = function() {
// once, at start
};
this.update = function(data) {
this['mesh_cube_1'].rotation.y += data.delta;
};
return {start: this.start, update: this.update}; // REQUIRED — nothing runs without itReach a component as this['<entityRef>'], infrastructure with this.getProject() / getScene() / getCamera() / getRenderer() / getWorld() / getAudioListener() / getEntityInstance(). Anything else returned is an api other scripts call: this['<entityRef>'].api.<name>(...). Code that creates things (scene objects, timers, listeners) frees them in a returned dispose: R3 calls it on re-save, Stop and delete.
No getComponentByRef, this.state, this.getSibling or R3 global: code using them is REFUSED.
EVENTS (by NAME; default RENDER_BEFORE): RENDER_BEFORE, RENDER_AFTER, KEY_DOWN, KEY_UP, MOUSE_DOWN, MOUSE_UP, MOUSE_MOVE, MOUSE_WHEEL, MOUSE_CLICK, TOUCH_START, TOUCH_MOVE, TOUCH_END, TOUCH_CANCEL, SWIPE, MUSIC_BEAT, MUSIC_BAR, PHYSICS_COLLISION. Their data (mouse: nested, -1..+1): the how-to's table.
Pass entityRef + baseVersion (the codeVersion r3_code_read gave) to REPLACE a script (and its event); name (or neither) to create one. Never merged: a write on an older version is refused with the current code.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The JavaScript. A function body that returns {start, update} — see the description. | |
| name | No | Label for a NEW Code component, e.g. "Spin". Cannot be combined with entityRef. | |
| event | No | Which event runs it, by NAME: RENDER_BEFORE, RENDER_AFTER, KEY_DOWN, KEY_UP, MOUSE_DOWN, MOUSE_UP, MOUSE_MOVE, MOUSE_WHEEL, MOUSE_CLICK, TOUCH_START, TOUCH_MOVE, TOUCH_END, TOUCH_CANCEL, SWIPE, MUSIC_BEAT, MUSIC_BAR, PHYSICS_COLLISION. Default RENDER_BEFORE on create; left unchanged on update. | |
| entityRef | No | The entityRef of an EXISTING Code component to replace, as reported by r3_project_load. Cannot be combined with name. | |
| projectId | Yes | The project to write into, from r3_project_create or r3_project_load. | |
| baseVersion | No | REQUIRED with entityRef: the codeVersion r3_code_read answered for that script. A write on an older version is refused with the current code, never merged. Leave it out when creating. | |
| componentId | No | Or the id of the EXISTING Code component to replace (instead of entityRef). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seq | No | ||
| name | Yes | ||
| event | Yes | ||
| action | Yes | ||
| answer | Yes | This answer in words: what was done, what R3 measured, decided or refused, and what to do next. The same text as the result's text block. Read it: the fields beside it are the data, this is the guidance. | |
| fileName | Yes | ||
| warnings | No | ||
| entityRef | Yes | ||
| projectId | Yes | ||
| codeVersion | Yes | ||
| componentId | Yes |