Script

Attaches a Relay script to a definition.

• Kind: Script
• Availability: Any

Fields

parameters

object = {}

Key-value parameters passed to the script as a global parameters variable.

Provide either scriptAsset or scriptInline, not both.

scriptAsset

AssetReference

Path to a .rl script file.

scriptInline

string

Inline script source code (alternative to scriptAsset).

Handlers

When attached to Car objects, the following script handlers run:

onObjectLoad(car)

car Car The Car the script component is attached to.

Called when the script component initializes. The object’s 3D model may not be loaded yet.

onObjectUnload(car)

car Car The Car the script component is attached to.

Called when the object is being destroyed.

onModelLoad(car)

car Car The Car the script component is attached to.

Called when the object’s 3D model is loaded. Use this to access components, set up property observers, and control visual state.

onModelUnload(car)

car Car The Car the script component is attached to.

Called when the object’s 3D model is unloaded. Use this to clean up observers and other resources.

Example

This script cycles through a set of component names when a property changes, enabling only the matching one. It demonstrates using parameters, property observers, and component control.

Script (CycleComponents.rl):

var observer = null

var componentNames = parameters["components"]
var propertyKey = parameters["key"]

func onModelLoad(car) {
    var components = componentNames
        .map((name) => car.components[name])
        .filter((c) => c != null)

    observer = car.properties.observe(propertyKey, true, (value) => {
        for i in 0..<components.count {
            components[i].enabled = (componentNames[i] == value)
        }
    })
}

func onModelUnload(car) {
    observer?.dispose()
    observer = null
}

Adding it to a definition via Data.rl:

func modifyDefinitions(data) {
    data.merge("rr/my-car", {
        "definition": {
            "components": {
                "roof-selector": {
                    "kind": "Script",
                    "name": "RoofSelector",
                    "scriptAsset": "my-pack/CycleComponents",
                    "parameters": {
                        "components": ["FlatRoof", "PeakedRoof", "CupolarRoof"],
                        "key": "customize.roof"
                    }
                }
            }
        }
    })
}

Before writing your own script, check Shared Scripts — rr/shared ships ready-made ones for common cases, so you may not need one. The example above, in particular, is better served by rr/EnableComponentsPropertyEquals; see Toggleable Components.

Multiplayer

Script component handlers run on every peer, just like Main.rl handlers. If your script writes shared properties in response to game events (rather than UI interactions), guard those writes with world.isHost.