The handle to manipulate the item itself. This exists for each individual item, and can be accessed from the $ object.

Hierarchy

  • ClusterScript

Properties

angularVelocity: Vector3

Gets or sets this item's angular velocity (global coordinates).

If this item is not a MovableItem, the value will be a Zero Vector. If this item is not a physics-enabled MovableItem, attempting to modify it will result in an exception. Changes made during grabbing, etc. will be ignored.

id: string

The string representation of the ID that uniquely identifies an item within the space. This is the same as the ItemHandle.id of the ItemHandle for this item.

itemHandle: ItemHandle

Returns the ItemHandle that represents this item.

itemTemplateId: ItemTemplateId

The ID of item template that this Craft Item is based on. if the item executing this script is World Item, this function returns null. This value can be used by createItem.

state: StateProxy

Provides access to the state of individual items. Arbitrary property names can be used as keys for reading/writing data in the state.

Example

Reading from a not yet defined property will default to returning undefined.

let v = $.state.exampleKey; // Read the value of the key "exampleKey". If it has never been written to before, it will return undefined.
if (v == null) { v = 0.0; }
$.state.exampleKey = v + 1;

Values of the Sendable type can also be written and saved to states.

Specifically, you can use numbers, strings, booleans, Vector2, Vector3, Quaternion, PlayerHandle, ItemHandle, arrays of the aforementioned types, and objects having keys assigned with strings.

Example

$.state.exampleKey1 = 1; // Write a number
$.state.exampleKey2 = "hello"; // Write a string
$.state.exampleKey3 = true; // Write a boolean
$.state.exampleKey4 = { foo: "bar" }; // Write an object
$.state.exampleKey5 = [1, 2, 3]; // Write an array
$.state.exampleKey6 = { // Write a complex object
array: [1, 2, 3],
object: { foo: "bar" },
};

Example

To make changes on arrays and objects reflect on a state, they need to be reassigned.

$.state.exampleKey = [1, 2, 3];
// $.state.exampleKey.push(4); // This will NOT make the changes reflect on the state

// This will make the changes reflect on the state
const v = $.state.exampleKey;
v.push(4);
$.state.exampleKey = v;
useGravity: boolean

Gets or sets whether this item is affected by gravity under normal conditions. Items are not affected by gravity while being grabbed, but this does not affect useGravity.

If this item is not a physics-enabled MovableItem, the value will be false. If this item is not a physics-enabled MovableItem, attempting to modify it will result in an exception.

velocity: Vector3

Gets or sets this item's velocity (global coordinates).

If this item is not a MovableItem, the value will be a Zero Vector. If this item is not a physics-enabled MovableItem, attempting to modify it will result in an exception. Changes made during grabbing, etc. will be ignored.

Methods

  • Beta

    Adds a force, valid during the current PhysicsUpdate, to the item's center of gravity. This can only be used inside the callback of onPhysicsUpdate. Calling it elsewhere will result in an exception.

    Parameters

    • force: Vector3

      Force (global coordinates)

    Returns void

  • Beta

    Adds a force (in global coordinates), valid during the current PhysicsUpdate, to a specified point on the item. This can only be used inside the callback of onPhysicsUpdate. Calling it elsewhere will result in an exception.

    Parameters

    • force: Vector3

      Force (global coordinates)

    • position: Vector3

      Point to apply force (global coordinates)

    Returns void

  • Beta

    Adds an impulsive force to the item's center of gravity. To apply impulsive force to points other than the center of gravity, use addImpulsiveForceAt.

    Parameters

    • impulsiveForce: Vector3

      Impulsive force (global coordinates)

    Returns void

  • Beta

    Adds an impulsive force to a specified point on the item.

    Parameters

    • impulsiveForce: Vector3

      Impulsive force (global coordinates)

    • position: Vector3

      Point to apply impulsive force (global coordinates)

    Returns void

  • Beta

    Adds an impulsive torque to the item's center of gravity.

    Parameters

    • impulsiveTorque: Vector3

      Impulsive torque (global coordinates)

    Returns void

  • Beta

    Adds a torque, valid during the current PhysicsUpdate, to the item's center of gravity. This can only be used inside the callback of onPhysicsUpdate. Calling it elsewhere will result in an exception.

    Parameters

    • torque: Vector3

      Torque (global coordinates)

    Returns void

  • Locates an audio entry with the ID itemAudioSetId within the item's ItemAudioSetList, and returns an ApiAudio object referring to it.

    For details on ItemAudioSetList, refer to the documentation.

    Parameters

    • itemAudioSetId: string

    Returns ApiAudio

  • Sends a request outside of the space. The response is received through onExternalCallEnd. To use this call, the developer themselves must prepare an external server.

    Frequency Limit

    There is a limit on how often callExternal can be called.

    • If the item running this script is a craft item, 5 times per minute per item
    • If the item running this script is a world item, a total of 100 times per minute per space for all world items

    It is possible to momentarily exceed this limit, but please ensure the average number of calls stays below this limit. If the limit is exceeded, ClusterScriptError (rateLimitExceeded) occurs and the operation fails.

    Size Limit

    If the request or meta exceeds the size limit, ClusterScriptError (requestSizeLimitExceeded) will occur.

    How to Use

    Setup: Register the endpoint (external communication (callExternal) connection URL) from Creator Kit to receive the requests. The endpoint is tied to the account and can be set only once per account. Requests are sent to the endpoint of the account that uploaded the item/world.

    Each time callExternal is called from Cluster Script, an HTTP POST call is made from cluster's server to the endpoint. The data included in the response to the POST is passed to onExternalCallEnd. If the endpoint does not respond within 5 seconds timeout or returns an error, it is considered a failure. There are no retries from cluster to the endpoint.

    Endpoint Specifications

    Must respond to HTTP POST in the following format. Only HTTP/1.1 and HTTP/2 are supported, calls via HTTP/3 are not supported. Both HTTP and HTTPS are supported, but HTTPS is recommended for security reasons upon publication.

    Request

    {
    "request": "...string (1kB or less)..."
    }

    Response

    {
    "verify": "...verify_token (can be obtained in Creator Kit)...",
    "response": "...string (1kB or less)..."
    }

    The verify field is used to confirm the developer themselves manages the endpoint. If the response field exceeds 1kB, it is considered an invalid response and callExternal is treated as a failure.

    If the ownership of the endpoint cannot be confirmed due to an invalid response, etc., the use of the callExternal API may be restricted. Similarly, restrictions or inquiries may be made in cases where it is thought that responses are not being made due to high load.

    Privacy

    Sending information that corresponds to personal information of players without their consent is prohibited. If such use is suspected, there may be restrictions on the use of the callExternal API or inquiries regarding the purpose of use. Also, if deemed inappropriate by us, we may restrict its use without notice.

    Parameters

    • request: string

      A string less than 1kB. It is sent to an external server.

    • meta: string

      A string less than 100 bytes. It can be used to identify multiple callExternal calls. It is fine to specify an empty string or the same string multiple times.

    Returns void

  • Calculates the data size in bytes when the data is sent with send. If the data is not compatible with send, a TypeError will occur.

    Parameters

    Returns number

  • Beta

    Creates the specified item in the current space. There may be a delay before the item is actually created.

    Item creation can fail for various reasons, including processing load or permission issues.

    The template of the item to be created must meet one of the following criteria:

    • If the item executing this script is a Craft Item, it must have the same author as that item's template.
    • If the item executing this script is a World Item, it must have the same author as the current Venue.
    • It is a Beta item.

    If the creation of an item would cause the Craft Item Capacity Usage to exceed 500%, createItem will fail.

    If item creation fails, the returned ItemHandle will be in a state where it does not point to anything, and ItemHandle.exists will return false.

    When an item is created through this method, the owner of the item that executes the createItem method will become the owner of the new item, provided they are present in the room at that time.

    This method can only be used to create items within 30 meters of the item executing this script. If this limit is exceeded, a ClusterScriptError (distanceLimitExceeded) error will occur and createItem will fail.

    An item can be created up to 10 times per second. This can be exceeded momentarily, but please keep the average below this limit. If the limit is exceeded, a ClusterScriptError (rateLimitExceeded) error will occur and createItem will fail.

    Parameters

    • itemTemplateId: ItemTemplateId

      TemplateId of the item to be created

    • position: Vector3

      Initial position (global coordinates)

    • rotation: Quaternion

      Initial rotation (global coordinates)

    Returns ItemHandle

  • Destroys this item. There may be a delay before the item is actually destroyed.

    This currently only works with Dynamic Items. If executed on items embedded into worlds, an ClusterScriptError (executionNotAllowed) error will occur and destroy will fail.

    Returns void

  • Returns an array of handles for items (excluding itself) that have detectable colliders within a specified spherical space. Detectable colliders are: colliders with a PhysicalShape, colliders with an OverlapSourceShape, and colliders without a Shape that can cause physics collisions. Detectable layers are: Default, RidingItem, InteractableItem, and GrabbingItem.

    Returns

    An array of handles for the detected items (order is undefined)

    Parameters

    • position: Vector3

      Center position (global coordinates)

    • radius: number

      Radius of sphere

    Returns ItemHandle[]

  • Beta

    Returns an array of detectable objects that overlap with this item's OverlapDetectorShape. Detectable objects are: colliders with a PhysicalShape, colliders with an OverlapSourceShape, and colliders without a Shape that can cause physics collisions. Overlaps with this item itself are excluded.

    Either this item or the detectable object must fulfill one of the following: be a MovableItem, have a Rigidbody, have a CharacterController, or be a player. Detectable layers are those that perform collision detection on this item's OverlapDetectorShape. In some cases, this method may exclude objects that do overlap in space, eg. if the item had already been overlapping when it was created or enabled.

    Example

    // Count players who overlap with me
    let set = new Set();
    let overlaps = $.getOverlaps();
    for(let overlap of overlaps) {
    let player = overlap.object.playerHandle;
    if (player != null && !set.has(player.id)) {
    set.add(player.id);
    }
    }
    $.log(`Player count: ${set.size}`);

    Returns Overlap[]

  • Returns an array of handles for players whose colliders exist within a specified spherical space.

    Returns

    An array of handles for the detected players (order is undefined)

    Parameters

    • position: Vector3

      Center position (global coordinates)

    • radius: number

      Radius of sphere

    Returns PlayerHandle[]

  • Obtains the current position of the item. Values will be returned in the global coordinates of the world the item is in.

    If you call this immediately after calling setPosition, please be aware it will return the item's current position, not the value passed to setPosition.

    Returns Vector3

  • Obtains the current rotation of the item. Values will be returned in the global coordinates of the world the item is in.

    If you call this immediately after calling setRotation, please be aware it will return the item's current rotation, not the value passed to setRotation.

    Returns Quaternion

  • In Worlds made using the Creator Kit, obtains a message from the target. If used outside of items in Creator Kit-developed worlds, a runtime error will occur.

    Example

    // Obtain a message to this item, with the identifer "foo", in the boolean type.
    $.getStateCompat("this", "foo", "boolean");

    Parameters

    • target: CompatGimmickTarget

      The target from which to obtain messages

      "this": Obtain a message for this item.

      "owner": Obtain a message for this item's owner.

      "global": Obtain a global message.

    • key: string

      Message identifier

    • parameterType: CompatParamType

      Message type

      Can be one of the following: "signal", "boolean", "float", "double", "integer", "vector2", and "vector3".

    Returns undefined | CompatSendable

  • Beta

    Locates an animation entry with the ID humanoidAnimationId within the item's HumanoidAnimationList, and returns a HumanoidAnimation object referring to it.

    For details on HumanoidAnimationList, refer to the documentation.

    Parameters

    • humanoidAnimationId: string

    Returns HumanoidAnimation

  • Performs a toString on the content of v, then outputs it to the log.

    Parameters

    • v: any

    Returns void

  • Beta

    Returns a MaterialHandle object that references the material with the id specified in materialId in the item's ItemMaterialSetList.

    For details on ItemMaterialSetList, see documentation.

    Example

    // Items that change the color of the material when interacted
    $.onInteract(() => {
    const mh = $.material("materialId");
    mh.setBaseColor(new Color(Math.random(), Math.random(), Math.random(), 1));
    });

    Parameters

    • materialId: string

    Returns MaterialHandle

  • Beta

    Registers a callback to be called when this item collides with another object. The item must have physics behaviors enabled.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    $.onCollide(collision => {
    if (collision.object.playerHandle != null) {
    $.log("Collided with a player.");
    }
    });

    Parameters

    Returns void

  • Registers a callback to be called upon the completion of callExternal. The callback is called once upon success or failure of callExternal.

    Only supported for calls at the script's top level. If called multiple times at the top level, only the last registration is effective.

    Parameters

    • callback: ((response: null | string, meta: string, errorReason: null | string) => void)

      response: The response obtained from external. It is null in case of failure. meta: The same string passed during callExternal. errorReason: The reason for failure if response is null.

        • (response: null | string, meta: string, errorReason: null | string): void
        • Parameters

          • response: null | string
          • meta: string
          • errorReason: null | string

          Returns void

    Returns void

  • Registers a callback to be called when grabbing or releasing an object. The item must have a GrabbableItem Component attached.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    $.onGrab((isGrab, isLeftHand) => {
    if (isGrab) {
    if (isLeftHand) {
    $.log("Grabbed by left hand.");
    } else {
    $.log("Grabbed by right hand.");
    }
    }
    });

    The player handle can also be obtained.

    // Increase the movement speed while grabbing
    $.onGrab((isGrab, isLeftHand, player) => {
    if (isGrab) {
    player.setMoveSpeedRate(2);
    } else {
    player.setMoveSpeedRate(1);
    }
    });

    Parameters

    • callback: ((isGrab: boolean, isLeftHand: boolean, player: PlayerHandle) => void)

      isGrab = true when grabbing, false when releasing.

      isLeftHand = true when grabbed/released with the left hand, false when with the right hand.

      player = The handle of the player who grabbed/released the item.

        • (isGrab: boolean, isLeftHand: boolean, player: PlayerHandle): void
        • Parameters

          Returns void

    Returns void

  • Registers a callback to be called when a "Use" action is performed on a non-grabbable item. The item must have 1 or more Collider Components attached.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    $.onInteract(() => {
    $.log("Interacted.");
    });

    The player handle can also be obtained.

    // Respawn the player who interacted with it
    $.onInteract(player => {
    player.respawn();
    });

    Parameters

    • callback: ((player: PlayerHandle) => void)

      player = The handle of the player who interacted with the item.

    Returns void

  • Beta

    Registers a callback to be called when this item's physics state gets updated. (Corresponds to FixedUpdate in Unity)

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    // Rise for 1 second, then fall for 2 seconds.
    // The Rigidbody's Mass here is assumed to be 1.
    $.onPhysicsUpdate(deltaTime => {
    let t = $.state.time ?? 0;
    t += deltaTime;
    if (t < 1) {
    $.addForce(new Vector3(0, 12, 0));
    } else if (t > 3) {
    t = 0;
    }
    $.state.time = t;
    });

    Parameters

    • callback: ((deltaTime: number) => void)
        • (deltaTime: number): void
        • Parameters

          • deltaTime: number

          Returns void

    Returns void

  • Registers a callback to be called when this item receives a message sent from ItemHandle.send.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    // Log to output if the message type received is either "damage" or "heal".
    $.onReceive((messageType, arg, sender) => {
    switch (messageType) {
    case "damage":
    $.log(`damage: ${arg}`);
    break;
    case "heal":
    $.log(`heal: ${arg}`);
    break;
    }
    });

    Parameters

    Returns void

  • Registers a callback to be called when mounting or dismounting a ridable item. The item must have a RidableItem Component attached.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    // Rotates only while the players is riding.
    $.onRide(isGetOn => {
    $.state.isRiding = isGetOn;
    });

    $.onUpdate(deltaTime => {
    if (!$.state.isRiding) return;
    let t = $.state.time ?? 0;
    t += deltaTime;
    $.state.time = t % 360;
    $.setRotation(new Quaternion().setFromEulerAngles(0, t, 0));
    });

    The player handle can also be obtained.

    $.onRide((isGetOn, player) => {
    $.state.isRiding = isGetOn;
    $.state.player = isGetOn ? player : null;
    });

    Parameters

    • callback: ((isGetOn: boolean, player: PlayerHandle) => void)

      isGetOn = true when mounting, false when dismounting.

      player = The handle of the player mounted/dismounted the item.

    Returns void

  • Registers a callback to be called once, before the first execution of onUpdate, when this item first appears in the space.

    The item appearing in the space refers to any of the following situations:

    • When an item is created with createItem or createItemGimmick
    • In Creator Kit based worlds, when the space starts anew
    • In World Craft, when an item is newly created by placing or copying

    Only the last registered callback at script load time will be active.

    For more details, see When onStart is called

    Parameters

    • callback: (() => void)
        • (): void
        • Returns void

    Returns void

  • Registers a callback to be called when this item receives a text input from the player, requested with PlayerHandle.requestTextInput.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    $.onTextInput((text, meta, status) => {
    switch(status) {
    case TextInputStatus.Success:
    $.log(text);
    break;
    case TextInputStatus.Busy:
    // Retry in 5 seconds
    $.state.should_retry = true;
    $.state.retry_timer = 5;
    break;
    case TextInputStatus.Refused:
    // Give up if refused
    $.state.should_retry = false;
    break;
    }
    });

    Parameters

    • callback: ((text: string, meta: string, status: TextInputStatus) => void)

      text = Text entered by the player.

      meta = The meta string as specified in PlayerHandle.requestTextInput.

      status = Status signifying the outcome of the text input request.

    Returns void

  • Registers a callback to be called on each update loop.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    // Output to log every 10 seconds
    $.onUpdate(deltaTime => {
    let t = $.state.time ?? 0;
    t += deltaTime;
    if (t > 10) {
    $.log("10 seconds elapsed.");
    t -= 10;
    }
    $.state.time = t;
    });

    Parameters

    • callback: ((deltaTime: number) => void)
        • (deltaTime: number): void
        • Parameters

          • deltaTime: number

          Returns void

    Returns void

  • Registers a callback to be called when a "Use" action is performed on a item being grabbed. The item must have a GrabbableItem Component attached.

    Supported only when called at the top level of the script. If called multiple times at the top level, only the last registration will be valid.

    Example

    $.onUse(isDown => {
    $.log(`isDown: ${isDown}.`);
    });

    The player handle can also be obtained.

    // Apply upwards velocity to the player who used this
    $.onUse((isDown, player) => {
    if (isDown) {
    player.addVelocity(new Vector3(0, 5, 0));
    }
    });

    Parameters

    • callback: ((isDown: boolean, player: PlayerHandle) => void)

      isDown = true when beginning the "Use" action, false when ending.

      player = The handle of the player who used the item.

    Returns void

  • Beta

    Casts a ray, and returns the first object it collided with.

    Returns

    The collided object (null if no collision)

    Parameters

    • position: Vector3

      Origin of the ray (global coordinates)

    • direction: Vector3

      Direction of the ray (global coordinates)

    • maxDistance: number

      Maximum distance for performing collision detection

    Returns null | RaycastResult

  • Beta

    Casts a ray, and returns all the objects it collided with.

    Returns

    An array of the collided objects (order is undefined)

    Parameters

    • position: Vector3

      Origin of the ray (global coordinates)

    • direction: Vector3

      Direction of the ray (global coordinates)

    • maxDistance: number

      Maximum distance for performing collision detection

    Returns RaycastResult[]

  • In Worlds made using the Creator Kit, sends a signal to the target. If used outside of items in Creator Kit-developed worlds, a runtime error will occur.

    Parameters

    • target: CompatStateTarget

      The target to send the message

      "this": Send a message to this item.

      "owner": Send a message to this item's owner.

    • key: string

      Message identifier

    Returns void

  • Specify a position to move the item to, using the global coordinates of the world the item is in.

    The item must have a MovableItem Component attached. As the positions are interpolated and synced across the network, please be aware they may not be reflected immediately.

    Parameters

    Returns void

  • Specify a rotation to rotate the item to, using the global coordinates of the world the item is in.

    The item must have a MovableItem Component attached. As the rotations are interpolated and synced across the network, please be aware they may not be reflected immediately.

    Example

    $.setRotation(new Quaternion().setFromEulerAngles(new Vector3(90, 0, 0)));
    

    Parameters

    Returns void

  • In Worlds made using the Creator Kit, sends a message to the target. If used outside of items in Creator Kit-developed worlds, a runtime error will occur.

    Example

    // Send a message to this item, with the identifier "foo", in the boolean type.
    $.setStateCompat("this", "foo", true);

    Parameters

    • target: CompatStateTarget

      The target to send the message

      "this": Send a message to this item.

      "owner": Send a message to this item's owner.

    • key: string

      Message identifier

    • value: CompatSendable

      Message value

    Returns void

  • Locates an object named subNodeName within the item's children and descendants, and returns a SubNode object that refers to it.

    Parameters

    • subNodeName: string

    Returns SubNode

Generated using TypeDoc