World
Contains functions for finding and creating entities.
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 citizenEntity = World.findEntity("Citizen")
if citizenEntity then
citizenEntity.position = Vector3.new(1,0,-17)
end
end
findEntities(tag)
Returns all the Entity that match the specified tag.
Parameters
- tag — A string containing the entity tag.
Returns
An array of Entity that matches the tag, or an empty array if none was found.
Example
Get all entities with the tag "Citizen" and move them to the position (1,0,-17).
function onStart()
local citizens = World.findEntities("Citizen")
for i, citizenEntity in ipairs(citizens) do
citizenEntity.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.