Skip to main content

World

Contains functions for finding and creating entities.

info

This module can only be used in Entity scripts.

Functions

findEntity(tag)

Returns the Entity that matches the specified tag. If there are multiple entities with the same tag, only one will be returned.

Parameters

  • tag A string containing the entity tag.

Returns

The Entity that matches the tag, or nil if none was found.

Example

Get an entity with the tag "Citizen" and move it to the position (1,0,-17).

function onStart()
local entityCitizen = World.findEntity("Citizen")
if entityCitizen then
-- assert if the entity exist at that location
entityCitizen.position = Vector3.new(1,0,-17)
end
end

assignScript(entity, scriptName, initialData)

Assigns a script, specified by name, to an Entity. Once assigned, the program in the script will start immediately.

Parameters

  • entity The Entity to assign the script.
  • scriptName The exact name of the script.
  • initialData Optional data payload that can be used in the script's onStart function.

Example

Assign a different script to an Entity with tag "Citizen" after 2 seconds.

function onStart()
-- first get the entity
local entityCitizen = World.findEntity("Citizen")
if entityCitizen then
entityCitizen.position = Vector3.new(1,0,-17)
World.assignScript(entityCitizen, "Citizen (2)")
end
end

assignTag(entity, tag)

Assigns a tag, to an Entity. If Entity already has a tag, it will be replaced with a new one.

Parameters

  • entity The Entity to assign the tag.
  • tag The tag to assign.

Example

Assign a tag to a new Entity and change position after 5 seconds.

function onStart()
-- first spawn the entity
local bearEntity = World.spawn("02:0004:00", Vector3.new(1,0,-4), Bearing.North)
World.assignTag(bearEntity, "Enemy")

Task.wait(5)

local lookup = World.findEntity("Enemy")
if lookup then
lookup.position = Vector3.new(1,5,-8)
end
end

spawn(entityCode, position, rotation, scale)

Spawns a new Entity.

Parameters

  • entityCode A string containing the Entity Code (you can find this in the inventory).
  • position A Vector3 containing the position of the Entity when it is spawned.
  • rotation A Vector3 of the orientation of the Entity when it is spawned.
  • scale A Vector3 for the size of the Entity when it is spawned.

Returns

The Entity that was spawned.

Example

Spawn a Bearracuda at (-10,0,-4) upside-down and twice as large.

function onStart()
World.spawn("02:0004:00", Vector3.new(-10,0,-4), Vector3.new(180,0,0),Vector3.new(2,2,2))
end

getPersistentData(key)

Returns persistent data stored.

Parameters

  • key A string containing the key used to identify the data cache.

Example

Change the behaviour of an entity based on how many levels are unlocked at the start of the world.

function onStart()
--... previously set
local levelsUnlcoked = World.getPersistentData("levelsUnlcked")
if levelsUnlocked == 3 then
-- ... logic
end
end

setPersistentData(key, value)

Stores data in a cache for the world in which the script is running.

Parameters

  • key A string containing the key used to identify the data cache.
  • value The data to store in the cache.

Example

Stores the current level unlocked in the world, in this example, 5 levels are unlocked.

--... world code
World.setPersistentData("levelsUnlocked", 5)

barrierBlocks(barrier, target)

Returns true if the specified Barrier object blocks the specified target.

Parameters

  • barrier Reference to the target Barrier.
  • target Target Player, Entity, Entity Code or BarrierLayer.