ScriptAPI guide
Write scripts as small C# classes, expose the values designers need, and let SimuScriptBase handle world events, object targeting, and client commands.
Every ScriptAPI script is a C# class that derives from SimuScriptBase. Most scripts import Simuspaces.Simulation, then override lifecycle methods such as Start, OnDestroy, OnUserJoin, or OnUserSit.
Small scripts are easier to slot, test, and reuse. For example, keep a light toggle, a trigger reset, and a sitpoint vehicle controller as separate scripts unless they truly share state.
Public fields are the main way to make a script configurable. The examples use public values for object slots, inventory picks, usernames, timings, booleans, colors, distances, frame counts, and scale values.
SceneObject
Use for a generic target object. Check IsNull or Exists before acting on it.
Sitpoint
Use when the field should point at a sitpoint and expose SitpointId.
SVLight
Use for a light target. It resolves the first Light on the object or in children.
InventoryItem
Use for spawnable inventory. The field carries InventoryId and Kind.
Emote
Use for player emote selection. It is an InventoryItem with kind Emote.
int, float, bool, string, Vector3, Color
Use for common tuning values such as cooldowns, distances, offsets, colors, scales, labels, or target usernames.
List<T>
Use for repeatable inspector rows. Supported element types use the same widgets as normal public fields, including text, numbers, toggles, colors, vectors, and slottable ScriptAPI object references.
Public List<T> fields appear in the SV Inspector as editable lists instead of a raw new List<T>() string. Users can expand the list, add rows, remove rows, and edit each row with the normal widget for that element type.
Use new List<T>() so the script can safely read Count, add entries, and iterate even before the inspector has rows.
using System.Collections.Generic;
using Simuspaces.Simulation;
public class ListFieldsExample : SimuScriptBase
{
public List<SceneObject> targets = new List<SceneObject>();
public List<string> labels = new List<string>();
public List<int> materialSlots = new List<int>();
public List<float> glowLevels = new List<float>();
public List<bool> enabledRows = new List<bool>();
}SceneObject wraps a scene object id and resolves it at runtime through the scene object registry. Use it instead of storing raw object ids yourself.
Use gameObject and transform for the object the script is attached to. Self-targeted helpers such as PlayAudio() and SetRendererVisible() operate on this object.
Use a public SceneObject field and the overloads that accept SceneObject targetObject when the script controls a separate object.
Many helpers include includeChildren, defaulting to true. Component indexes count through the resolved component list.
The protected slots dictionary is available for runtime-assigned named GameObject slots when the host runtime provides them.
User callbacks and client commands use usernames as stable targets. Empty targetUsername, *, all, and everyone target every client. Any other non-empty value targets the matching username.
GetUsers()
Returns SVUserInfo snapshots for users currently known to the script runtime.
ForEachUser(callback)
Runs a callback for each active user and logs callback exceptions without breaking the loop.
OnUserJoin / OnUserPart
Override to respond as users enter or leave.
OnUserSit / OnUserStand
Override to respond to sitpoint occupancy changes.
RegisterChatCommand
Listens for custom slash commands entered in room chat. Use SVChatCommandInfo.Username, Command, ParameterText, and Args to respond.
SendScriptChat
Adds a room chat history entry from [Script], useful for command responses or scripted announcements.
User scripts compile as C# 8 with core System, System.Collections, System.Collections.Generic, UnityEngine, and the approved Simuspaces.Simulation ScriptAPI types. The compiler blocks editor APIs, file and network namespaces, reflection, diagnostics/process APIs, unsafe code, and direct modal dialog static calls that bypass the script command system.
When a task affects clients or shared world state, use helpers like ShowDialog, SetLightColor, PlayAudio, TeleportPlayer, or SpawnInventoryItem instead of trying to reach lower-level systems.
SimuScriptBase and import Simuspaces.Simulation.SceneObject, InventoryItem, and Emote fields before using them.Start.Log, LogWarning, and LogError for messages with the script name prefix.