API Reference | Simuspaces ScriptAPI

Base Class

Scripts inherit from SimuScriptBase. Most callable helpers are protected, so they are used from inside your script class.

public virtual string ScriptName

Defaults to the class name. Used in logs and script event sender info.

public virtual string ScriptDescription

Optional description text for tools that surface script metadata.

protected GameObject gameObject

The object that owns this script instance.

protected Transform transform

The transform of the owning object.

protected Dictionary<string, GameObject> slots

Named object slots assigned by the runtime when available.

protected bool IsRuntimeMode

True when running in the runtime world rather than editor bootstrap mode.

protected virtual bool SyncTransformStateByDefault

Defaults to true. Override to disable automatic transform state sync at startup.

protected bool TransformStateSyncEnabled

Runtime switch for automatic transform state synchronization.

Core Types

SceneObject

Serialized scene reference with ObjectId, Id, IsNull, Exists, gameObject, transform, GetComponent<T>, GetComponents<T>, child lookup, and parent lookup helpers.

Sitpoint : SceneObject

Scene object reference with SitpointId resolution for sitpoint components and settings.

AvatarClone : SceneObject

Server-spawned avatar clone reference with SourceUsername, DisplayName, CloneId, and helper methods for destroy, transform, emote, sitpoint, and stand commands.

SVLight : SceneObject

Scene object reference with a light property that resolves a Light on the object or in children.

InventoryItem

Inventory reference with InventoryId, Kind, Id, IsNull, IsEmpty, Exists, and normalization helpers.

Emote : InventoryItem

Inventory item specialized for emotes. Kind is Emote; EmoteId mirrors InventoryId.

SVUserInfo

User snapshot with Username, ObjectName, ObjectId, and PlayerObject.

SVSitpointInfo

Sit or stand snapshot with Username, SitpointId, ObjectName, ObjectId, Sitpoint, and PlayerObject.

SVInteractionInfo

Interactable callback data with Username, ObjectName, ObjectId, ScriptNetworkId, InteractionType, and Target.

SVChatCommandInfo

Chat command callback data with Username, UserId, player object fields, room ids, FullText, Command, ParameterText, and split Args.

SVSitpointInputInfo

Sitpoint input data with MoveX, MoveY, LookX, LookY, Jump, Sprint, Username, SitpointId, and Sitpoint.

SVTriggerInfo

Trigger callback data with EventType, IsPlayer, username, object name/id, trigger object id, OtherObject, and TriggerObject.

SVCollisionInfo

Collision callback data with IsPlayer, username, collided object name/id, collision object id, OtherObject, and CollisionObject.

SVTriggerEventType

Enum values: Enter, Exit.

SVCharacterPhysicsMode

Enum values: Standing, Falling, Sleep.

SVCharacterImpactPart

Enum values: All, Core, LeftArm, RightArm, LeftLeg, RightLeg, Head.

Script Event Data

SVScriptEventData.Set(name, value)

Adds or replaces a named event value and returns the same data object.

Has(name)

Checks whether the data contains a key. Keys are case-insensitive.

Get(name, defaultValue)

Gets a raw value or default.

Get<T>(name, defaultValue)

Gets and converts a value to the requested type when possible.

TryGet<T>(name, out value)

Gets a typed value and reports whether the key existed.

GetString / GetInt / GetFloat / GetDouble / GetBool

Convenience typed accessors for common event payload values.

Copy()

Returns a shallow copy of the event data.

SVScriptEventData.From(params object[] pairs)

Builds event data from alternating name/value pairs.

Script Event Info

SVScriptEventInfo

Contains EventName, Group, FullName, SenderScriptName, SenderObjectId, SenderObject, and Data.

Lifecycle And Mode Helpers

public virtual void Start()

Called when the script starts. Call base.Start() before custom setup.

public virtual void OnDestroy()

Called as the script is destroyed. Use for cleanup such as despawning objects or stopping state.

public virtual void OnEnable()

Called when the script is enabled.

public virtual void OnDisable()

Called when the script is disabled.

public virtual void OnEvent(string eventName, object data)

Generic event hook for runtime-dispatched events.

SetTransformStateSync / DisableTransformStateSync / EnableTransformStateSync

Control automatic transform state synchronization for this script.

protected void SetStateApplyPhase(int phase)

Advanced control for when state is applied. The base uses the update phase.

Users

OnUserJoin(SVUserInfo user)

Override to run logic when a user enters.

OnUserPart(SVUserInfo user)

Override to run logic when a user leaves.

OnUserSit(SVSitpointInfo sitpoint)

Override to run logic when a user sits.

OnUserStand(SVSitpointInfo sitpoint)

Override to run logic when a user stands.

GetUsers()

Returns a list of active user snapshots.

GetUsernames()

Returns the active usernames known by the runtime.

ForEachUser(Action<SVUserInfo> callback)

Runs the callback for each active user and logs callback errors.

Script Events

Script events are local runtime messages. Use eventName for global listeners, or eventName@group for a grouped event key. Posting name@group notifies listeners of name and listeners of name@group.

CreateScriptEventData(params object[] nameValuePairs)

Builds SVScriptEventData from alternating name and value arguments.

NewScriptEventData(params object[] nameValuePairs)

Alias for CreateScriptEventData.

ListenForScriptEvent(string eventName, Action<SVScriptEventInfo> callback)

Registers a callback with full sender and payload details.

ListenForScriptEvent(string eventName, Action<SVScriptEventData> callback)

Registers a callback that receives only the payload data.

StopListeningForScriptEvent(string eventName = null)

Stops this script's event subscriptions. With no name, removes all subscriptions owned by this script.

PostScriptEvent(string eventName)

Posts an event with empty data.

PostScriptEvent(string eventName, SVScriptEventData data)

Posts an event with structured data.

PostScriptEvent(string eventName, params object[] nameValuePairs)

Posts an event from alternating name and value arguments.

Dialogs

ShowDialog queues a modal dialog client command. Provide targetUsername for a single user, or leave it empty for everyone.

ShowDialog(title, message, targetUsername = null, icon = Info, buttons = OK)

Shows a simple dialog with optional target, icon, and button set.

ShowDialog(title, message, SSModalDialogIcon icon)

Shows an icon dialog with an OK button.

ShowDialog(title, message, icon, buttons, targetUsername = null)

Shows a dialog with explicit icon and button configuration.

ShowDialog(title, message, icon, buttons, onResult, targetUsername = null)

Shows a dialog and invokes the callback with SSModalDialogResult.

ShowDialog(title, message, icon, onResult, targetUsername = null)

Shows an OK dialog and invokes the callback.

Dialog Enums

SSModalDialogIcon

None, Info, Warning, Error, Success.

SSModalDialogButtons

OK, OKCancel, YesNo, YesNoCancel, Custom.

SSModalDialogResult

None, OK, Cancel, Yes, No, Custom1, Custom2, Custom3.

Coroutines And Self Transform Helpers

StartCoroutine(IEnumerator routine)

Starts a coroutine using the script runtime runner.

yield return new WaitForSeconds(seconds)

Waits inside a coroutine. For example, yield return new WaitForSeconds(0.5f); waits half a second.

StopCoroutine(Coroutine routine)

Stops a coroutine started through the runtime runner.

StopAllCoroutines()

Stops all coroutines on the runner.

Move(Vector3 offset)

Adds the offset to this script object's world position.

Rotate(Vector3 eulerAngles)

Rotates this script object in world space.

RotateAround(Vector3 axis, float angle)

Rotates this script object around a world-space axis.

SetPosition / SetRotation / SetScale

Sets this script object's world position, world rotation, or local scale.

GetPosition / GetRotation / GetScale

Reads this script object's world position, world euler rotation, or local scale.

Self Object Client Commands

These helpers queue commands for the object that owns the script. Most include optional targetUsername, component index, and includeChildren parameters.

SetMaterialFloat(int materialIndex, string propertyName, float value, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Sets a material float property.

SetMaterialColor(int materialIndex, string propertyName, Color value, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Sets a material color property.

SetMaterialKeyword(int materialIndex, string keyword, bool enabled, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Enables or disables a material keyword.

SetRendererVisible(bool visible, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Sets renderer visibility.

SetRendererVisibleForUser(string targetUsername, bool visible, int rendererIndex = 0, bool includeChildren = true)

Changes this object's renderer visibility only for the named user. The private state is not replayed after the user leaves and rejoins. An empty username is rejected rather than becoming a broadcast.

SetLightEnabled / SetLightIntensity / SetLightColor

Controls a light component by index.

SetAudioVolume / SetAudioPitch / PlayAudio / StopAudio

Controls an audio source by index.

SetAnimatorTrigger / SetAnimatorBool

Controls animator parameters by index.

EnableAnimatorSync / DisableAnimatorSync

Periodically sends current Animator state to clients.

EnableLegacyAnimationSync / DisableLegacyAnimationSync

Periodically sends current legacy Animation state to clients.

SyncAnimatorState / SyncLegacyAnimationState

Sends current animation state once.

SetLocalPosition / SetLocalRotation / SetLocalScale

Queues a client transform command for this object.

LerpLocalPosition(Vector3 targetPosition, float lerpTime, string targetUsername = null)

Moves this object smoothly from its current position to the target over lerpTime seconds.

LerpLocalRotation(Vector3 targetEulerAngles, float lerpTime, string targetUsername = null)

Spherically interpolates this object's rotation to the target euler angles.

LerpLocalScale(Vector3 targetScale, float lerpTime, string targetUsername = null)

Interpolates this object's local scale to the target.

LerpLocalTransform(Vector3 targetPosition, Vector3 targetEulerAngles, Vector3 targetScale, float lerpTime, string targetUsername = null)

Interpolates position, rotation, and scale together using one command.

SetColliderEnabled / SetRigidbodyKinematic

Controls collider or rigidbody state by index.

Target Object Client Commands

These overloads take SceneObject targetObject first and queue the command for that object id.

SetMaterialFloat(SceneObject targetObject, int materialIndex, string propertyName, float value, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Sets a target object's material float property.

SetMaterialColor(SceneObject targetObject, int materialIndex, string propertyName, Color value, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Sets a target object's material color property.

SetMaterialKeyword(SceneObject targetObject, int materialIndex, string keyword, bool enabled, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Enables or disables a target object's material keyword.

SetRendererVisible(SceneObject targetObject, bool visible, string targetUsername = null, int rendererIndex = 0, bool includeChildren = true)

Sets target renderer visibility.

SetRendererVisibleForUser(string targetUsername, SceneObject targetObject, bool visible, int rendererIndex = 0, bool includeChildren = true)

Changes a target object's renderer visibility only for the named user. The setting is temporary and a later public SetRendererVisible command replaces it normally.

SetLightEnabled / SetLightIntensity / SetLightColor

Controls a target light by index.

SetAudioVolume / SetAudioPitch / PlayAudio / StopAudio

Controls a target audio source by index.

SetAnimatorTrigger / SetAnimatorBool

Controls a target animator by index.

SyncAnimatorState / SyncLegacyAnimationState

Sends a target object's current animation state once.

SetLocalPosition / SetLocalRotation / SetLocalScale

Queues a client transform command for a target object.

LerpLocalPosition(SceneObject targetObject, Vector3 targetPosition, float lerpTime, string targetUsername = null)

Moves a target object smoothly from its current position to the destination.

LerpLocalRotation(SceneObject targetObject, Vector3 targetEulerAngles, float lerpTime, string targetUsername = null)

Spherically interpolates a target object's rotation.

LerpLocalScale(SceneObject targetObject, Vector3 targetScale, float lerpTime, string targetUsername = null)

Interpolates a target object's local scale.

LerpLocalTransform(SceneObject targetObject, Vector3 targetPosition, Vector3 targetEulerAngles, Vector3 targetScale, float lerpTime, string targetUsername = null)

Interpolates all three transform channels on a target object using one command.

SetColliderEnabled / SetRigidbodyKinematic

Controls a target collider or rigidbody by index.

Timed transform behavior.

Leave targetUsername empty (or use *, all, or everyone) to run the interpolation on every client and on the shared instance-server object. A specific username runs only on that user's client and does not move the server copy. A newer lerp replaces the affected transform channel; an immediate SetLocalPosition, SetLocalRotation, or SetLocalScale cancels the matching lerp. For continuous motion, send future waypoints at a modest interval and make lerpTime equal to or slightly longer than that interval.

Material Emission At Runtime

SV Standard Lit materials expose _EmissionIntensity for glow strength and _EmissionColor for glow color. Set intensity above 0 to make the material emissive, and set intensity back to 0 with a black emission color to turn it off.

SetMaterialFloat(target, materialIndex, "_EmissionIntensity", level)

Sets the emission level. 0 is off; values like 1 to 3 are useful for visible glow.

SetMaterialColor(target, materialIndex, "_EmissionColor", color)

Sets the emitted color. Use a bright color while lit and Color.black when resetting.

_SVEmissionUseMap

Leave this off for normal SV Standard Lit glow through the base texture. Turn it on only when the material has a dedicated emission mask map.

SetMaterialFloat(target, 0, "_EmissionIntensity", 1.5f);
SetMaterialColor(target, 0, "_EmissionColor", Color.white);

SetMaterialFloat(target, 0, "_EmissionIntensity", 0f);
SetMaterialColor(target, 0, "_EmissionColor", Color.black);

Spritesheet Material Helpers

Spritesheet helpers are target-object commands. They expect materials with the spritesheet properties used by the runtime animator.

SetSpritesheetFrame(SceneObject targetObject, int frame, string targetUsername = null, int rendererIndex = 0, int materialIndex = 0, bool includeChildren = true)

Sets the target material frame.

SetSpritesheetPlayback(SceneObject targetObject, bool animate, float autoAdvanceSeconds, bool loop, string targetUsername = null, int rendererIndex = 0, int materialIndex = 0, bool includeChildren = true)

Sets animation, frame advance interval, and looping.

SetSpritesheetMaterial(SceneObject targetObject, int? frame = null, bool? animate = null, float? autoAdvanceSeconds = null, bool? loop = null, bool? affectMaps = null, string targetUsername = null, int rendererIndex = 0, int materialIndex = 0, bool includeChildren = true)

Applies any combination of frame, playback, loop, and map-affecting settings. Commands are persistent for late-joining clients.

Inventory Spawning And Player Controls

SpawnInventoryItem(InventoryItem item, Vector3 position, Vector3 eulerAngles, Vector3 scale)

Spawns an inventory item, returns a SceneObject, and queues a persistent spawn command for clients.

DespawnSpawnedObject(SceneObject spawnedObject)

Removes a spawned object, clears its persistent spawn command, and queues a despawn command.

TeleportPlayer(string username, Vector3 position, Vector3 eulerAngles)

Queues a teleport command for one username.

PlayPlayerEmote(string username, string emoteId)

Requests an emote for one user.

PlayPlayerEmote(string username, Emote emote)

Requests an emote using an Emote inventory reference.

PlayEmoteForAll / StopPlayerEmote / StopAllPlayerEmotes

Controls emotes globally or by username.

SetPlayerScale(string username, float scale)

Sets uniform scale for one user.

SetPlayerScale(string username, Vector3 scale)

Sets non-uniform scale for one user.

SetAllPlayerScales(float scale) / SetAllPlayerScales(Vector3 scale)

Sets player scale for everyone.

SetMediaScreenUrl(string url)

Sets all media screens to a URL.

SetMediaScreenUrl(string mediaScreenId, string url)

Sets one media screen id, or * for all media screens.

SetMediaScreenUrlForUser(string targetUsername, string url)

Sets all media screens to a URL only for the named user. Stored database rows are ignored for that user until a live public media update arrives. The override is not restored after rejoining.

SetMediaScreenUrlForUser(string targetUsername, string mediaScreenId, string url)

Sets one media screen, or * for all screens, only for the named user. A public SetMediaScreenUrl or /media update releases the matching private override.

GetCurrentSceneIdentifier()

Returns the current scene instance EventID for the server script. This is useful for logs and instance-specific script behavior.

Avatar Clone Spawning

Avatar clones are spawned and animated on the instance server, then serialized to clients through player-style packets. Keep the returned AvatarClone reference if you want to move it, force emotes, slot it into a sitpoint, or destroy it later.

SpawnAvatarClone(string username, Vector3 position)

Spawns a clone of the named user's avatar at a world position and returns an AvatarClone reference.

SpawnAvatarClone(string username, Vector3 position, Vector3 eulerAngles)

Spawns a clone with a world position and rotation.

SpawnAvatarClone(string username, Vector3 position, Vector3 eulerAngles, Vector3 scale)

Spawns a clone with a world position, rotation, and scale.

DestroyAvatarClone(AvatarClone clone)

Destroys a spawned clone. Clients remove it when the server stops sending clone packets.

SetAvatarClonePosition(AvatarClone clone, Vector3 position)

Moves a clone to a world position.

SetAvatarCloneRotation(AvatarClone clone, Vector3 eulerAngles)

Sets clone world rotation in Euler angles.

SetAvatarCloneScale(AvatarClone clone, Vector3 scale)

Sets clone scale.

SetAvatarCloneTransform(AvatarClone clone, Vector3 position, Vector3 eulerAngles, Vector3 scale)

Sets clone position, rotation, and scale in one command.

PlayAvatarCloneEmote(AvatarClone clone, string emoteId)

Forces the clone to play an emote by id on the server. The resulting bones are serialized to clients like player bones.

PlayAvatarCloneEmote(AvatarClone clone, Emote emote)

Forces the clone to play a slotted Emote inventory reference.

StopAvatarCloneEmote(AvatarClone clone)

Stops the clone's forced emote.

SeatAvatarClone(AvatarClone clone, Sitpoint sitpoint)

Slots the clone into a slotted Sitpoint.

StandAvatarClone(AvatarClone clone)

Removes the clone from its current sitpoint.

AvatarClone Reference Methods

clone.Destroy()

Same as DestroyAvatarClone(clone).

clone.SetPosition(position) / SetRotation(eulerAngles) / SetScale(scale) / SetTransform(position, eulerAngles, scale)

Convenience methods for controlling the cached clone reference.

clone.PlayEmote(emoteId) / PlayEmote(emote) / StopEmote()

Convenience methods for forcing or stopping server-side clone emotes.

clone.Sit(sitpoint) / clone.Stand()

Convenience methods for sitpoint slotting.

public Emote selectedEmote;
public Sitpoint cloneSeat;

AvatarClone clone;

void SpawnOne(string username)
{
    clone = SpawnAvatarClone(username, transform.position + Vector3.forward * 2f);
}

void ToggleEmote()
{
    if (clone != null && !clone.IsNull)
        clone.PlayEmote(selectedEmote);
}

void SitClone()
{
    if (clone != null && !clone.IsNull)
        clone.Sit(cloneSeat);
}

void RemoveClone()
{
    if (clone != null && !clone.IsNull)
        clone.Destroy();
}

Character Physics

These helpers queue client commands for one username. The receiving client applies the effect to that user's local avatar and returns to normal walking when the mode is stopped or an auto-stand delay finishes.

SetCharacterPhysicsMode(string username, SVCharacterPhysicsMode mode, float transitionSeconds = 0.8f, float autoStandAfterSeconds = 0f)

Starts a character physics mode for one user. Use SVCharacterPhysicsMode.Falling for fall trigger zones. Set autoStandAfterSeconds above 0 to recover automatically.

StopCharacterPhysicsMode(string username, float transitionSeconds = 0.8f)

Stops character physics and returns the targeted user's local avatar to normal movement.

ApplyCharacterImpact(string username, Vector3 direction, float power = 8f, float durationSeconds = 0.15f, bool fall = true, float autoStandAfterSeconds = 0f, SVCharacterImpactPart part = SVCharacterImpactPart.All)

Applies an impact to the targeted user's local avatar. Use direction = Vector3.zero, power = 0, fall = true, and a short autoStandAfterSeconds value for drop/recover behavior.

// Start falling for the player who entered a trigger.
SetCharacterPhysicsMode(info.Username, SVCharacterPhysicsMode.Falling, 0.15f);

// Stop when the player reaches the landing trigger.
StopCharacterPhysicsMode(info.Username, 0.8f);

// Drop in place and recover after 3 seconds.
ApplyCharacterImpact(info.Username, Vector3.zero, 0f, 0f, true, 3f);

Chat Commands And Room Messages

RegisterChatCommand(Action<SVChatCommandInfo> callback)

Listens for every non-system slash command that was not handled by the game client command list.

RegisterChatCommand(string command, Action<SVChatCommandInfo> callback)

Listens for one custom slash command such as /roll. The leading slash is optional.

StopListeningForChatCommand(string command = null)

Removes this script's chat command listener for one command, or all chat command listeners when omitted.

SendScriptChat(string message)

Inserts a room chat history entry from the fake username [Script].

Interactables, Triggers, Collisions, And Sitpoint Input

MakeInteractable(Action<SVInteractionInfo> onInteract, bool highlight = true, string targetUsername = null, bool includeChildren = true, float raycastDistance = 10f, string hintText = null)

Makes the script object interactable and calls the callback when activated.

MakeInteractable(SceneObject targetObject, Action<SVInteractionInfo> onInteract, bool highlight = true, string targetUsername = null, bool includeChildren = true, float raycastDistance = 10f, string hintText = null)

Makes a target object interactable.

RegisterTrigger(Action<SVTriggerInfo> onEnter, Action<SVTriggerInfo> onExit = null, bool includeChildren = true)

Registers trigger callbacks on the script object.

RegisterTrigger(SceneObject targetObject, Action<SVTriggerInfo> onEnter, Action<SVTriggerInfo> onExit = null, bool includeChildren = true)

Registers trigger callbacks on a target object.

RegisterCollision(Action<SVCollisionInfo> onCollision, bool includeChildren = true)

Registers a server-side collision callback on the script object. The callback receives the collided object's ObjectName and ObjectId.

RegisterCollision(SceneObject targetObject, Action<SVCollisionInfo> onCollision, bool includeChildren = true)

Registers a server-side collision callback on a target object or its child colliders.

RegisterSitpointInput(Action<SVSitpointInputInfo> onInput)

Registers a callback for input from the sitpoint associated with this script's network id.

Advanced Helpers

EmitClientCommand(string command, string payloadJson, string targetUsername = null)

Queues a raw client command for this script object's network id.

EmitClientCommand(SceneObject targetObject, string command, string payloadJson, string targetUsername = null)

Queues a raw client command for a target object id.

Log(string msg)

Writes a normal log message prefixed with the script name.

LogWarning(string msg)

Writes a warning prefixed with the script name.

LogError(string msg)

Writes an error prefixed with the script name.