Write code that runs in an R3 project
r3_code_writeAdd or replace a Code component: JavaScript a project runs. 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 (r3_editor_code: the same tool).
r3_project_load names the entityRefs; r3_docs_read("CODE_PATTERNS.md") is the API (a guessed one silently does nothing).
The code is a function body:
this.update = function(data) {
this['mesh_cube_1'].rotation.y += data.delta;
};
return {update: this.update}; // REQUIRED (also start, dispose) — nothing runs without itReach a component as this['<entityRef>'], infrastructure with this.getProject() / getScene() / getCamera() / 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, SONG_CUE, PHYSICS_COLLISION. Their data (mouse: nested, -1..+1): the how-to's table.
Pass entityRef + baseVersion (r3_code_read's codeVersion) to REPLACE a script; name (or neither) to create one. Never merged: an older one is refused with the current code.
PATCH a long script: replacements [{old, new, count?}] + baseSha256 (r3_code_read's), no code; all or nothing, each old found exactly count (default 1) times; ≤ 200 replacements, 60000 chars.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"projectId": "<projectId>"
},
"name": "r3_code_write"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | The JavaScript. A function body that returns {start, update} — see the description. Omit it when you send replacements. | |
| 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, SONG_CUE, 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. | |
| baseSha256 | No | With replacements only: the sha256 r3_code_read answered for the script (of its WHOLE code) at baseVersion. | |
| 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). | |
| replacements | No | Instead of code: exact replacements on the script at baseVersion, in order, all or nothing (at most 200, 60000 characters of old + new in all). |
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. | |
| sha256 | Yes | ||
| imports | No | ||
| fileName | Yes | ||
| warnings | No | ||
| entityRef | Yes | ||
| projectId | Yes | ||
| totalChars | Yes | ||
| codeVersion | Yes | ||
| componentId | Yes | ||
| occurrences | Yes | ||
| replacements | Yes |