GameObject

GameObject provides scene lookup, active-state control, tags, layers, and bounded calls between Lua Behaviours. IDs are integers owned by the scene; cache resolved IDs and validate them with GameObject.Exists when lifetime may have changed.

Lookup and State

Method	Returns	Description
GameObject.Find(name)	integer	Finds a GameObject by exact name, including inactive objects, or -1.
GameObject.Exists(gameObjectId)	boolean	Checks whether an ID is valid.
GameObject.GetName(gameObjectId)	string or nil	Reads the display name.
GameObject.IsActive(gameObjectId)	boolean or nil	Reads the active state.
GameObject.SetActive(gameObjectId, active)	boolean	Changes the active state.

Changing active state dispatches OnEnable or OnDisable only when the state actually changes.

local gateGameObjectId = -1

function Start(gameObjectId)
  gateGameObjectId = GameObject.Find("Security Gate")
  if not GameObject.Exists(gateGameObjectId) then
    Log.Print("Security Gate was not found")
  end
end

function OpenGate()
  if GameObject.Exists(gateGameObjectId) then
    GameObject.SetActive(gateGameObjectId, false)
  end
end

Tags and Layers

Method	Returns	Description
GameObject.CompareTag(gameObjectId, tag)	boolean	Compares the baked tag without allocating.
GameObject.GetLayer(gameObjectId)	integer	Returns the physics/render layer.
GameObject.SetLayer(gameObjectId, layer)	boolean	Sets a layer inside the project's baked range.

Use CompareTag in collision callbacks instead of reading and comparing names. Layers are also accepted by Physics.Raycast through its optional layer mask.

Calling Another Lua Behaviour

GameObject.Invoke(
  targetGameObjectId,
  "Open",
  sourceGameObjectId,
  0,
  "keycard",
  "accepted"
)

GameObject.Invoke returns false when the target, Lua Behaviour, or function does not exist, or the call cannot run within the scripting budget. It supports up to two integer and two string arguments after the function name. The target function receives its own GameObject ID first:

function Open(gameObjectId, sourceGameObjectId, unusedValue, itemName, result)
  Log.Print(itemName .. " was " .. result)
end

UI Buttons, Interactables, and Timeline script events use the same exact-name callback model. Custom callback names are project-defined; engine lifecycle and API names remain PascalCase.

GameObject.Find can find inactive objects. Use GameObject.IsActive when you need to check their state. Keep names unique because lookup returns the first match, and find objects again after changing scenes.