Skip to main content
Glama

Write code that runs in an R3 project

r3_code_write
Destructive

Add 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 it

Reach 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

NameRequiredDescriptionDefault
codeNoThe JavaScript. A function body that returns {start, update} — see the description. Omit it when you send replacements.
nameNoLabel for a NEW Code component, e.g. "Spin". Cannot be combined with entityRef.
eventNoWhich 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.
entityRefNoThe entityRef of an EXISTING Code component to replace, as reported by r3_project_load. Cannot be combined with name.
projectIdYesThe project to write into, from r3_project_create or r3_project_load.
baseSha256NoWith replacements only: the sha256 r3_code_read answered for the script (of its WHOLE code) at baseVersion.
baseVersionNoREQUIRED 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.
componentIdNoOr the id of the EXISTING Code component to replace (instead of entityRef).
replacementsNoInstead 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

NameRequiredDescriptionDefault
seqNo
nameYes
eventYes
actionYes
answerYesThis 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.
sha256Yes
importsNo
fileNameYes
warningsNo
entityRefYes
projectIdYes
totalCharsYes
codeVersionYes
componentIdYes
occurrencesYes
replacementsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • addedInput schema / properties / baseSha256
      Added value: +{
      +  "description": "With replacements only: the sha256 r3_code_read answered for the script (of its WHOLE code) at baseVersion.",
      +  "pattern": "^[0-9a-f]{64}$",
      +  "type": "string"
      +}
    • changedInput schema / properties / code / description
      Previous value: -"The JavaScript. A function body that returns {start, update} — see the description."New value: +"The JavaScript. A function body that returns {start, update} — see the description. Omit it when you send replacements."
    • addedInput schema / properties / replacements
      Added value: +{
      +  "description": "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).",
      +  "items": {
      +    "properties": {
      +      "count": {
      +        "description": "How many times old occurs, all replaced (default 1).",
      +        "maximum": 9007199254740991,
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "new": {
      +        "description": "What replaces it (empty deletes it). Taken literally.",
      +        "maxLength": 60000,
      +        "type": "string"
      +      },
      +      "old": {
      +        "description": "Exact text in the script (whitespace and line breaks count).",
      +        "maxLength": 60000,
      +        "minLength": 1,
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "old",
      +      "new"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 200,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "projectId",
      -  "code"
      -]New value: +[
      +  "projectId"
      +]
    • addedOutput schema / properties / occurrences
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedOutput schema / properties / replacements
      Added value: +{
      +  "anyOf": [
      +    {
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedOutput schema / properties / sha256
      Added value: +{
      +  "type": "string"
      +}
    • addedOutput schema / properties / totalChars
      Added value: +{
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "projectId",
      -  "action",
      -  "componentId",
      -  "entityRef",
      -  "name",
      -  "fileName",
      -  "event",
      -  "codeVersion",
      -  "answer"
      -]New value: +[
      +  "projectId",
      +  "action",
      +  "componentId",
      +  "entityRef",
      +  "name",
      +  "fileName",
      +  "event",
      +  "codeVersion",
      +  "sha256",
      +  "totalChars",
      +  "replacements",
      +  "occurrences",
      +  "answer"
      +]
  2. Changed1 schema field changed
    • changedInput schema / properties / event / description
      Previous value: -"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."New value: +"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."
  3. Changed1 schema field changed
    • addedOutput schema / properties / imports
      Added value: +{
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "error": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "latestVersion": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      },
      +      "moduleId": {
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "name": {
      +        "type": "string"
      +      },
      +      "pinned": {
      +        "type": "boolean"
      +      },
      +      "version": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "name",
      +      "moduleId",
      +      "version",
      +      "latestVersion",
      +      "pinned",
      +      "error"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  4. Changed1 schema field changed
    • changedInput schema / properties / event / description
      Previous value: -"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. Default RENDER_BEFORE on create; left unchanged on update."New value: +"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."
  5. Changed1 schema field changed
    • changedInput schema / properties / event / description
      Previous value: -"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. Default RENDER_BEFORE on create; left unchanged on update."New value: +"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. Default RENDER_BEFORE on create; left unchanged on update."
  6. Changed2 schema fields changed
    • addedOutput schema / properties / answer
      Added value: +{
      +  "description": "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.",
      +  "type": "string"
      +}
    • changedOutput schema / required
      Previous value: -[
      -  "projectId",
      -  "action",
      -  "componentId",
      -  "entityRef",
      -  "name",
      -  "fileName",
      -  "event",
      -  "codeVersion"
      -]New value: +[
      +  "projectId",
      +  "action",
      +  "componentId",
      +  "entityRef",
      +  "name",
      +  "fileName",
      +  "event",
      +  "codeVersion",
      +  "answer"
      +]
  7. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Well beyond what readOnlyHint=false/destructiveHint=true already convey: the code lives in a copy every open R3 tab runs, created objects/timers/listeners must be released in a returned dispose which R3 calls on re-save, Stop and delete, and a missing return object means nothing runs at all. It also discloses refusal rules (banned globals, stale baseVersion, out-of-order patches) that no annotation covers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the code template, then lifecycle, then events, then write modes — a sensible order for a dense tool. It loses a point for redundancy: the full 18-event list appears in the description and again in the `event` schema, and some API warnings are restated in multiple paragraphs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given nine parameters, mutation semantics and a sibling read tool, the description covers what an agent needs before calling: code shape, event selection, runtime reachability rules, concurrency guards and patch form. Return values are covered by the output schema and per-event payload detail is delegated to a named how-to, which is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description still adds real meaning: baseVersion is the codeVersion from r3_code_read, baseSha256 is computed over the whole code, replacement `old`/`count` semantics are all-or-nothing and each must match exactly count times, plus the 200-replacement / 60000-char caps. Some of this duplicates schema prose, which keeps it off a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Add or replace a Code component: JavaScript a project runs" gives a specific verb pair and resource, and immediately distinguishes the write path from r3_code_read (versions/sha) and r3_editor_code (declared to be the same tool under another name). An agent can tell what this does and where the sibling reads happen without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description spells out the three modes and how to select them: entityRef + baseVersion to replace, name (or neither) to create, replacements + baseSha256 to patch a long script. It also names the docs to read per event (HOWTO_CODE_EVENTS.md, CODE_PATTERNS.md) and states the failure conditionals (stale version refused with current code, never merged).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources