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)