Wild Life Lua Documentation

Welcome to the official Wild Life Lua documentation! This page should give a broad overview of all the functionality the lua implementation in Wild Life has to offer.


Contents


General

Lua Prop

In the sandbox, you can find the Lua Prop in the automation tab. After placing the prop and selecting it, you can open the code editor with syntax highlighting using the "Open Code Editor" button in the options panel.


Lua State

All Lua props share the same Lua State, meaning if you define a global variable/function/table etc in one prop and execute it, all other props will have access to these global definitions. If you want a prop to be the only one able to access it's own definitions, use the local keyword.


Execution

To execute the lua code, you can either use the "Test code" button in the top right of the code editor window, or you can use the event receiver called "Execute". Keep in mind, that the "Test code" button can execute the current lua code even if it wasn't saved to the lua prop yet. Every code execution has a quota of 500.000 operations to prevent unintentional game freezes in infinite recursive functions or infinite loops.


Execute snippet

You also have the option to execute lua code directly from an event parameter using the "Execute snippet" event receiver on the lua prop. This could be useful for things like setting global variable values.


Custom return types

SandboxObject 

This just contains a reference to a sandbox object in the outliner and can be used as a parameter in subsequent function calls.


Vector 

Vector.x - The X component of the vector
Vector.y - The Y component of the vector
Vector.z - The Z component of the vector

The Vector contains three components x, y and z, one for each axis.


Color 

Color.r - The red component of the color
Color.g - The green component of the color
Color.b - The blue component of the color
Color.a - The alpha component of the color

The Color contains four components r, g, b and a, one for each color channel.


VectorString 

A VectorString is the text representation of a Vector, used primarily for setting option values in the event system. This is only one part of the full OptionVectorString, which would be needed to be able to set the event system values.

It will have the format

"x=[xValue],y=[yValue],z=[zValue]"

so for example

"x=1.0,y=2.0,z=3.0"


OptionVectorString 

An OptionVectorString is the text representation of a Vector together with an option name, used primarily for setting option values in the event system.

It will have the format

"[optionName];x=[xValue],y=[yValue],z=[zValue]"

so for example

"StartLocation;x=1.0,y=2.0,z=3.0"


ColorString 

A ColorString is the text representation of a Color, used primarily for setting option values in the event system. This is only one part of the full OptionColorString, which would be needed to be able to set the event system values.

It will have the format

"r=[rValue],g=[gValue],b=[bValue],a=[aValue]"

so for example

"r=0.5,g=0.2,b=0.75,a=1.0"


OptionColorString 

An OptionColorString is the text representation of a Color together with an option name, used primarily for setting option values in the event system.

It will have the format

"[optionName];r=[rValue],g=[gValue],b=[bValue],a=[aValue]"

so for example

"color;r=0.5,g=0.2,b=0.75,a=1.0"


RayCastHit 

RayCastHit.did_hit            - true or false depending on if the ray hit anything
RayCastHit.hit_point          - Contains the location where the raycast hit something as a vector, all zero if the ray did not hit anything
RayCastHit.hit_point.x        - The X component of the hit point
RayCastHit.hit_point.y        - The Y component of the hit point
RayCastHit.hit_point.z        - The Z component of the hit point
RayCastHit.hit_normal         - Contains the normal of the surface it hit, meaning the direction of the face of the geometry, as a vector
RayCastHit.hit_normal.x       - The X component of the hit normal
RayCastHit.hit_normal.y       - The Y component of the hit normal
RayCastHit.hit_normal.z       - The Z component of the hit normal
RayCastHit.time               - The normalized position of the hit between the start and end of the ray, i.e. close to the start is 0 and close to the end is 1
RayCastHit.distance           - The distance between the start point and the hit point of the ray, in centimeters
RayCastHit.hit_sandbox_object - If the hit was another sandbox object, this will contain a reference to that object

A RayCastHit is returned when using the wl_raycast function. It will contain all relevant information on what, where and if it hit something. When using most of the data it is recommended to check whether did_hit is true first to ensure the data is accurate for your use case.


Functions

Default allowed Lua functions

Not all default functions that lua provides will work in Wild Life for security reasons, but here is a list of all the whitelisted functions:


Wild Life specific Lua functions

These are all the functions we provide for the lua implementation:


Wild Life Function examples

Data

wl_data_save (data, fileName) → bool

This function can be used to save custom data onto the hard drive for later use. The save location will always be in the "%localappdata%/WildLifeC/Saved/SandboxSaveGames/CustomSaves/" folder.
Of course, having the power to save any amount of data needs to be restricted for security purposes, so saving data has the following limitations:

  • The file name may only contain characters a-z, A-Z and 0-9
  • The saved data may not exceed 1MB
  • You are only allowed 10 separate file names before the sandbox will block any new files being created. You can reset the block by resetting the lua state (Trash icon in the lua editor, this will also clean all globally defined functions and variables).

    • You can save both single values as well as tables using this function. If you require a lot of values to be saved, it is recommended to create a save structure lua table containing all the values you want to save. Tables are saved as json strings. Also, make sure to use unique file names so that they don't clash with other creators' scenes, since all custom save files share the same folder.

    Example:

    saveData = {}
saveData.playerPosition = wl_make_vector(1,2,3)
saveData.playerName = "Hans"
saveData.playerMoney = 69420
saveData.playerHasSeenIntro = true
saveData.enemiesDefeated = 24
saveData.deaths = 3

wl_data_save(saveData, "MySceneNameSaveData")

    This code creates a table with arbitrary data we want to save and then saves it to file file named "MySceneNameSaveData".


    wl_data_load (fileName) → table/value

    This function allows you to load save data from the "%localappdata%/WildLifeC/Saved/SandboxSaveGames/CustomSaves/" folder. If the file failed to load, the function will return 'nil' instead.
    Loading files has the following limitations:

  • The file name may only contain characters a-z, A-Z and 0-9

    • Example:

    loadedData = wl_data_load("MySceneNameSaveData")
if (loadedData ~= nil) then
    wl_print_table(loadedData)
end

    This code will try to load a file named "MySceneNameSaveData", and if it didn't return 'nil', it will be printed into the log.


    wl_data_exists (fileName)

    This function allows you to check whether a save file exists before trying to load, save or delete it.
    Checking files has the following limitations:

  • The file name may only contain characters a-z, A-Z and 0-9

    • Example:

    if (wl_data_exists("MySceneNameSaveData") == true) then
    print("File exists! :)")
else
    print("File doesn't exist! :(")
end

    This code tries to find a file named "MySceneNameSaveData" and prints to the log whether it exists or not.


    wl_data_delete (fileName) → bool

    This functions allows you to delete a save file in the "%localappdata%/WildLifeC/Saved/SandboxSaveGames/CustomSaves/" folder. It will return either 'true' or 'false', depending on the success or failure of the deletion.
    Deleting files has the following limitations:

  • The file name may only contain characters a-z, A-Z and 0-9

    • Example:

    if (wl_data_delete("MySceneNameSaveData") == true) then
    print("File was deleted successfully!")
else
    print("File could not be deleted!")
end

    This code tries to delete a file named "MySceneNameSaveData" and prints to the log whether it was successful or not.




    Editor

    wl_editor_get_active_object () → SandboxObject

    Returns the active object of a selection, meaning the object that currently has the movement gizmo attached to it.

    Example:

    active_object = wl_editor_get_active_object()
print(active_object)

    This code will print the current active object to the log


    wl_editor_get_selection () → SandboxObject array

    Returns an array of all of the currently selected objects in the outliner

    Example:

    selected = wl_editor_get_selection()
for i = 1, #selected do
    print(selected[i])
end

    This code will print all currently selected objects into the log


    wl_editor_set_active_object (sandboxObject) → bool

    This function can be used to set the current active object, meaning the object that currently has the movement gizmo attached to it. This will only succeed if the given sandboxObject is not locked and is part of the current selection. Returns true when successful, otherwise false

    Example:

    player = wl_get_player_object()
wl_editor_set_active_object(player)

    This code will set the player as the active object. This will only have an effect if the player is already part of the selection.


    wl_editor_set_selection (sandboxObjects) → bool

    Sets the current selection of the editor. This function accepts a sandboxObject array, a single sandboxObject and nil. nil will deselect everything. Returns true if successful, otherwise false.

    Example:

    player = wl_get_player_object()
wl_editor_set_selection(player)

    This code will select the current player object in the editor.


    (Experimental) wl_editor_spawn_prop (propID [, name]) → SandboxObject

    This function will spawn a prop into the world. The 'propID' of a prop can be found when hovering over the desired prop in the editor. If spawned successful, this function will return the newly spawned prop, otherwise nil. Keep in mind that specifying an unknown propID will not result in a nil object, but rather a "Missing Prop" object.
    Optionally, if the 'name' parameter is set, the newly spawned prop will have that name in the outliner.

    Example:

    cube = wl_editor_spawn_prop("Cube", "My awesome cube")

    This code spawns a prototype cube object into the world with the name "My awesome cube".


    (Experimental) wl_editor_duplicate_object (sandboxObject) → bool

    This function will attempt to duplicate the specified 'sandboxObject' with all it's children. Returns true if successful, otherwise false.

    Example:

    me = wl_get_object_self()
wl_editor_duplicate_object(me)

    This code will duplicate the executing Lua prop.


    (Experimental) wl_editor_delete_object (sandboxObject) → bool

    This function can be used to delete the specified 'sandboxObject'. Returns true if successful, otherwise false.

    Example:

    cube = wl_get_object("Cube")
wl_editor_delete_object(cube)

    This code gets the first object named "Cube" and deletes it.




    Events

    wl_add_event_to_dispatcher (sandboxObject, dispatcherID, eventName, eventValue)

    Adds an event to an event dispatcher on 'sandboxObject'. The 'dispatcherID' is the ID of the dispatcher you want to add the event to.
    Tip: if you click on the label of a dispatcher, it will automatically copy the dispatcher ID to the clipboard for you to paste it into your code.

    Example:

    button = wl_get_object("Button")
wl_add_event_to_dispatcher(button, "OnButtonDown", "SetCubeVisibilityOn", "true")

    This code adds an event to the "OnButtonDown" dispatcher on the first sandbox object named "Button".


    wl_add_event_to_receiver (sandboxObject, receiverID, eventName, eventValue)

    Adds an event to an event receiver on 'sandboxObject'. The 'receiverID' is the ID of the receiver you want to add the event to.
    Tip: if you click on the label of a receiver, it will automatically copy the receiver ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
wl_add_event_to_receiver(cube, "SetVisibility", "SetCubeVisibilityOn", "true")

    This code adds an event to the "SetVisibility" receiver on the first sandbox object named "Cube".


    wl_dispatch_event (eventName, eventValue)

    Dispatches an event just like any other prop can using the event system. As the parameters suggest, 'eventName' would be the name of the event to be fired, and 'eventValue' would be the value (or parameter) of the event.

    Example:

    wl_dispatch_event("ButtonVisibility", false)

    Let's say the current sandbox scene contains a Button that has "ButtonVisibility" bound to it's "Set visibility" receiver. This code would make that button invisible when executed. Similarly, if you would use "true" instead of "false", the button would become visible again.


    wl_dispatch_event_to_object (eventName, eventValue, sandboxObject)

    Dispatches an event just like any other prop can using the event system, except it will only send it to 'sandboxObject'. As the parameters suggest, 'eventName' would be the name of the event to be fired, and 'eventValue' would be the value (or parameter) of the event.

    Example:

    button = wl_get_object("Play Button")
wl_dispatch_event_to_object("ButtonVisibility", false, button)

    If there are multiple objects that use "ButtonVisibility" in any of their receivers, none of them will receive the event unless they are the first sandbox object named "Play Button".


    (Experimental) wl_event_system_add_listener (eventName, luaFunctionString) → bool [NEW]

    Will add a listener on a specific event 'eventName' and calls the given 'luaFunctionString' function with the parameter which the event dispatched with. Adding the same event to the same function multiple times will be ignored. Returns true if successful, otherwise false.

    Example:

    function print_event_value_to_log(value)
    print(value)
end

function init()
    wl_event_system_add_listener("PrintToLuaLog", "print_event_value_to_log")
end

init()

    This code will add an event listener for the event named "PrintToLuaLog" and call the print_event_value_to_log(value) function when it receives that event.


    (Experimental) wl_event_system_remove_listener (eventName, luaFunctionString) → bool [NEW]

    Will remove a listener from a specific event 'eventName' which points to 'luaFunctionString'. If no listener exists, nothing will happen. Returns true if successful, otherwise false.

    Example:

    function print_event_value_to_log(value)
    print(value)
end

function init()
    wl_event_system_remove_listener("PrintToLuaLog", "print_event_value_to_log")
end

init()

    This code will remove an existing event listener for the event named "PrintToLuaLog" which points to the print_event_value_to_log(value) function.


    wl_get_call_argument_as_bool () → bool [NEW]

    Returns the last argument/parameter that was used to execute this code as a bool (Execute event parameter or Test Code Button Parameter).
    This function will try to convert the parameter into a bool, if it fails, it will return false.

    Example:

    print(wl_get_call_argument_as_bool())

    This code will print the argument used to call this function into the log.


    wl_get_call_argument_as_color () → Color [NEW]

    Returns the last argument/parameter that was used to execute this code as a color (Execute event parameter or Test Code Button Parameter).
    This function will try to convert the parameter into a color, if it fails, it will return black with full opacity.

    Example:

    wl_print_color(wl_get_call_argument_as_color())

    This code will print the argument used to call this function into the log.


    wl_get_call_argument_as_float () → float [NEW]

    Returns the last argument/parameter that was used to execute this code as a float (Execute event parameter or Test Code Button Parameter).
    This function will try to convert the parameter into a float, if it fails, it will return 0.

    Example:

    print(wl_get_call_argument_as_float())

    This code will print the argument used to call this function into the log.


    wl_get_call_argument_as_integer () → integer [NEW]

    Returns the last argument/parameter that was used to execute this code as an integer (Execute event parameter or Test Code Button Parameter).
    This function will try to convert the parameter into an integer, if it fails, it will return 0.

    Example:

    print(wl_get_call_argument_as_integer())

    This code will print the argument used to call this function into the log.


    wl_get_call_argument_as_string () → string [NEW]

    Returns the last argument/parameter that was used to execute this code as a string (Execute event parameter or Test Code Button Parameter).
    Since event parameters are always passed around as strings, this is the most 'accurate' value.

    Example:

    print(wl_get_call_argument_as_string())

    This code will print the argument used to call this function into the log.


    wl_get_call_argument_as_vector () → Vector [NEW]

    Returns the last argument/parameter that was used to execute this code as a vector (Execute event parameter or Test Code Button Parameter).
    This function will try to convert the parameter into a vector, if it fails, it will return a zero vector.

    Example:

    wl_print_vector(wl_get_call_argument_as_vector())

    This code will print the argument used to call this function into the log.


    wl_get_object_dispatchers_enabled (sandboxObject) → bool

    Returns whether the given 'sandboxObject' has it's event dispatchers enabled or not.

    Example:

    button = wl_get_object("Button")
is_enabled = wl_get_object_dispatchers_enabled(button)
print(is_enabled)

    This code will print whether the first object named "Button" has it's event dispatchers enabled or not.


    wl_get_object_receivers_enabled (sandboxObject) → bool

    Returns whether the given 'sandboxObject' has it's event receivers enabled or not.

    Example:

    cube = wl_get_object("Cube")
is_enabled = wl_get_object_receivers_enabled(cube)
print(is_enabled)

    This code will print whether the first object named "Cube" has it's event receivers enabled or not.


    wl_remove_event_from_dispatcher (sandboxObject, dispatcherID, eventName)

    Removes an event from an event dispatcher on 'sandboxObject'. The 'dispatcherID' is the ID of the dispatcher you want to remove the event from.
    Tip: if you click on the label of a dispatcher, it will automatically copy the dispatcher ID to the clipboard for you to paste it into your code.

    Example:

    button = wl_get_object("Button")
wl_remove_event_from_dispatcher(cube, "OnButtonDown", "SetCubeVisibilityOn")

    This code removes an event called "SetCubeVisibilityOn" from the "OnButtonDown" dispatcher on the first sandbox object named "Button"


    wl_remove_event_from_receiver (sandboxObject, receiverID, eventName)

    Removes an event from an event receiver on 'sandboxObject'. The 'receiverID' is the ID of the receiver you want to remove the event from.
    Tip: if you click on the label of a receiver, it will automatically copy the receiver ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
wl_remove_event_from_receiver(cube, "SetVisibility", "SetCubeVisibilityOn")

    This code removes an event called "SetCubeVisibilityOn" from the "SetVisibility" receiver on the first sandbox object named "Cube"


    wl_set_object_dispatchers_enabled (sandboxObject, newEnabled)

    This function can be used to enable or disable the event dispatchers of the given 'sandboxObject'.

    Example:

    button = wl_get_object("Button")
wl_set_object_dispatchers_enabled(button, false)

    This code will disable the event dispatchers on the first sandbox object named "Button".


    wl_set_object_receivers_enabled (sandboxObject, newEnabled)

    This function can be used to enable or disable the event receivers of the given 'sandboxObject'.

    Example:

    cube = wl_get_object("Cube")
wl_set_object_receivers_enabled(cube, false)

    This code will disable the event receivers on the first sandbox object named "Cube".




    Hierarchy

    wl_get_object (objectName) → SandboxObject

    Returns a reference to the first sandbox object in the outliner named 'objectName'. Since this function potentially needs to iterate over lots of sandbox objects, it is better to cache the return value in a variable at game start and then using the variable in subsequent function calls

    Example:

    cube = wl_get_object("Cube")
print(cube)

    This code will get a sandbox object with the name "Cube" and print it's ID to the log


    wl_get_object_below (objectName, sandboxObject) → SandboxObject

    Similarly to wl_get_object, this returns a sandbox object with the name 'objectName', but it will only search for a sandbox object that is parented below the given 'sandboxObject'. Since this function potentially needs to iterate over lots of sandbox objects, it is better to cache the return value in a variable at game start and then using the variable in subsequent function calls

    Example:
    Say we have the following outliner hierarchy:

    Lamp Post 1
        Post
        Light
    Lamp Post 2
        Post
        Light
    Lamp Post 3
        Post
        Light

    As you can see, there are multiple sandbox objects with the name "Light".

    Example:

    lamp_post = wl_get_object("Lamp post 2")
light = wl_get_object_below("Light", lamp_post)
print(light)

    This example code would print the ID of the "Light" object under "Lamp post 2", since that was the given second parameter.


    wl_get_object_children (sandboxObject) → SandboxObject array

    Returns an array of all the direct children the 'sandboxObject' has. If you also want to retrieve children of children, use wl_get_object_children_recursive instead.
    Caution: Lua arrays are 1-indexed, meaning the first element of an array is in array[1] and not in array[0].

    Example:

    cube = wl_get_object("Cube")
cube_children = wl_get_object_children(cube)

for i = 1, #cube_children do
    print(wl_get_object_name(cube_children[i]))
end

    This code retrieves all direct children of the first object named "Cube" and prints each of their names into the log.


    wl_get_object_children_recursive (sandboxObject) → SandboxObject array

    Returns an array of all the children the 'sandboxObject' has. If you only want to retrieve the direct children of the object, use wl_get_object_children instead.
    Caution: Lua arrays are 1-indexed, meaning the first element of an array is in array[1] and not in array[0].

    Example:

    cube = wl_get_object("Cube")
cube_children = wl_get_object_children_recursive(cube)

for i = 1, #cube_children do
    print(wl_get_object_name(cube_children[i]))
end

    This code retrieves all children of the first object named "Cube" and prints each of their names into the log.


    wl_get_object_parent (sandboxObject) → SandboxObject

    Returns the object parent of the given 'sandboxObject'.

    Example:

    cube = wl_get_object("Cube")
cube_parent = wl_get_object_parent(cube)
print(wl_get_object_name(cube_parent))

    This code gets the first object named "Cube", accesses it's parent and saves it into the cube_parent variable. Then, the parent's name is printed to the log.


    wl_get_object_self () → SandboxObject

    Returns a reference to the Lua sandbox object that is currently executing this code.

    Example:

    lua = wl_get_object_self()
print(lua)

    This code will get the currently executing Lua prop and print it's ID to the log


    wl_get_object_self_children () → SandboxObject array

    Returns an array of all the direct children the currently executing Lua prop has. If you also want to retrieve children of children, use wl_get_object_self_children_recursive instead.
    Caution: Lua arrays are 1-indexed, meaning the first element of an array is in array[1] and not in array[0].

    Example:

    cube = wl_get_object("Cube")
lua_children = wl_get_object_self_children(cube)

for i = 1, #lua_children do
    print(wl_get_object_name(lua_children[i]))
end

    This code retrieves all direct children of the currently executing Lua prop and prints each of their names into the log.


    wl_get_object_self_children_recursive () → SandboxObject array

    Returns an array of all the children the currently executing Lua prop has. If you only want to retrieve the direct children of the object, use wl_get_object_self_children instead.
    Caution: Lua arrays are 1-indexed, meaning the first element of an array is in array[1] and not in array[0].

    Example:

    cube = wl_get_object("Cube")
lua_children = wl_get_object_self_children_recursive(cube)

for i = 1, #lua_children do
    print(wl_get_object_name(lua_children[i]))
end

    This code retrieves all children of the currently executing Lua prop and prints each of their names into the log.


    wl_get_object_self_parent () → SandboxObject

    Returns the object parent of the currently executing Lua prop.

    Example:

    lua_parent = wl_get_object_self_parent()
print(wl_get_object_name())

    This code prints the name of the parent of the currently executing Lua prop to the log.


    wl_get_objects (objectName) → SandboxObject array

    Similar to wl_get_object, but instead of returning the first instance of a sandbox object named 'objectName', it will instead return an array of all sandbox objects with that name.
    Caution: Lua arrays are 1-indexed, meaning the first element of an array is in array[1] and not in array[0]

    Example:

    cubes = wl_get_objects("Cube")

for i = 1, #cubes do
    print(cubes[i])
end

    This code retrieves an array of all sandbox objects named "Cube" and prints their IDs into the log.


    wl_get_player_object () → SandboxObject

    Returns the current player object.

    Example:

    player = wl_get_player_object()
print(player)

    This code will get the current player object and print it's ID into the log. It doesn't matter whether you possessed another object since game start, as soon as wl_get_player_object is called, it will contain the current player object.


    wl_get_object_over (sandboxObject [, amount [, onlyVisible]]) → SandboxObject [NEW]

    Will return an object that is above the given 'sandboxObject' in the scene outliner. The optional 'amount' parameter determines how many objects you want to go up, default is 1. The optional 'onlyVisible' parameter will change the behaviour of this function depending on the foldout state of the objects in the hierarchy: If all children of all objects in your scene are expanded, the function will always return the object directly above the specified 'sandboxObject' (if the amount is 1), but if you go up to an object with collapsed children, having 'onlyVisible' on 'true' will return the parent itself, while having 'onlyVisible' on 'false' will return that parent's last child (recursively). Default is false.

    Example:

    selection = wl_editor_get_selection()
newObj = wl_get_object_over(selection[1])
wl_editor_set_selection(newObj)

    This code will get the current editor selection (assumes one object is selected) and selects the object directly above it.


    wl_get_object_over_with_same_parent (sandboxObject [, amount]) → SandboxObject [NEW]

    Will return an object that is above the given 'sandboxObject' in the scene outliner but shares the same parent. The optional 'amount' parameter determines how many objects you want to go up, default is 1. If the 'sandboxObject' is already the top child in the hierarchy, trying to use this function with a positive amount will return nil since there are no objects above it sharing the same parent.

    Example:

    selection = wl_editor_get_selection()
newObj = wl_get_object_over_with_same_parent(selection[1])
wl_editor_set_selection(newObj)

    This code will get the current editor selection (assumes one object is selected) and selects the object directly above it which shares the same parent.


    wl_get_object_under (sandboxObject [, amount [, onlyVisible]]) → SandboxObject [NEW]

    Will return an object that is below the given 'sandboxObject' in the scene outliner. The optional 'amount' parameter determines how many objects you want to go down, default is 1. The optional 'onlyVisible' parameter will change the behaviour of this function depending on the foldout state of the objects in the hierarchy: If all children of all objects in your scene are expanded, the function will always return the object directly below the specified 'sandboxObject' (if the amount is 1), but if you go down from an object with collapsed children, having 'onlyVisible' on 'true' will return the next visible object, while having 'onlyVisible' on 'false' will return that parent's first child. Default is false.

    Example:

    selection = wl_editor_get_selection()
newObj = wl_get_object_under(selection[1])
wl_editor_set_selection(newObj)

    This code will get the current editor selection (assumes one object is selected) and selects the object directly below it.


    wl_get_object_under_with_same_parent (sandboxObject [, amount]) → SandboxObject [NEW]

    Will return an object that is below the given 'sandboxObject' in the scene outliner but shares the same parent. The optional 'amount' parameter determines how many objects you want to go down, default is 1. If the 'sandboxObject' is already the bottom child in the hierarchy, trying to use this function with a positive amount will return nil since there are no objects below it sharing the same parent.

    Example:

    selection = wl_editor_get_selection()
newObj = wl_get_object_under_with_same_parent(selection[1])
wl_editor_set_selection(newObj)

    This code will get the current editor selection (assumes one object is selected) and selects the object directly below it which shares the same parent.


    (Experimental) wl_set_object_parent (sandboxObject, newParentObject [, attachment [, desiredChildIndex]]) → bool [UPDATED]

    Can be used to attach the 'sandboxObject' to 'newParentObject'. If the specified parent is nil then the object will be detached from everything. Returns true if successful, otherwise false. The optional 'attachment' parameter will determine the bone on which to attach this object to if the 'newParentObject' is a character, default is "None". The second optional parameter 'desiredChildIndex' will try to put the 'sandboxObject' at the desired position below the 'newParentObject', meaning 0 would put it as the first child and any higher number will put it further down the list. Default is -1, which defaults to the end of the children list.

    Example:

    player = wl_get_player_object()
ring = wl_get_object("Ring")
wl_set_object_parent(ring, player)

    This code gets the current player object and an object named "Ring" and then it attaches the ring to the player.




    Make

    wl_make_color (r, g, b, a) → Color

    Unlike wl_make_color_string, this function does not create a single string containing all values. Instead, it returns a table with r, g, b and a set to the given parameter values.

    Example:

    color = wl_make_color(0.5, 0.24, 0.75, 1.0)
print(color.r)
print(color.g)
print(color.b)
print(color.a)

    This code creates a color and prints the individual components. The color can be used for various operations for ease of use.


    wl_make_color_string (r, g, b, a) → ColorString wl_make_color_string (color) → ColorString

    When using the event system, some receivers require option color strings as parameters (for example, setting the color of a prototype shape). This is just a helper function to create only the color part of an event parameter. If you want the full option color string, see wl_make_option_color_string().

    Example:

    color_string = wl_make_color_string(0.5, 0.2, 1.0, 1.0)
	
-- Alternatively
color = wl_make_color(0.5, 0.2, 1.0, 1.0)
color_string = wl_make_color_string(color)

    This function would return a string into 'color_string' that looks as follows: "r=0.5,g=0.2,b=1.0,a=1.0".


    wl_make_option_color_string (optionName, r, g, b, a) → OptionColorString wl_make_option_color_string (optionName, color) → OptionColorString

    When using the event system, some receivers require option color strings as parameters (for example, setting the color on a prototype shape). This is just a helper function to create these option color strings.

    Example:

    option_color_string = wl_make_option_color_string("color", 0.5, 0.2, 1.0, 1.0)
	
-- Alternatively
color = wl_make_color(0.5, 0.2, 1.0, 1.0)
color_string = wl_make_option_color_string("color", color)

    This function would return a string into 'option_color_string' that looks as follows: "color;r=0.5,g=0.2,b=1.0,a=1.0". That string could then be used in a wl_dispatch_event("SetOption", option_color_string) function call for example.


    wl_make_option_vector_string (optionName, x, y, z) → OptionVectorString wl_make_option_vector_string (optionName, vector) → OptionVectorString

    When using the event system, some receivers require option vector strings as parameters (for example, setting the start value on a Transformer prop). This is just a helper function to create these option vector strings.

    Example:

    option_vector_string = wl_make_option_vector_string("StartLocation", 3.4, 1.0, 5.7)
	
-- Alternatively
vector = wl_make_vector(3.4, 1.0, 5.7)
vector_string = wl_make_option_vector_string("StartLocation", vector)

    This function would return a string into 'option_vector_string' that looks as follows: "StartLocation;x=3.4,y=1.0,z=5.7". That string could then be used in a wl_dispatch_event("SetOption", option_vector_string) function call for example.


    wl_make_rotation_from_x (vectorX) → Vector

    This function creates a rotation from the given vector. If applied to a sandbox object, the object's forward vector (aka X, aka red arrow in local space) will be pointing in the direction of the given vector.

    Example:

    target = wl_get_object("Target")
me = wl_get_object_self()
dir = wl_vector_subtract(wl_get_object_position(target), wl_get_object_position(me))
rot = wl_make_rotation_from_x(dir)
wl_set_object_rotation(me, rot)

    This code gets an object named "Target" and rotates the executing Lua prop towards it, pointing at it with it's forward vector.


    wl_make_rotation_from_xy (vectorX, vectorY) → Vector

    This function creates a rotation from the given vectors. The resulting rotation will have it's forward vector (aka X, aka red arror in local space) point in the direction of vectorX and try to point it's right vector (aka Y, aka green arrow in local space) towards vectorY, which will not always be possible if the two vectors are not orthogonal to each other.

    Example:

    targetX = wl_get_object("TargetX")
targetY = wl_get_object("TargetY")
me = wl_get_object_self()
dirX = wl_vector_subtract(wl_get_object_position(targetX), wl_get_object_position(me))
dirY = wl_vector_subtract(wl_get_object_position(targetY), wl_get_object_position(me))
rot = wl_make_rotation_from_xy(dirX, dirY)
wl_set_object_rotation(me, rot)

    This code gets two objects named "TargetX" and "TargetY" and rotates the executing Lua prop towards the two object, pointing at TargetX with it's forward vector and trying to point at TargetY with it's right vector.


    wl_make_rotation_from_xz (vectorX, vectorZ) → Vector

    This function creates a rotation from the given vectors. The resulting rotation will have it's forward vector (aka X, aka red arror in local space) point in the direction of vectorX and try to point it's up vector (aka Z, aka blue arrow in local space) towards vectorZ, which will not always be possible if the two vectors are not orthogonal to each other.

    Example:

    targetX = wl_get_object("TargetX")
targetZ = wl_get_object("TargetZ")
me = wl_get_object_self()
dirX = wl_vector_subtract(wl_get_object_position(targetX), wl_get_object_position(me))
dirZ = wl_vector_subtract(wl_get_object_position(targetZ), wl_get_object_position(me))
rot = wl_make_rotation_from_xz(dirX, dirZ)
wl_set_object_rotation(me, rot)

    This code gets two objects named "TargetX" and "TargetZ" and rotates the executing Lua prop towards the two object, pointing at TargetX with it's forward vector and trying to point at TargetZ with it's forward vector.


    wl_make_rotation_from_y (vectorY) → Vector

    This function creates a rotation from the given vector. If applied to a sandbox object, the object's right vector (aka Y, aka green arrow in local space) will be pointing in the direction of the given vector.

    Example:

    target = wl_get_object("Target")
me = wl_get_object_self()
dir = wl_vector_subtract(wl_get_object_position(target), wl_get_object_position(me))
rot = wl_make_rotation_from_y(dir)
wl_set_object_rotation(me, rot)

    This code gets an object named "Target" and rotates the executing Lua prop towards it, pointing at it with it's right vector.


    wl_make_rotation_from_yx (vectorY, vectorX) → Vector

    This function creates a rotation from the given vectors. The resulting rotation will have it's right vector (aka Y, aka green arror in local space) point in the direction of vectorY and try to point it's forward vector (aka X, aka red arrow in local space) towards vectorX, which will not always be possible if the two vectors are not orthogonal to each other.

    Example:

    targetY = wl_get_object("TargetY")
targetX = wl_get_object("TargetX")
me = wl_get_object_self()
dirY = wl_vector_subtract(wl_get_object_position(targetY), wl_get_object_position(me))
dirX = wl_vector_subtract(wl_get_object_position(targetX), wl_get_object_position(me))
rot = wl_make_rotation_from_yx(dirY, dirX)
wl_set_object_rotation(me, rot)

    This code gets two objects named "TargetY" and "TargetX" and rotates the executing Lua prop towards the two object, pointing at TargetY with it's right vector and trying to point at TargetX with it's forward vector.


    wl_make_rotation_from_yz (vectorY, vectorZ) → Vector

    This function creates a rotation from the given vectors. The resulting rotation will have it's right vector (aka Y, aka green arror in local space) point in the direction of vectorY and try to point it's up vector (aka Z, aka blue arrow in local space) towards vectorZ, which will not always be possible if the two vectors are not orthogonal to each other.

    Example:

    targetY = wl_get_object("TargetY")
targetZ = wl_get_object("TargetZ")
me = wl_get_object_self()
dirY = wl_vector_subtract(wl_get_object_position(targetY), wl_get_object_position(me))
dirZ = wl_vector_subtract(wl_get_object_position(targetZ), wl_get_object_position(me))
rot = wl_make_rotation_from_yz(dirY, dirZ)
wl_set_object_rotation(me, rot)

    This code gets two objects named "TargetY" and "TargetZ" and rotates the executing Lua prop towards the two object, pointing at TargetY with it's right vector and trying to point at TargetZ with it's up vector.


    wl_make_rotation_from_z (vectorZ) → Vector

    This function creates a rotation from the given vector. If applied to a sandbox object, the object's up vector (aka Z, aka blue arrow in local space) will be pointing in the direction of the given vector.

    Example:

    target = wl_get_object("Target")
me = wl_get_object_self()
dir = wl_vector_subtract(wl_get_object_position(target), wl_get_object_position(me))
rot = wl_make_rotation_from_z(dir)
wl_set_object_rotation(me, rot)

    This code gets an object named "Target" and rotates the executing Lua prop towards it, pointing at it with it's up vector.


    wl_make_rotation_from_zx (vectorZ, vectorX) → Vector

    This function creates a rotation from the given vectors. The resulting rotation will have it's up vector (aka Z, aka blue arror in local space) point in the direction of vectorZ and try to point it's forward vector (aka X, aka red arrow in local space) towards vectorX, which will not always be possible if the two vectors are not orthogonal to each other.

    Example:

    targetZ = wl_get_object("TargetZ")
targetX = wl_get_object("TargetX")
me = wl_get_object_self()
dirZ = wl_vector_subtract(wl_get_object_position(targetZ), wl_get_object_position(me))
dirX = wl_vector_subtract(wl_get_object_position(targetX), wl_get_object_position(me))
rot = wl_make_rotation_from_zx(dirZ, dirX)
wl_set_object_rotation(me, rot)

    This code gets two objects named "TargetZ" and "TargetX" and rotates the executing Lua prop towards the two object, pointing at TargetZ with it's up vector and trying to point at TargetX with it's forward vector.


    wl_make_rotation_from_zy (vectorZ, vectorY) → Vector

    This function creates a rotation from the given vectors. The resulting rotation will have it's up vector (aka Z, aka blue arror in local space) point in the direction of vectorZ and try to point it's right vector (aka Y, aka green arrow in local space) towards vectorY, which will not always be possible if the two vectors are not orthogonal to each other.

    Example:

    targetZ = wl_get_object("TargetZ")
targetY = wl_get_object("TargetY")
me = wl_get_object_self()
dirZ = wl_vector_subtract(wl_get_object_position(targetZ), wl_get_object_position(me))
dirY = wl_vector_subtract(wl_get_object_position(targetY), wl_get_object_position(me))
rot = wl_make_rotation_from_zx(dirZ, dirY)
wl_set_object_rotation(me, rot)

    This code gets two objects named "TargetZ" and "TargetY" and rotates the executing Lua prop towards the two object, pointing at TargetZ with it's up vector and trying to point at TargetY with it's right vector.


    wl_make_vector (x, y, z) → Vector

    Unlike wl_make_vector_string, this function does not create a single string containing all values. Instead, it returns a table with x, y and z set to the given parameter values.

    Example:

    vector = wl_make_vector(3.4, 1.0, 5.7)
print(vector.x)
print(vector.y)
print(vector.z)

    This code creates a vector and prints the individual components. The vector can be used for various vector operations for ease of use.


    wl_make_vector_string (x, y, z) → VectorString wl_make_vector_string (vector) → VectorString

    When using the event system, some receivers require option vector strings as parameters (for example, setting the start value on a Transformer prop). This is just a helper function to create only the vector part of an event parameter. If you want the full option vector string, see wl_make_option_vector_string().

    Example:

    vector_string = wl_make_vector_string(3.4, 1.0, 5.7)
	
-- Alternatively
vector = wl_make_vector(3.4, 1.0, 5.7)
vector_string = wl_make_vector_string(vector)

    This function would return a string into 'vector_string' that looks as follows: "x=3.4,y=1.0,z=5.7".




    Misc

    wl_execute_delayed (delaySeconds, luaCodeString)

    This function can be used to execute lua code at a later point in time. As the name suggests, the 'delaySeconds' parameter defines the amount of seconds to wait until executing the code in 'luaCodeString'.

    Example:

    function print_something(text_to_print)
    print(text_to_print)
end

wl_execute_delayed(2.0, "print_something('Hello world!')")

    This code defines a function to print something into the log and then executes it with a 2 second delay.


    wl_get_delta_time () → float

    This functions return the time since the last frame, in seconds. This is useful if you want to build functionality that is not dependent on the framerate, like moving an object forwards by a constant value.

    Example:

    orb = wl_get_object("Orb")
orbPos = wl_get_object_position(orb)
orbPos.x = orbPos.x + wl_get_delta_time() * 5
wl_set_object_position(orb, orbPos.x, orbPos.y, orbPos.z)

    This function will get the first sandbox object called "Orb" and get it's current position. Then, it will add an offset to it's x coordinate using the delta time to ensure constant movement. If this function was to be called every frame, this would mean the orb would move 5 centimeters along the axis per second.


    (Experimental) wl_load_scene (sceneName, loadAdditively) → bool

    This function allows you to load another sandbox scene. The scene needs to be compatible with the current level, for example, a Showroom map could not be loaded while in the Wild Life map. Only the scene name needs to be specified (without the .json extension).
    You can specify whether the loaded scene should be loaded by itself or additively using the second function parameter.
    Returns true or false, depending on the success of the load.

    This function is experimental and could lead to a multitude of unexpected edge cases. Before running this function, make sure all necessary scenes and code are saved to prevent any data loss. It is also recommended to not load multiple scenes at the same time, both additively and not. Any code that follows this function could lead to unexpected behaviour and should be avoided.

    Example:

    -- Loads a scene by itself, overwriting anything currently in the sandbox.
wl_load_scene("My Scene", false)

-- Alternatively: Loads a scene additively to the current sandbox scene.
wl_load_scene("My Scene", true)

    This code tries to open a scene named "My Scene".


    wl_raycast (originVector, directionVector, maxDistance) → RayCastHit

    This will cast an ray from the given location 'originVector' in the direction of 'directionVector' with a max distance of 'maxDistance'. If the ray hits anything on it's path, it will add useful hit information into a the returned RayCastHit table.

    Example:

    origin = wl_make_vector(0.0, 0.0, 500.0)
direction = wl_make_vector(0.0, 0.0, -1.0)
hit = wl_raycast(origin, direction, 1000)
print(hit.did_hit)
print(hit.hit_point.x)
print(hit.hit_point.y)
print(hit.hit_point.z)
print(hit.hit_normal.x)
print(hit.hit_normal.y)
print(hit.hit_normal.z)
print(hit.time)
print(hit.distance)
print(hit.hit_sandbox_object)

    This code starts a ray 5 meters above the ground and fires downwards 10 meters. In the flat Showroom map, it will hit the floor at x=0, y=0, z=0. All the hit information will then be printed into the log. If you want more information about what the return values do or show, see RayCastHit.




    Object Data

    wl_get_object_name (sandboxObject) → string

    Returns the name of the sandbox object. This is the same name as the one you can see in the outliner.

    Example:

    player = wl_get_player_object()
name = wl_get_object_name(player)
print(name)

    This code will get the current player object and print it's name into the log.


    wl_is_object_valid (sandboxObject) → bool

    Returns whether the given object is valid. This might be necessary if you want to make sure that an object that was saved in a variable has not since been deleted.

    Example:

    cube = wl_get_object("Cube")

function print_cube_if_valid()
    if wl_is_object_valid(cube) then
        print(cube)
    end
end

print_cube_if_valid()

    This code saves a cube object into a variable and defines a function to print the ID of the cube. Since this function could be executed by anyone at a later point in time, we want to make sure that the cube object is still valid before doing something with it.


    wl_get_object_back_vector (sandboxObject) → Vector

    Returns the back direction vector of the given 'sandboxObject'.

    Example:

    player = wl_get_player_object()
vector = wl_get_object_back_vector(player)
wl_print_vector(vector)

    This code will get the player object and print it's back facing direction into the log.


    wl_get_object_down_vector (sandboxObject) → Vector

    Returns the down direction vector of the given 'sandboxObject'.

    Example:

    player = wl_get_player_object()
vector = wl_get_object_down_vector(player)
wl_print_vector(vector)

    This code will get the player object and print it's down facing direction into the log.


    wl_get_object_forward_vector (sandboxObject) → Vector

    Returns the forward direction vector of the given 'sandboxObject'.

    Example:

    player = wl_get_player_object()
vector = wl_get_object_forward_vector(player)
wl_print_vector(vector)

    This code will get the player object and print it's forward facing direction into the log.


    wl_get_object_left_vector (sandboxObject) → Vector

    Returns the left direction vector of the given 'sandboxObject'.

    Example:

    player = wl_get_player_object()
vector = wl_get_object_left_vector(player)
wl_print_vector(vector)

    This code will get the player object and print it's left facing direction into the log.


    wl_get_object_right_vector (sandboxObject) → Vector

    Returns the right direction vector of the given 'sandboxObject'.

    Example:

    player = wl_get_player_object()
vector = wl_get_object_right_vector(player)
wl_print_vector(vector)

    This code will get the player object and print it's right facing direction into the log.


    wl_get_object_up_vector (sandboxObject) → Vector

    Returns the up direction vector of the given 'sandboxObject'.

    Example:

    player = wl_get_player_object()
vector = wl_get_object_up_vector(player)
wl_print_vector(vector)

    This code will get the player object and print it's up facing direction into the log.


    wl_get_object_visibility (sandboxObject) → bool

    Returns whether the given 'sandboxObject' is currently visible or not.

    Example:

    cube = wl_get_object("Cube")
is_visible = wl_get_object_visibility(cube)
print(is_visible)

    This code will get the first object named "Cube" and print whether it's visible or not into the log.


    wl_set_object_visibility (sandboxObject, newVisibility)

    This function can be used to set the visibility of the given 'sandboxObject' to the value of 'newVisibility'

    Example:

    cube = wl_get_object("Cube")
wl_set_object_visibility(cube, true)

    This code will set the first object named "Cube" to be visible.




    Options

    wl_get_object_bool_option (sandboxObject, optionName [, index]) → bool

    Returns the bool value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
optionValue = wl_get_object_integer_option(cube, "UseTriplanarMapping")
print(optionValue)

    This code will retrieve and print the value in the "UseTriplanarMapping" option of the first sandbox object named "Cube".


    wl_get_object_color_option (sandboxObject, optionName [, index]) → Color

    Returns the color value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
optionValue = wl_get_object_integer_option(cube, "Color")
wl_print_vector(optionValue)

    This code will retrieve and print the value in the "Color" option of the first sandbox object named "Cube".


    wl_get_object_float_option (sandboxObject, optionName [, index]) → float

    Returns the float value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
optionValue = wl_get_object_float_option(cube, "Specular")
print(optionValue)

    This code will retrieve and print the value in the "Specular" option of the first sandbox object named "Cube".


    wl_get_object_integer_option (sandboxObject, optionName [, index]) → integer

    Returns the integer value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
optionValue = wl_get_object_integer_option(cube, "Material Type")
print(optionValue)

    This code will retrieve and print the value in the "Material Type" option of the first sandbox object named "Cube".


    wl_get_object_string_option (sandboxObject, optionName [, index]) → string

    Returns the string value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
optionValue = wl_get_object_integer_option(cube, "MaterialOverride")
print(optionValue)

    This code will retrieve and print the value in the "MaterialOverride" option of the first sandbox object named "Cube".


    wl_get_object_vector_option (sandboxObject, optionName [, index]) → Vector

    Returns the vector value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Transformer")
optionValue = wl_get_object_integer_option(cube, "StartLocation")
wl_print_color(optionValue)

    This code will retrieve and print the value in the "StartLocation" option of the first sandbox object named "Transformer".


    wl_set_object_bool_option (sandboxObject, optionName, optionValue [, index])

    Sets the bool value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
wl_set_object_integer_option(cube, "UseTriplanarMapping", true)

    This code will set the value in the "UseTriplanarMapping" option of the first sandbox object named "Cube" to true.


    wl_set_object_color_option (sandboxObject, optionName, optionValue [, index])

    Sets the color value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
wl_set_object_integer_option(cube, "Color", wl_make_color(0.0, 1.0, 0.0, 1.0))

    This code will set the value in the "Color" option of the first sandbox object named "Cube" to green.


    wl_set_object_float_option (sandboxObject, optionName, optionValue [, index])

    Sets the float value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
wl_set_object_float_option(cube, "Specular", 0.5)

    This code will set the value in the "Specular" option of the first sandbox object named "Cube" to 0.5.


    wl_set_object_integer_option (sandboxObject, optionName, optionValue [, index])

    Sets the integer value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
wl_set_object_integer_option(cube, "Material Type", 3)

    This code will set the value in the "Material Type" option of the first sandbox object named "Cube" to 3.


    wl_set_object_string_option (sandboxObject, optionName, optionValue [, index])

    Sets the string value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Cube")
wl_set_object_integer_option(cube, "MaterialOverride", "MyMaterial")

    This code will set the value in the "MaterialOverride" option of the first sandbox object named "Cube" to "MyMaterial".


    wl_set_object_vector_option (sandboxObject, optionName, optionValue [, index])

    Sets the vector value of the 'optionID' option of the given 'sandboxObject'. This works for props, characters, sex scenes and poses. The 'index' parameter is only necessary when dealing with sex scenes to select the animation index.
    Tip: if you click on the label of an option, it will automatically copy the option ID to the clipboard for you to paste it into your code.

    Example:

    cube = wl_get_object("Transformer")
wl_set_object_integer_option(cube, "StartLocation", wl_make_vector(1.0, 2.0, 3.0))

    This code will set the value in the "StartLocation" option of the first sandbox object named "Transformer" to x=1.0, y=2.0, z=3.0.




    Print

    wl_print_color (color)

    Prints a color to the log. This is a helper function to aid debugging or visualizing your colors.

    Example:

    col = wl_make_color(0.5, 0.24, 0.75, 1.0)
wl_print_color(col)

    The code creates a color and prints it directly into the log. The printed string will look as follows: r = 0.500000, g = 0.240000, b = 0.750000, a = 1.000000


    wl_print_table (table)

    Prints the entire 'table' to the log using json syntax. This is a helper function to aid debugging or visualizing your custom lua tables.

    Example:

    myObj = {}
myObj.position = wl_make_vector(1,2,3)
myObj.name = "Object name"
myObj.value = 512
myObj.canEatLemons = true

wl_print_table(myObj)

    This code create a table and gives it arbitrary data. Then, it prints the contents of the table into the log.


    wl_print_vector (vector)

    Prints a vector to the log. This is a helper function to aid debugging or visualizing your vectors.

    Example:

    vec = wl_make_vector(1,2,3)
wl_print_vector(vec)

    The code creates a vector and prints it directly into the log. The printed string will look as follows: x = 1.000000, y = 2.000000, z = 3.000000




    Transform

    wl_get_object_local_position (sandboxObject) → Vector

    Returns the relative position to the parent of the given 'sandboxObject' as a Vector.

    Example:

    tree = wl_get_object("Tree")
pos = wl_get_object_local_position(tree)
print(pos.x)
print(pos.y)
print(pos.z)

    This code will get the first sandbox object named "Tree" and print it's local coordinates into the log.


    wl_get_object_local_rotation (sandboxObject) → Vector

    Returns the relative rotation to the parent of the given 'sandboxObject' as a Vector.

    Example:

    fan = wl_get_object("Fan")
rot = wl_get_object_local_rotation(fan)
print(rot.x)
print(rot.y)
print(rot.z)

    This code will get the first sandbox object named "Fan" and print it's local rotation into the log.


    wl_get_object_local_scale (sandboxObject) → Vector

    Returns the relative scale to the parent of the given 'sandboxObject' as a Vector.

    Example:

    ball = wl_get_object("Ball")
scale = wl_get_object_local_scale(ball)
print(scale.x)
print(scale.y)
print(scale.z)

    This code will get the first sandbox object named "Ball" and print it's local scale into the log.


    wl_get_object_position (sandboxObject) → Vector

    Returns the world position of the given 'sandboxObject' as a Vector.

    Example:

    tree = wl_get_object("Tree")
pos = wl_get_object_position(tree)
print(pos.x)
print(pos.y)
print(pos.z)

    This code will get the first sandbox object named "Tree" and print it's world coordinates into the log.


    wl_get_object_rotation (sandboxObject) → Vector

    Returns the world rotation of the given 'sandboxObject' as a Vector.

    Example:

    fan = wl_get_object("Fan")
rot = wl_get_object_rotation(fan)
print(rot.x)
print(rot.y)
print(rot.z)

    This code will get the first sandbox object named "Fan" and print it's world rotation into the log.


    wl_get_object_scale (sandboxObject) → Vector

    Returns the world scale of the given 'sandboxObject' as a Vector.

    Example:

    ball = wl_get_object("Ball")
scale = wl_get_object_scale(ball)
print(scale.x)
print(scale.y)
print(scale.z)

    This code will get the first sandbox object named "Ball" and print it's world scale into the log.


    wl_set_object_local_position (sandboxObject, x, y, z)wl_set_object_local_position (sandboxObject, vector)

    This function can be used to set the position relative to the parent of a sandbox object directly.

    Example:

    sphere = wl_get_object("Sphere")
wl_set_object_local_position(sphere, 0, 0, 0)

-- Alternatively
sphere = wl_get_object("Sphere")
vec = wl_make_vector(0, 0, 0)
wl_set_object_local_position(sphere, vec)

    This code will teleport the first sandbox object named "Sphere" to the local coordinates x=0, y=0, z=0. Since the coordinates are relative to the parent, this effectively sets the position of this object to the same position as the parent. Alternatively, you can also provide a vector instead of x, y and z separately.


    wl_set_object_local_rotation (sandboxObject, x, y, z)wl_set_object_local_rotation (sandboxObject, vector)

    This function can be used to set the rotation relative to the parent of a sandbox object directly.

    Example:

    windmill = wl_get_object("Windmill")
wl_set_object_local_rotation(windmill, 0, 0, 180)

-- Alternatively
windmill = wl_get_object("Windmill")
vec = wl_make_vector(0, 0, 180)
wl_set_object_local_rotation(windmill, vec)

    This code will set the local rotation of the first sandbox object named "Windmill" to x=0, y=0, z=180, meaning it will have the same rotation as it's parent, but rotated 180 degrees around whatever the parent considers "up". Alternatively, you can also provide a vector instead of x, y and z separately.


    wl_set_object_local_scale (sandboxObject, x, y, z)wl_set_object_local_scale (sandboxObject, vector)

    This function can be used to set the scale relative to the parent of a sandbox object directly.

    Example:

    balloon = wl_get_object("Balloon")
wl_set_object_local_scale(balloon, 2, 2, 2)

-- Alternatively
balloon = wl_get_object("Balloon")
vec = wl_make_vector(2, 2, 2)
wl_set_object_local_scale(balloon, vec)

    This code will set the local scale of the first sandbox object named "Balloon" to x=2, y=2, z=2. Alternatively, you can also provide a vector instead of x, y and z separately.


    wl_set_object_position (sandboxObject, x, y, z)wl_set_object_position (sandboxObject, vector)

    This function can be used to set the world position of a sandbox object directly.

    Example:

    sphere = wl_get_object("Sphere")
wl_set_object_position(sphere, 0, 1000, 0)

-- Alternatively
sphere = wl_get_object("Sphere")
vec = wl_make_vector(0, 1000, 0)
wl_set_object_position(sphere, vec)

    This code will teleport the first sandbox object named "Sphere" to the world coordinates x=0, y=1000, z=0. The units are in centimeters. Alternatively, you can also provide a vector instead of x, y and z separately.


    wl_set_object_rotation (sandboxObject, x, y, z)wl_set_object_rotation (sandboxObject, vector)

    This function can be used to set the world rotation of a sandbox object directly.

    Example:

    windmill = wl_get_object("Windmill")
wl_set_object_rotation(windmill, 0, 0, 180)

-- Alternatively
windmill = wl_get_object("Windmill")
vec = wl_make_vector(0, 0, 180)
wl_set_object_rotation(windmill, vec)

    This code will set the world rotation of the first sandbox object named "Windmill" to x=0, y=0, z=180. The units are in degrees. Alternatively, you can also provide a vector instead of x, y and z separately.


    wl_set_object_scale (sandboxObject, x, y, z)wl_set_object_scale (sandboxObject, vector)

    This function can be used to set the world scale of a sandbox object directly.

    Example:

    balloon = wl_get_object("Balloon")
wl_set_object_scale(balloon, 2, 2, 2)

-- Alternatively
balloon = wl_get_object("Balloon")
vec = wl_make_vector(2, 2, 2)
wl_set_object_scale(balloon, vec)

    This code will set the world scale of the first sandbox object named "Balloon" to x=2, y=2, z=2. The units are scale units, meaning x=1, y=1, z=1 is "normal" scale. Thus, this code doubles the balloon's size. Alternatively, you can also provide a vector instead of x, y and z separately.




    Vector

    wl_vector_add (vectorA, vectorB) → Vector wl_vector_add (vectorA, numB) → Vector

    Adds 'vectorA' and 'vectorB' together component wise, or alternatively adds 'vectorA' and 'numB' together, meaning 'numB' is added to all x, y and z components of the vector.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(4,5,6)
vec3 = wl_vector_add(vec1, vec2)
vec4 = wl_vector_add(vec1, 5)
wl_print_vector(vec3)
wl_print_vector(vec4)

    This code creates two vectors, adds them together and prints the result into the log. It also adds a fixed value '5' to the first vector and prints that result into the log too.


    wl_vector_cross (vectorA, vectorB) → Vector

    Calculates the cross product between 'vectorA' and 'vectorB', meaning it finds a vector that is perpendicular to both 'vectorA' and 'vectorB'.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(4,5,6)
vec3 = wl_vector_cross(vec1, vec2)
wl_print_vector(vec3)

    This code creates two vectors, calculates the cross product and prints the resulting vector into the log.


    wl_vector_divide (vectorA, vectorB) → Vector wl_vector_divide (vectorA, numB) → Vector

    Divides 'vectorB' from 'vectorA' component wise, or alternatively divides 'numB' from 'vectorA', meaning 'numB' is divided from all x, y and z components of the vector.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(4,5,6)
vec3 = wl_vector_divide(vec1, vec2)
vec4 = wl_vector_divide(vec1, 5)
wl_print_vector(vec3)
wl_print_vector(vec4)

    This code creates two vectors, divides them and prints the result into the log. It also divides a fixed value '5' from the first vector and prints that result into the log too.


    wl_vector_dot (vectorA, vectorB) → float

    Calculates the dot product between 'vectorA' and 'vectorB', meaning all x, y, z components are multiplied component wise and the resulting components are summed together.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(4,5,6)
dot = wl_vector_dot(vec1, vec2)
print(dot)

    This code creates two vectors, calculates the dot product between them and prints the result into the log.


    wl_vector_length (vector) → float

    Returns the length of the vector in centimeters.

    Example:

    vec1 = wl_make_vector(1,2,3)
length = wl_vector_length(vec1)
print(length)

    This code creates a vector, calculates the length and prints the result into the log.


    wl_vector_multiply (vectorA, vectorB) → Vector wl_vector_multiply (vectorA, numB) → Vector

    Multiplies 'vectorA' and 'vectorB' together component wise, or alternatively multiplies 'vectorA' and 'numB' together, meaning each x, y and z component is multiplied with 'numB'.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(4,5,6)
vec3 = wl_vector_multiply(vec1, vec2)
vec4 = wl_vector_multiply(vec1, 5)
wl_print_vector(vec3)
wl_print_vector(vec4)

    This code creates two vectors, multiplies them together and prints the result into the log. It also multiplies a fixed value '5' to the first vector and prints that result into the log too.


    wl_vector_normalize (vector) → Vector

    Normalizes the given vector 'vector', meaning the direction will remain the same, but the length of the vector will be exaclty 1 centimeter

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_vector_normalize(vec1)
wl_print_vector(vec2)

    This code creates a vector, normalizes it and prints the resulting vector into the log.


    wl_vector_plane_project (vectorA, vectorB) → Vector

    Projects 'vectorA' onto a plane with normal 'vectorB' and returns the projected vector.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(0,0,1)
vec3 = wl_vector_plane_project(vec1, vec2)
wl_print_vector(vec3)

    This code creates a vector and projects it onto a surface with an 'up' normal vector. In this case that means only the x and y components of the resulting vector have a value.


    wl_vector_project (vectorA, vectorB) → Vector

    Projects 'vectorA' onto 'vectorB' and returns the projected vector.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(0,0,1)
vec3 = wl_vector_project(vec1, vec2)
wl_print_vector(vec3)

    This code creates a vector and projects it onto an 'up' vector. In this case that means only the z component of the resulting vector has a value.


    wl_vector_reflect (vectorA, vectorB) → Vector

    Calculates the reflected vector of 'vectorA' bouncing off a surface with normal vector 'vectorB'.

    Example:

    vec1 = wl_make_vector(-1,-1,-1)
vec2 = wl_make_vector(0,0,1)
vec3 = wl_vector_reflect(vec1, vec2)
wl_print_vector(vec3)

    This code creates a vector that is reflected off a surface that faces upwards. The resulting reflected vector is printed into the log.


    wl_vector_subtract (vectorA, vectorB) → Vector

    Subtracts 'vectorB' from 'vectorA' component wise, or alternatively subtracts 'numB' from 'vectorA', meaning 'numB' is subtracted from all x, y and z components of the vector.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(4,5,6)
vec3 = wl_vector_subtract(vec1, vec2)
vec4 = wl_vector_subtract(vec1, 5)
wl_print_vector(vec3)
wl_print_vector(vec4)

    This code creates two vectors, subtracts them and prints the result into the log. It also subtracts a fixed value '5' from the first vector and prints that result into the log too.