Change a property on an R3 component
r3_component_setSet one or more properties on a component that already exists in a project — a material's roughness, a mesh's position, which material a mesh uses. Kept at once in the project's live copy: every R3 tab with the project open shows it now, no editor needed and nothing to save (r3_editor_set is the same tool). The answer says what was kept and its seq.
Components are addressed by entityRef; r3_project_load returns those names.
Properties come in four shapes and the value you pass differs: • plain value — {"roughness": 0.25}, {"visible": false} • value component (position / rotation / scale / color / size …) — pass an OBJECT of just the keys to change: {"position": {"y": 2}} leaves x and z alone. Vector3 has x/y/z, Color has r/g/b/a (0..1), Scalar has value. An EMPTY slot (a rigid body's centerOfMass is empty until set) is made from the fields given: {"centerOfMass": {"z": -0.3, "mass": 8}}; the fields not named keep their defaults. • reference to another component — pass that component's entityRef as a string: {"material": "material_cube_1"}, or null to clear it. • list of references (a mesh's materials) — pass an ARRAY of entityRefs: {"materials": ["mat_a", "mat_b"]}. The array REPLACES the whole list, in the order given — it does NOT append, so name every component you want in it; [] empties the list. The result reports the list before and after, so check that against what you intended.
Several properties in one call is one round trip, and is applied all-or-nothing.
An unknown property name is REFUSED and the valid names are listed, rather than written — so a typo costs a message, not a corrupted project. Renaming (name / entityRef) is refused too: it has to rewrite the code that addresses the component, which only the R3 editor does.
Giving a VehicleWheel its mesh or vehicle measures the wheel from that mesh, as the R3 editor does (Configure from Mesh: radius, connectionPoint, axle); a value named in the same call is kept. Giving a ColliderCuboid / Sphere / Cylinder / Capsule its mesh fits it to that mesh (Fit to Mesh: size, and position on the mesh's centre); giving it only a rigidBody fits the values still at their defaults. The answer says what was measured or fitted and what was kept (PHYSICS_USAGE.md → Vehicles).
Moving or scaling a Mesh keeps what the editor derives from it: a SCALE change re-fits every Cuboid / Sphere / Cylinder / Capsule collider fitted to that mesh (size and offset); moving or scaling a wheel's mesh re-measures the wheel; scaling a vehicle's chassis mesh also carries the wheels' suspensionRestLength and maxSuspensionTravel by the new / old scale on the up axis. The answer lists each.
A Mesh's rotation and quaternion are one orientation held twice: set ONE of them and the other follows (both in one call must agree, or the call is refused).
Changing the parent of a Mesh / Empty / Points / Line ({"parent": "root_empty"}, or null for the scene) keeps it where it is in the world, as the R3 editor's re-parent does: its position, rotation (and quaternion) and scale are rewritten to the values local to the new parent, and the answer lists them. A position, rotation / quaternion or scale given in the SAME call is the new LOCAL value under the new parent, taken as given (as if the parent changed first and that value were set after); the fields not given keep the world place. Under a NON-UNIFORMLY scaled parent a rotated part cannot keep its shape (it would shear): that re-parent is refused unless you give rotation and scale yourself.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| entityRef | No | Which component to change, as reported by r3_project_load, e.g. "mesh_cube_1". | |
| projectId | Yes | The project the component is in, from r3_project_create or r3_project_load. | |
| properties | Yes | What to set: {"roughness": 0.25, "position": {"y": 2}, "material": "material_cube_1"}. | |
| componentId | No | Or its id (r3_project_load) — exactly one of entityRef / componentId. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seq | No | ||
| type | 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. | |
| landed | No | ||
| changes | Yes | ||
| physics | Yes | ||
| entityRef | Yes | ||
| keptWorld | No | ||
| projectId | Yes | ||
| componentId | Yes |