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
RayCastHit.hit_sphere_point    - The final center position of the sphere (Shapecasts only)
RayCastHit.hit_sphere_point.x  - The X component of the final center position of the sphere (Shapecasts only)
RayCastHit.hit_sphere_point.y  - The Y component of the final center position of the sphere (Shapecasts only)
RayCastHit.hit_sphere_point.z  - The Z component of the final center position of the sphere (Shapecasts only)
RayCastHit.hit_sphere_normal   - A normalized direction vector pointing from 'hit_point' to 'hit_sphere_point' (Shapecasts only)
RayCastHit.hit_sphere_normal.x - The X component of the 'hit_sphere_point' vector (Shapecasts only)
RayCastHit.hit_sphere_normal.y - The Y component of the 'hit_sphere_point' vector (Shapecasts only)
RayCastHit.hit_sphere_normal.z - The Z component of the 'hit_sphere_point' vector (Shapecasts only)
RayCastHit.penetration_depth   - If a shapecast ends up inside an object, this value will determine the depth within the object (Shapecasts only)

A RayCastHit is returned when using the wl_raycast, wl_spherecast, wl_boxcast, wl_capsulecast functions. 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.


BoneControl 

BoneControl.control_object       - A reference to a sandbox object controlling the bone. Can be nil
BoneControl.alpha                - The amount to control the bone by. 0 = keep original transform, 1 = use only offset transform
BoneControl.position_offset      - The vector to offset the bone's position by
BoneControl.position_offset.x    - The X component of the position offset
BoneControl.position_offset.y    - The Y component of the position offset
BoneControl.position_offset.z    - The Z component of the position offset
BoneControl.rotation_offset      - The vector to offset the bone's rotation by
BoneControl.rotation_offset.x    - The X component of the rotation offset
BoneControl.rotation_offset.y    - The Y component of the rotation offset
BoneControl.rotation_offset.z    - The Z component of the rotation offset
BoneControl.scale_offset         - The vector to offset the bone's scale by
BoneControl.scale_offset.x       - The X component of the scale offset
BoneControl.scale_offset.y       - The Y component of the scale offset
BoneControl.scale_offset.z       - The Z component of the scale offset
BoneControl.control_child_bones  - Whether child bones should also be offset

A BoneControl is returned when using the wl_character_create_bone_control, wl_character_get_bone_control or wl_character_get_all_bone_controls functions. It contains all relevant information on how to modify a bone on a character.


Material 

Material.type                      - The type of the material (Opaque, Transparent, Masked, Decal)
Material.color_texture_path        - The path to the external diffuse texture
Material.normal_texture_path       - The path to the external normal texture
Material.metallic_texture_path     - The path to the external metallic texture
Material.roughness_texture_pat h   - The path to the external roughness texture
Material.emission_texture_path     - The path to the external emission texture
Material.color_multiplier          - The color multiplier for the material
Material.metallic                  - The metallic value
Material.specular                  - The specular value
Material.roughness                 - The roughness value
Material.normal_strength           - The multiplier for the normal strength
Material.emissive_color_multiplier - The emission color multiplier for the material
Material.masked_alpha_cutoff       - The alpha cutoff value for masked materials
Material.texture_tiling            - A vector for the texture tiling on every axis
Material.texture_offset            - A vector for the texture offset on every axis
Material.triplanar                 - Whether triplanar mapping is enabled or not
Material.two_sided                 - Whether two sided mode is enabled or not
Material.invert_green_channel      - Whether to invert the green channel for the normal map
Material.surface_type              - The surface type of the material (For example, for footstep/impact sounds)
Material.texture_movement          - A vector for the texture movement on every axis
Material.refraction                - The refraction value

A Material is returned when using the wl_material_create or wl_material_get functions. It contains all relevant information on how to modify a material.


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

Animation

wl_animation_guid_tracks_get (animationObject) → SandboxObject array

This function will return an array of all guids that have a track in the given 'animationObject'.

Example:

local animation = wl_get_object("Animation Sequence")
local guids = wl_animation_guid_tracks_get(animation)
wl_print_table(guids)

This code will print all guids that have a track in the animation prop into the log.


wl_animation_object_track_add (animationObject, guid) → bool

This code will add an object track to the given 'animationObject' prop. The 'guid' is the object guid of the desired object to add, or wl_animation_get_event_track_guid if you want to add the event track.
For more control over the object track, use wl_animation_object_track_add_advanced instead.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
wl_animation_object_track_add(animation, selfGuid)

This code will add the executing Lua prop as an object track into the animation prop.


wl_animation_object_track_add_advanced (animationObject, objectTrackData) → bool

This code will add an object track to the given 'animationObject' prop. The 'objectTrackData' is the object track data you want to add - you can create this data using the wl_animation_object_track_create function.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
local objectTrack = wl_animation_object_track_create(selfGuid, "My Group/Sub Group")
wl_animation_object_track_add_advanced(animation, objectTrack)

This code will add the executing Lua prop as an object track into the animation prop.


wl_animation_object_track_create (guid, groupName) → Table

This function will create a table that can be used as the 'objectTrackData' in the wl_animation_object_track_add_advanced function.
The given 'guid' is the guid of the object you want to create a track for, while the 'groupName' specifies the group it should be added to within the animation prop. You can add slashes to put it into a subgroup, for example "Maya/Arms/Hands".

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
local objectTrack = wl_animation_object_track_create(selfGuid, "My Group/Sub Group")
wl_animation_object_track_add_advanced(animation, objectTrack)

This code will add the executing Lua prop as an object track into the animation prop.


wl_animation_object_track_get (animationObject, guid) → Table

This function will return a table with the data of the 'guid' object track.

The entries in this table will be:
"guid"
"group_name"
"sub_tracks"

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object_self())
local objectTrackData = wl_animation_object_track_get(animation, guid)
wl_print_table(objectTrackData)

This code will print the data of this Lua prop's object track in the animation prop to the log.


wl_animation_object_track_remove (animationObject, guid) → bool

This function will remove an object track with the given 'guid' on the 'animationObject'. Any owned keyframe tracks and keyframes will also be cleared.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
wl_animation_object_track_add(animation, selfGuid)
wl_animation_object_track_remove(animation, selfGuid)

Pretty useless, but this code will add and immediately remove an object track from an animation sequence prop.


wl_animation_keyframe_track_add (animationObject, guid, identifier, type) → bool

This code will add a keyframe track to the given 'animationObject' prop. The 'guid' is the object guid of the desired object to add to, and the 'identifier' is the option you want to animate with this keyframe track (OptionID). For position, rotation and scale the identifier is not strictly needed, but it is best to use "Position", "Rotation" and "Scale" respecively to avoid potential problems.

The given 'type' defines what kind of track it should be. Available types are:
"Position"
"Rotation"
"Scale"
"Float"
"Int"
"Bool"
"String"
"Vector"
"Color"
"Notify"

For more control over the keyframe track, use wl_animation_keyframe_track_add_advanced instead.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
wl_animation_keyframe_track_add(animation, selfGuid, "Position", "Position")

This code will add a position keyframe track for the Lua prop into the animation. This assumes that an object track already exists.


wl_animation_keyframe_track_add_advanced (animationObject, guid, identifier, keyframeTrackData) → bool

This code will add a keyframe track to the given 'animationObject' prop. The 'guid' is the object guid of the desired object to add to, and the 'identifier' is the option you want to animate with this keyframe track (OptionID). For position, rotation and scale the identifier is not strictly needed, but it is best to use "Position", "Rotation" and "Scale" respecively to avoid potential problems.
The 'keyframeTrackData' is the keyframe track data you want to add - you can create this data using the wl_animation_keyframe_track_create function.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
local keyframeTrack = wl_animation_keyframe_track_create("Position", "Default")
wl_animation_keyframe_track_add_advanced(animation, selfGuid, keyframeTrack)

This code will add a position keyframe track for the Lua prop into the animation. This assumes that an object track already exists.


wl_animation_keyframe_track_create (type, tag) → Table

This function will create a table that can be used as the 'keyframeTrackData' in the wl_animation_keyframe_track_add_advanced function.

The given 'type' defines what kind of track it should be. Available types are:
"Position"
"Rotation"
"Scale"
"Float"
"Int"
"Bool"
"String"
"Vector"
"Color"
"Notify"

The 'tag' specifies what exactly should be affected, Available tags are:
"Default"
"BoneController"

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
local keyframeTrack = wl_animation_keyframe_track_create("Position", "Default")
wl_animation_keyframe_track_add_advanced(animation, selfGuid, keyframeTrack)

This code will add a position keyframe track for the Lua prop into the animation. This assumes that an object track already exists.


wl_animation_keyframe_track_get (animationObject, guid, identifier) → Table

This function will return a table with the data of the 'guid' -> 'identifier' keyframe track.

The entries in this table will be:
"type"
"tag"
"num_tracks"

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object_self())
local keyframeTrackData = wl_animation_keyframe_track_get(animation, guid, "Position")
wl_print_table(keyframeTrackData)

This code will print the data of this Lua prop's position keyframe track data in the animation prop to the log.


wl_animation_keyframe_track_remove (animationObject, guid, identifier) → bool

This function will remove the keyframe track for the given 'guid' and 'identifier' on the 'animationObject'. Any owned keyframes will also be cleared.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local selfGuid = wl_get_object_guid(wl_get_object_self())
wl_animation_keyframe_track_add(animation, selfGuid, "Position", "Position")
wl_animation_keyframe_track_remove(animation, selfGuid, "Position")

Pretty useless, but this code will add and immediately remove a keyframe track from an animation sequence prop.This assumes that an object track already exists.


wl_animation_keyframe_add (animationObject, guid, identifier, time, value [, groupIndex]) → bool

This function will add a keyframe to the 'animationObject'. The object's 'guid', the 'identifier' and 'time' need to be specified for the keyframe to know what track to be added to.
The 'value' parameter can be a float, integer, bool, string, color, vector or notify (which is also just two strings separated with a semicolon e.g. "eventName;eventParameter").
The 'groupIndex' specifies what subtrack the keyframe should be added to (for example, whether to add to the red, green, blue or alpha of a color track, starting at 0 for red/x). If the 'value' already is a color/vector, the 'groupIndex' is not needed and a keyframe will be added to all subtracks.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Cube"))
wl_animation_keyframe_add(animation, guid, "Color", 0.5, 0.25, 1)

This code will add a keyframe to the color track of a cube, but only to the green channel with the value of 0.25 at time 0.5. This assumes that an object track and a keyframe track already exist.


wl_animation_keyframe_add_advanced (animationObject, guid, identifier, time, keyframeData [, groupIndex]) → bool

This function will add a keyframe to the 'animationObject'. The object's 'guid', the 'identifier' and 'time' need to be specified for the keyframe to know what track to be added to.
The 'keyframeData' can be created using the wl_animation_keyframe_create function.
The 'groupIndex' specifies what subtrack the keyframe should be added to (for example, whether to add to the red, green, blue or alpha of a color track, starting at 0 for red/x). If the 'value' already is a color/vector, the 'groupIndex' is not needed and a keyframe will be added to all subtracks.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Button"))
local keyframe = wl_animation_keyframe_create(5.0, 0.0, 0.0, "Smooth", "Free", "Free")
wl_animation_keyframe_add_advanced(animation, guid, "buttonDownDuration", 0.5, keyframe)

This code will add a float keyframe for a button prop into the animation. This assumes that an object track and a keyframe track already exist.


wl_animation_keyframe_create (value [, inTangent, outTangent, tangentMode, inTangentType, outTangentType]) → Table

This function will create a table that can be used as the 'keyframeData' in the wl_animation_keyframe_add_advanced function.
The 'value' parameter can be a float, integer, bool, string, color, vector or notify (which is also just two strings separated with a semicolon e.g. "eventName;eventParameter").
The 'inTangent' and 'outTangent' define the incoming and outgoing tangents, where 0 means flat.

The 'tangentMode' parameter defines how the tangent should be handled, default is "Smooth". Available candidates are:
"Auto"
"Smooth"
"Broken"

The 'inTangentType' and 'outTangentType' parameters define the interpolation, default is "Free". Available candidates are:
"Free"
"Linear"
"Constant"

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Button"))
local keyframe = wl_animation_keyframe_create(5.0, 0.0, 0.0, "Smooth", "Free", "Free")
wl_animation_keyframe_add_advanced(animation, guid, "buttonDownDuration", 0.5, keyframe)

This code will add a float keyframe for a button prop into the animation. This assumes that an object track and a keyframe track already exist.


wl_animation_keyframe_get (animationObject, guid, identifier, time, groupIndex) → Table

This function will return the data of a keyframe at the given 'time'. The object's 'guid', and 'identifier' need to be specified to narrow down what track to check on. The 'groupIndex' specifies the subtrack (red/green/blue/alpha or x/y/z as an index starting from 0).

The resulting table will contain the following data:
"value"
"in_tangent"
"out_tangent"
"tangent_mode"
"in_tangent_type"
"out_tangent_type"
"time"

If no keyframe was found at the specified time, nil will be returned instead.

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Cube"))
local keyframeData = wl_animation_keyframe_get(animation, guid, "Color", 0.5, 1)
wl_print_table(keyframeData)

This code will print the data of a keyframe into the log. This assumes that the animation has a "Cube" object track, a "Color" keyframe track and a keyframe on the green channel at second 0.5.


wl_animation_keyframe_get_index (animationObject, guid, identifier, index, groupIndex) → Table

This function will return the data of a keyframe with the given 'index' on it's track. The object's 'guid', and 'identifier' need to be specified to narrow down what track to check on. The 'groupIndex' specifies the subtrack (red/green/blue/alpha or x/y/z as an index starting from 0).

The resulting table will contain the following data:
"value"
"in_tangent"
"out_tangent"
"tangent_mode"
"in_tangent_type"
"out_tangent_type"
"time"

If no keyframe was found at the specified time, nil will be returned instead.

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Cube"))
local keyframeData = wl_animation_keyframe_get_index(animation, guid, "Color", 0.5, 2)
wl_print_table(keyframeData)

This code will print the data of a keyframe into the log. This assumes that the animation has a "Cube" object track, a "Color" keyframe track and at least 3 keyframes on the green channel.


wl_animation_keyframe_remove (animationObject, guid, identifier, time, groupIndex) → bool

This function will attempt to remove a keyframe at the given 'time'. The object's 'guid', the 'identifier' and 'time' need to be specified for the keyframe to know what track to be removed from. The 'groupIndex' specifies the subtrack (red/green/blue/alpha or x/y/z as an index starting from 0).
Returns true if a keyframe was removed, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Cube"))
wl_animation_keyframe_remove(animation, guid, "Color", 0.5, 1)

This code will attempt to remove a keyframe in the green channel of the Cube's "Color" track at time 0.5.


wl_animation_keyframe_remove_index (animationObject, guid, identifier, index, groupIndex) → bool

This function will attempt to remove a keyframe with the given 'index' in it's track (starting at 0 for the first keyframe). The object's 'guid', and 'identifier' need to be specified for the keyframe to know what track to be removed from. The 'groupIndex' specifies the subtrack (red/green/blue/alpha or x/y/z as an index starting from 0).
Returns true if a keyframe was removed, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Cube"))
wl_animation_keyframe_remove_index(animation, guid, "Color", 2, 1)

This code will attempt to remove the third keyframe in the green channel of the Cube's "Color" track.


wl_animation_keyframe_track_get_keyframes (animationObject, guid, identifier, groupIndex) → Table

This function will return an array of all keyframes in the 'guid' -> 'identifier' -> 'groupIndex' keyframe track.

Every keyframe entry in this table will have the following data:
"value"
"in_tangent"
"out_tangent"
"tangent_mode"
"in_tangent_type"
"out_tangent_type"
"time"

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object_self())
local keyframeTrackData = wl_animation_keyframe_track_get_keyframes(animation, guid, "Position", 1)
wl_print_table(keyframeTrackData)

This code will print all keyframes of the Lua prop's position Y track into the log.


wl_animation_get_current_time (animationObject) → float

This function returns the current time in the animation prop.
Returns -1 if unsuccessful.

Example:

local animation = wl_get_object("Animation Sequence")
local currentTime = wl_animation_get_current_time(animation)
print(currentTime)

This code will print the current playback time of the animation prop into the log.


wl_animation_get_event_track_guid () → string

This function will return the guid of the event track. The event track works the same as an object track, except that the guid is always the same and it doesn't point towards an object.

Example:

print(wl_animation_get_event_track_guid())

This code will print the event track guid into the log.


wl_animation_go_to_time (animationObject, time [, updateAnimation [, triggerNotifies]]) → bool [NEW]

Calling this function will move the play cursor to the specified 'time'.
By default, the objects in the animation will update and all event notifies between the old and the new position will be triggered, but this can be disabled with the optional 'updateAnimation' and 'triggerNotifies' parameters respectively.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
wl_animation_go_to_time(animation, 2, true, false)

This code will go to second 2 in the animation and all objects will update accordingly. Notifies will not be triggered though.


wl_animation_group_remove (animationObject, groupName [, removeChildren]) → bool

This function will remove a group with the given 'groupName' from an animation. By default, all tracks currently in that group will not be deleted and will just move out of the group. If you do want to delete all sub-tracks, set the optional 'removeChildren' parameter to true.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
wl_animation_group_remove(animation, "Shapes")

This code will remove a group named "Shapes" from the animation.


wl_animation_group_rename (animationObject, oldGroupName, newGroupName) → bool

This function will rename a group in the given 'animationObject' from 'oldGroupName' to 'newGroupName'.
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
wl_animation_group_rename(animation, "Shapes", "Boxes")

This code will rename a group named "Shapes" into "Boxes".


wl_animation_set_auto_keying_enabled (animationObject, isEnabled) → bool

This function turns on or off auto-keying of the given 'animationObject' based on the specified 'isEnabled' parameter.

Example:

local animation = wl_get_object("Animation Sequence")
wl_animation_set_auto_keying_enabled(animation, true)

This code will turn on auto-keying on the animation prop.


wl_animation_set_object_track_group (animationObject, guid, groupName) → bool

This function will put the given object track into the specified 'groupName'. For subgroups you can use slashes, for example "Maya/Arms/Hand".
Returns true if successful, otherwise false.

Example:

local animation = wl_get_object("Animation Sequence")
local guid = wl_get_object_guid(wl_get_object("Cube"))
wl_animation_set_object_track_group(animation, guid, "Shapes")

This code will put the cube object track into a group named "Shapes".




Character

wl_character_add_bone_control (characterObject, boneName, boneControl) → bool

This function adds a bone control to the given 'characterObject'. The 'boneName' specifies which bone should be modified by the 'boneControl'. You can create a bone control by using the wl_character_create_bone_control function. Calling this function multiple times will overwrite the previous bone control, as there can only be a maximum of one bone control per bone at any time. Returns true if successful, otherwise false.

Example:

player = wl_get_player_object()
positionOffset = wl_make_vector(50, 0, 0)
boneControl = wl_character_create_bone_control(nil, 1.0, positionOffset)
wl_character_add_bone_control(player, "Head", boneControl)

This code will add a position offset on to the head bone of the player character, moving it up by 50 local units.


wl_character_create_bone_control ([controlObject, alpha, positionOffset, rotationOffset, scaleOffset, controlChildBones]) → BoneControl

This is a helper function to create a BoneControl table which can be used as a parameter in the wl_character_add_bone_control function.

All parameters are optional and default to:
controlObject: nil
alpha: 1.0
positionOffset: a vector with 0 on all axes
rotationOffset: a vector with 0 on all axes
scaleOffset: a vector with 1 on all axes
controlChildBones: true

Example:

positionOffset = wl_make_vector(0, 0, 100)
rotationOffset = wl_make_vector(0, 180, 0)
scaleOffset = wl_make_vector(1,1,1)
boneControl = wl_character_create_bone_control(nil, 1.0, positionOffset, rotationOffset, scaleOffset, true)
wl_print_table(boneControl)

This code will create a bone control with arbitrary data and print it to the log


wl_character_get_all_bone_controls (characterObject) → BoneControl array

This function will return all current bone controls on the given 'characterObject'. If the character is invalid, this function will return nil.

Example:

player = wl_get_player_object()
boneControls = wl_character_get_all_bone_controls(player)
wl_print_table(boneControls)

This code will get all bone controls on the player object and print them to the log.


wl_character_get_bone_control (characterObject, boneName) → BoneControl

This function will return an existing bone control table from the given 'characterObject' and 'boneName'. If the character is invalid or the specified bone does not have a bone control, this function will return nil.

Example:

player = wl_get_player_object()
boneControl = wl_character_get_bone_control(player, "Head")
wl_print_table(boneControl)

This code will get the head bone control on the player object and print it to the log.


wl_character_get_character_name (characterObject) → string

This function returns the internal character name of the given 'characterObject'.

Example:

player = wl_get_player_object()
characterName = wl_character_get_character_name(player)
print(characterName)

This code will print the name of the current player character into the log.


wl_character_get_controller (characterObject) → SandboxObject

This function returns the current controller of the given 'characterObject'. This could either be a pose, a sex scene or nil.

Example:

maya = wl_get_object("Maya")
controller = wl_character_get_controller(maya)
print(controller)

This code will get the character named "Maya" and print its controller to the log.


wl_character_get_num_outfits (sandboxCharacter) → integer

This function will return the amount of outfits the specified 'sandboxCharacter' has.

Example:

player = wl_get_player_object()
numOutfits = wl_character_get_num_outfits(player)
print(numOutfits)

This code will print the amount of outfits the current player character has into the log.


wl_character_get_presets_for_character (characterName) → string array

This function will return the names of all existing character presets for the given 'characterName'.

Example:

presetNames = wl_character_get_presets_for_character("Maya")
wl_print_table(presetNames)

This code will print all preset names for character "Maya" into the log.


wl_character_get_presets_for_skeleton (skeletonName) → string array

This function will return the names of all existing character presets for the given 'skeletonName'. This means that using a 'skeletonName' of "Maya" will also return all presets for characters that share the Maya skeleton, like Serenia, Alissa etc.
If you want to get presets that are only for Maya, use wl_character_get_presets_for_character instead.

Example:

presetNames = wl_character_get_presets_for_skeleton("Maya")
wl_print_table(presetNames)

This code will print all preset names for skeleton "Maya" into the log.


wl_character_get_skeleton_name (characterObject) → string

This function returns the internal character skeleton name of the given 'characterObject'.

Example:

player = wl_get_player_object()
skeletonName = wl_character_get_skeleton_name(player)
print(skeletonName)

This code will print the skeleton name of the current player character into the log.


wl_character_remove_bone_control (characterObject, boneName) → bool

This function removes a bone control on the given 'characterObject'. The 'boneName' specifies which bone should be removed'. Returns true if successful, otherwise false.

Example:

player = wl_get_player_object()
wl_character_remove_bone_control(player, "Head")

This code will remove a bone control for the head bone, if one exists.


wl_get_all_attachment_names () → string array

This function returns all existing attachment names for characters

Example:

attachmentNames = wl_get_all_attachment_names()
wl_print_table(attachmentNames)

This code will print all attachment names into the log


wl_get_character_names_with_skeleton (skeletonName) → string array

This function returns an array of character names that are associated with this skeleton.

Example:

characterNames = wl_get_character_names_with_skeleton("Maya")
wl_print_table(characterNames)

This code will gather an array of characters that use the "Maya" skeleton and prints them all to the log.


wl_get_skeleton_from_character_name (characterName) → string

This function returns the skeleton name of a given 'characterName'.

Example:

skeletonName = wl_get_skeleton_from_character_name("Serenia")
print(skeletonName)

This code will print the skeleton name of the character "Serenia", which in this case will be "Maya".


wl_character_get_parent_bone (characterObject, boneName) → string

This function will return the name of the parent bone of the given 'boneName' on 'characterObject'. Returns nil if no parent bone was found.

Example:

player = wl_get_player_object()
currentBone = "Head"
while currentBone ~= nil do
    print(currentBone)
    currentBone = wl_character_get_parent_bone(player, currentBone)
end

This code will start at the head bone and go up the parent hierarchy until there is no parent anymore. Every occurring bone will be printed into the log.

In the case of most human characters, it should look like this:
- Head
- NeckMid
- NeckBase
- SpineE
- SpineD
- SpineC
- SpineB
- SpineA
- Root




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_focus_object (sandboxObject) → bool

    This function will focus the editor camera on the given 'sandboxObject' similarly to how key "F" does it. Returns true if successful, otherwise false.

    Example:

    cube = wl_get_object("Cube")
wl_editor_focus_object(cube)

    This code will focus the editor camera on a sandbox object named "Cube".


    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_character (characterName [, name]) → SandboxObject

    This function will spawn a character into the world. The 'characterName' specifies the character that should be spawned, this is not the skeleton name. If spawned successful, this function will return the newly spawned character, otherwise nil.
    Optionally, if the 'name' parameter is set, the newly spawned character will have that name in the outliner.

    Example:

    serenia = wl_editor_spawn_character("Serenia", "Best girl")

    This code spawns a Serenia character into the scene and names her "Best girl"


    (Experimental) wl_editor_spawn_pose (characterName [, name]) → SandboxObject

    This function will spawn a pose into the world. The 'characterName' specifies the character that should be spawned, this is not the skeleton name. If spawned successful, this function will return the newly spawned pose, otherwise nil.
    Optionally, if the 'name' parameter is set, the newly spawned poser object will have that name in the outliner. If you want to rename the character itself, you will have to get the first child of that poser object and use wl_set_object_name.

    Example:

    serenia = wl_editor_spawn_pose("Rawn", "Woof")

    This code spawns a Rawn character poser into the scene and names the poser object "Woof".


    (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_spawn_sex_scene (charactersArray, animationsArray [, name_string]) → SandboxObject

    This function will spawn a sex scene into the world. The 'charactersArray' and 'animationsArray' tables need to contain at least one element to be accepted. If no animations for the given character pairing exist or an invalid animation name is provided, this function will fail, see the output log for more information in this case.
    Optionally, if the 'name' parameter is set, the newly spawned sex scene object will have that name in the outliner. If you want to rename the characters themselves, you will have to iterate through the children of that sex scene object and use wl_set_object_name on them.

    Example:

    characters = wl_make_name_array("Maya", "Max")
animations = wl_make_name_array("Amazone")
wl_editor_spawn_sex_scene(characters, animations, "Test")

    This function will spawn a sex scene with characters Maya and Max. The sex scene object will be called "Test".


    (Experimental) wl_editor_duplicate_object (sandboxObject) → SandboxObject

    This function will attempt to duplicate the specified 'sandboxObject' with all it's children. Returns the newly duplicated object.

    Example:

    me = wl_get_object_self()
duplicated = wl_editor_duplicate_object(me)
print(wl_get_object_name(duplicated))

    This code will duplicate the executing Lua prop and print the duplicated object's name to the log.


    (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

    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

    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_execute_object_event_dispatcher (sandboxObject, dispatcherID, eventValue)

    Directly executes the dispatcher with the given 'dispatcherID' without the need of an event name. 'eventValue' will be used as the parameter.

    Example:

    button = wl_get_object("Button")
wl_execute_object_event_dispatcher(button, "OnButtonDown", true)

    This code executes the "OnButtonDown" dispatcher on the first sandbox object named "Button" and uses "true" as the parameter.


    wl_execute_object_event_receiver (sandboxObject, receiverID, eventValue)

    Directly executes the receiver with the given 'receiverID' without the need of an event name. 'eventValue' will be used as the parameter.

    Example:

    button = wl_get_object("Button")
wl_execute_object_event_receiver(button, "SetVisibility", false)

    This code executes the "SetVisibility" receiver on the first sandbox object named "Button" and uses "false" as the parameter.


    wl_get_call_argument_as_bool () → bool

    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

    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

    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

    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

    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

    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_caller_object () → SandboxObject

    This function will return the object that triggered the "Execute" event receiver on the Lua prop (the "caller"). If called by "execute every frame", the function will return the Lua prop itself.
    This function can also be used inside a delayed call (for example, wl_execute_delayed) an will return whatever the caller was when the delayed call was made.

    Example:

    callerObject = wl_get_caller_object()
callerName = wl_get_object_name(callerObject)
print(callerName)

    This code will print the name of the prop that executes the code 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_all_objects () → SandboxObject array

    Returns an array of every object currently in the scene.
    Caution: Lua arrays are 1-indexed, meaning the first element of an array is in array[1] and not in array[0].

    Example:

    objects = wl_get_all_objects()
wl_print_table(objects)

    This code prints every object in the scene into the log (May stutter on large scenes).


    wl_get_all_root_objects () → SandboxObject array

    Returns an array of every top-level/root object currently in the scene. If you want to include children, use wl_get_all_objects.
    Caution: Lua arrays are 1-indexed, meaning the first element of an array is in array[1] and not in array[0].

    Example:

    objects = wl_get_all_root_objects()
wl_print_table(objects)

    This code prints every top-level/root object in the scene into the log (May stutter on large scenes).


    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_by_guid (guid) → SandboxObject

    Returns a sandbox object that has the given 'guid'. Returns nil if it does not exist.

    Example:

    luaProp = wl_get_object_self()
guid = wl_get_object_guid(luaProp)
obj = wl_get_object_by_guid(guid)
print(obj)

    This code will get the lua object GUID and, using the GUID, gets the object back and prints it to the log.


    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_guid (sandboxObject) → string

    Returns the underlying GUID of the 'sandboxObject'. Every object has a unique GUID, even if two objects share the same name, settings or other data. Keep in mind though, that the GUID is generated when an object gets spawned (map load, placing, prop collection etc), meaning that loading the same map multiple times will always result in a new unique GUID per object. Thus, saving and loading GUIDs over multiple sessions is not possible/recommended.

    Example:

    luaProp = wl_get_object_self()
guid = wl_get_object_guid(luaProp)
print(guid)

    This code will get the lua prop GUID and print it to 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_object_type (sandboxObject) → string

    This function will return the type of the given 'sandboxObject'.
    If the specified object is a Prop, it will return the kind of prop, for example, a Lua prop will return "Lua" or an input prop will return "Input".
    Characters will return "Character", poses will return "Pose" and sex scenes will return "SexScene".
    Otherwise nil.

    Example:

    activeSelectable = wl_editor_get_active_object()
activeType = wl_get_object_type(activeSelectable)
print(activeType)

    This function will return the type of the active object in the selection i.e. the object with the gizmo.


    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_set_character_controller (characterObject, controllerObject [, index]) → bool

    This function assigns the 'characterObject' to the specified 'controllerObject'. This way you can make the character go from an NPC, to a pose, to a sex scene.
    If 'characterObject' is nil, the 'controllerObject' will release its currently controlled character (if it has one) to become an NPC.
    If 'controllerObject' is nil, the 'characterObject' will release itself from whatever controller is currently controlling it.
    The 'index' parameter is only necessary for sex scenes.
    Returns true if successful, otherwise false.

    Example:

    character = wl_get_object("Maya")
controller = wl_get_object("Maya Pose")
wl_set_character_controller(character, controller)

    This code will assign a character called "Maya" to a pose object called "Maya Pose"


    wl_get_object_attachment (sandboxObject) → string

    Returns the current attachment of the given 'sandboxObject'. This is only really relevant, if the given 'sandboxObject' is attached to a character.

    Example:

    ring = wl_get_object("Ring")
attachment = wl_get_object_attachment(ring)
print(attachment)

    This code will get an object named "Ring" and print it's attachment name into the log.


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

    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

    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

    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

    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

    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_name_array (...) → Table

    This is a helper function to create a table array with names. You can add as many parameters as needed.
    Functionally it is the same as creating a Lua table yourself, for example:

    array = wl_make_name_array("Maya", "Max")
    and
    array = {"Maya", "Max"}

    are the same, just in function form.

    Example:

    array = wl_make_name_array("Maya", "Max")
wl_print_table(array)

    This function creates a name array with entries "Maya" and "Max" and prints the resulting table into the log.


    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_capture_screenshot (useGameResolution) → string wl_capture_screenshot (resolutionX, resolutionY) → string

    This function can be used to take a screenshot. The resulting image will be saved to %localappdata%/WildLifeC/Saved/Screenshots.
    You can call this function with a bool ('useGameResolution'), where 'true' will use the game's current resolution as the dimensions for the screenshot, whereas 'false' will use the screenshot resolution settings in the game options.
    Calling the function with two integer values will take those values as the dimensions for the screenshot. These values are internally clamped to a range of 1 to 4096.
    Keep in mind that this function can fail if either another screenshot is still being processed or if the screenshot cooldown is currently active (this can be adjusted in the game settings)
    Returns an absolute path to the new screenshot when successful, otherwise returns an empty string.

    Example:

    screenshotPath = wl_capture_screenshot(true)
print(screenshotPath)

-- Alternatively
screenshotPath = wl_capture_screenshot(100, 100)
print(screenshotPath)

    This code will take a screenshot and print the path to the newly created image into the log.


    wl_combine_rotations () → rotationA, rotationB [NEW]

    This function will accurately combine two rotation vectors using internal Quaternion maths. Keep in mind that the order of rotations is important here. Switching 'rotationA' and 'rotationB' will give a different result.

    Example:

    lua = wl_get_object_self()
rotation = wl_get_object_rotation(lua)
additionalRotation = wl_make_vector(10, 0, 0)
finalRotation = wl_combine_rotations(rotation, additionalRotation)
wl_set_object_rotation(lua, finalRotation)

    This code will rotate the executing Lua prop around the world x axis by 10 degrees


    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_execute_delayed_cancel (delayID)

    This function will cancel a wl_execute_delayed_retriggerable call with the given 'delayID'.

    Example:

    function printDelayed()
    print("Done!")
end

wl_execute_delayed_retriggerable("myDelayID", 1.0, "printDelayed()")
wl_execute_delayed_cancel("myDelayID")

    This code sets up a delayed call, which will immediately get cancelle and thus will never print "Done!" to the log.


    wl_execute_delayed_retriggerable (delayID, delaySeconds, luaCodeString)

    This function will create a delayed call similar to wl_execute_delayed, but is assigned the given 'delayID'. No two delayed calls with the same ID can exist at the same time. An existing delayed call will be overwritten when this function is called with the same ID again.

    Example:

    function printDelayed()
    print("Done!")
end

wl_execute_delayed_retriggerable("myDelayID", 1.0, "printDelayed()")

    This code will print "Done!" to the log one second after execution. If you spam the execution, nothing will be printed to the log until there was at least a one second pause.


    wl_get_camera_direction () → Vector [NEW]

    This function will return the current view direction of the viewing camera as a normalized vector.

    Example:

    cameraDirection = wl_get_camera_direction()
wl_print_vector(cameraDirection )

    This code will print the current camera view direction into the log.


    wl_get_camera_position () → Vector [NEW]

    This function will return the current position of the viewing camera.

    Example:

    cameraPosition = wl_get_camera_position()
wl_print_vector(cameraPosition)

    This code will print the current camera position into the log.


    wl_get_camera_rotation () → Vector [NEW]

    This function will return the current rotation of the viewing camera.

    Example:

    cameraRotation = wl_get_camera_rotation()
wl_print_vector(cameraRotation)

    This code will print the current camera rotation into the log.


    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.


    wl_spherecast (radius, originVector, directionVector, maxDistance) → RayCastHit [NEW]

    This will cast a sphere with the given 'radius' from the given location 'originVector' in the direction of 'directionVector' with a max distance of 'maxDistance'. If the sphere hits anything on it's path, it will add useful hit information into a the returned RayCastHit table.
    Compared with the normal wl_raycast, this function will add three additional entries into the resulting RayCastHit table: 'hit_sphere_point', 'hit_sphere_normal' and 'penetration_depth'.
    'hit_sphere_point' will contain the center position of the sphere when it touched a surface (as opposed to where exactly the surface touched in 'hit_point') and 'hit_sphere_normal' will contain a normalized direction vector that points from the 'hit_point' towards 'hit_sphere_point'. If the spherecast ends up inside an object (for example, if the cast already starts inside a wall), the 'penetration_depth' will show how far the sphere was embedded in that object.

    Example:

    origin = wl_make_vector(0.0, 0.0, 500.0)
direction = wl_make_vector(0.0, 0.0, -1.0)
hit = wl_spherecast(50, origin, direction, 1000)
print(hit.did_hit)
wl_print_vector(hit.hit_point)
wl_print_vector(hit.hit_normal)
wl_print_vector(hit.hit_sphere_point)
wl_print_vector(hit.hit_sphere_normal)
print(hit.time)
print(hit.distance)
print(hit.hit_sandbox_object)
print(hit.penetration_depth)

    This code starts a sphere 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.


    wl_world_to_screen_position (worldPositionVector) → Vector [NEW]

    This function will convert a 3D world position into a screen position. Keep in mind that if you want to use these screen coordinates in your custom UI, you need to include the wl_get_ui_scale in your calculations.

    Example:

    target = wl_get_object("Cube")
targetPos = wl_get_object_position(target)

text = wl_get_object("UI Text")
screenPos = wl_world_to_screen_position(targetPos)
screenPos = wl_vector_divide(screenPos, wl_get_ui_scale()) -- Correct the screen position to work with UI
wl_set_object_float_option(text, "XPositionOffset", screenPos.x)
wl_set_object_float_option(text, "YPositionOffset", screenPos.y)

    This code assumes you have an object in the world named "Cube" and a UI Layer prop with a direct child named "UI Text" that has the alignment set to left, top. When you enable "Execute every frame", the text element should be pinned to the position of the cube in the world. If the text lags behind, you will probably have to change the tick group of the Lua prop to "Post update".
    Note that this will only look correct if you are either in play mode or if the left panel is collapsed in edit mode.


    wl_json_string_to_table (string) → Table

    Converts a JSON string to a table.

    Example:

    vector = wl_make_vector(1, 2, 3)
json = wl_table_to_json_string(vector)
jsonVector = wl_json_string_to_table(json)
wl_print_table(jsonVector)

    This code will convert the given vector into a string representation and back, printing the resulting table into the log.


    wl_table_to_json_string (table) → string

    Converts a table to a JSON string representation.

    Example:

    vector = wl_make_vector(1, 2, 3)
json = wl_table_to_json_string(vector)
print(json)

    This code will convert the given vector into a string representation that looks as follows:
    {
        "x": 1,
        "y": 2,
        "z": 3
    }


    wl_get_mouse_position () → Vector

    Returns the mouse cursor location relative to the game window as a vector.

    Example:

    mousePos = wl_get_mouse_position()
wl_print_table(mousePos)

    This code prints the current mouse position into the log.


    wl_get_ui_scale () → float

    Returns the global UI scale value. The UI scale is a dynamic value that changes depending on the display resolution and the viewport resolution. A screen position may not match the UI position in certain cases, so incorporating this value into calculations will mitigate any position offsets caused by this mismatch.

    Example:

    text1 = wl_get_object("UI Text 1")
text2 = wl_get_object("UI Text 2")
mousePos = wl_get_mouse_position()
uiScale = wl_get_ui_scale()
correctedMousePos = wl_vector_divide(mousePos, uiScale)

-- Raw mouse position
wl_set_object_float_option(text1, "XPositionOffset", mousePos.x)
wl_set_object_float_option(text1, "YPositionOffset", mousePos.y)

-- UI corrected mouse position
wl_set_object_float_option(text2, "XPositionOffset", correctedMousePos.x)
wl_set_object_float_option(text2, "YPositionOffset", correctedMousePos.y)

    Given two UI Texts (named "UI Text 1" and "UI Text 2") exist in a UI Layer, this code will show the difference between using the mouse position directly as the offset for the text, and using a UI scale corrected mouse position for the offset. UI Text 1 will deviate from the mouse position the further it moves away from the top left corner of the screen, while UI Text 2 will remain directly on the cursor.
    (This assumes the game is not in edit mode or all the edit mode panels are collapsed)


    wl_mouse_cursor_to_world_direction () → Vector

    Takes the mouse position and creates a world space direction vector which points in the direction of that pixel.

    Example:

    direction = wl_mouse_cursor_to_world_direction()
wl_print_table(direction)

    This code will create a direction vector that points towards where the mouse cursor is.


    wl_screen_point_to_world_direction (x, y) → Vector

    Takes the given screen position ('x', 'y') and creates a world space direction vector which points in the direction of that pixel.

    Example:

    direction = wl_screen_point_to_world_direction(100, 100)
wl_print_table(direction)

    This code will create a direction vector that points towards where the pixel at x=100, y=100 is.


    wl_get_screen_width () → float

    This function returns the current game's resolution width. When using this function in combination with UI props, keep in mind that the UI has an additional scale multiplier applied to it which you need to include in your calculations, see wl_get_ui_scale.

    Example:

    width = wl_get_screen_width()
height = wl_get_screen_height()
print("Resolution: " .. width .. " x " .. height)

    This function will print the current game resolution to the log.


    wl_get_screen_height () → float

    This function returns the current game's resolution height. When using this function in combination with UI props, keep in mind that the UI has an additional scale multiplier applied to it which you need to include in your calculations, see wl_get_ui_scale.

    Example:

    width = wl_get_screen_width()
height = wl_get_screen_height()
print("Resolution: " .. width .. " x " .. height)

    This function will print the current game resolution to the log.




    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_set_object_name (sandboxObject, name) → bool

    The function changes the name of the specified 'sandboxObject'. Returns true if successful, otherwise false.

    Example:

    me = wl_get_object_self()
wl_set_object_name(me, "Gunther")

    This code will change this Lua prop's name to "Gunther"


    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 [, recursive])

    This function can be used to set the visibility of the given 'sandboxObject' to the value of 'newVisibility'.
    Setting the optional 'recursive' boolean to 'true' will also change the visibility of all child objects to the given '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.


    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.




    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_bool_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_color_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_string_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_vector_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_bool_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_color_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_string_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_vector_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.


    wl_get_object_options (sandboxObject) → Table

    Returns a table of all options which the specified 'sandboxObject' contains, including their current value. This is a read-only operation, changing the values in the table will not change the options on the object.
    The table structure looks as follows:

    table:
        "bools":
            "<bool1>": <value1>
            "<bool2>": <value2>
            ...
        "floats":
            "<float1>": <value1>
            "<float2>": <value2>
            ...
        "integers":
            "<integer1>": <value1>
            "<integer2>": <value2>
            ...
        "strings":
            "<string1>": <value1>
            "<string2>": <value2>
            ...
        "colors":
            "<color1>": <value1>
            "<color2>": <value2>
            ...
        "vectors":
            "<vector1>": <value1>
            "<vector2>": <value2>
            ...

    Example:

    cube = wl_get_object("Cube")
options = wl_get_object_options(cube)
wl_print_table(options)

    This code gets the first object named "Cube" and prints all it's options into the log


    wl_set_object_options (sandboxObject, options) → bool

    This function can bulk-apply 'options' to the given 'sandboxObject'. The table should be formatted as described in wl_get_object_options.

    Example:

    cube1 = wl_get_object("Cube 1")
cube2 = wl_get_object("Cube 2")
options = wl_get_object_options(cube)
wl_set_object_options(cube2, options)

    This code will copy all options from an object named "Cube 1" to an object named "Cube 2".




    Pose

    wl_pose_create_missing_controls (poseSandboxObject) → bool

    This function will invoke the "Create missing" function for custom poses, which creates all pose controls that are not yet set in the given 'poseSandboxObject'. If the given pose is not yet in custom pose mode, this function will also convert it to a custom pose in the process. Returns true if successful, otherwise false.

    Example:

    pose = wl_get_object("Maya Pose")
wl_pose_create_missing_controls(pose)

    This code will create all pose controls for a maya pose.


    wl_pose_get_body_pose_name (poseSandboxObject, index) → string

    This function returns the name of a given body pose index.
    Caution: While Lua indices start at 1, the internal pose data is not Lua based and starts at 0, meaning index 0 will return the first name.

    Example:

    local pose = wl_get_object("Maya Pose")

for i = 0, wl_pose_get_num_body_poses(pose) - 1 do
    print(wl_pose_get_body_pose_name(pose, i))
end

    This code will print all available body poses of the "Maya Pose" object to the log.


    wl_pose_get_control_object (poseObject, controlID) → SandboxObject

    This function will return the sandbox object which is currently controlling a custom pose with the given 'controlID'.

    Example:

    mayaPose = wl_get_object("Maya Pose")
spineAcontrol = wl_pose_get_control_object(mayaPose, "jBnd_spineA_ctrl")
print(spineAcontrol)

    This code will get the pose control object that is currently controlling the SpineA joint of the maya pose and print it to the log.


    wl_pose_get_control_objects (poseObject) → SandboxObject table

    Returns a table with all current control objects in the given 'poseObject'. The key of each table entry is the controlID, and the value is the corresponding sandboxObject.

    Example:

    mayaPose = wl_get_object("Maya Pose")
allControls = wl_pose_get_control_objects(mayaPose)
wl_print_table(allControls)

    This code prints all the current pose control IDs with their corresponding sandbox objects into the log.


    wl_pose_get_controlled_character (poseObject) → SandboxObject

    This function will return the character that the given 'poseObject' is currently controlling. Returns nil if no character is currently being controlled.

    Example:

    pose = wl_get_object("Maya Pose")
character = wl_pose_get_controlled_character(pose)
print(character)

    This code will print the character controlled by "Maya Pose" into the log.


    wl_pose_get_face_pose_name (poseSandboxObject, index) → string

    This function returns the name of a given face pose index.
    Caution: While Lua indices start at 1, the internal pose data is not Lua based and starts at 0, meaning index 0 will return the first name.

    Example:

    local pose = wl_get_object("Maya Pose")

for i = 0, wl_pose_get_num_face_poses(pose) - 1 do
    print(wl_pose_get_face_pose_name(pose, i))
end

    This code will print all available face poses of the "Maya Pose" object to the log.


    wl_pose_get_num_body_poses (poseSandboxObject) → integer

    This function will return the amount of body poses which the given 'poseSandboxObject' has. If the given 'poseSandboxObject' is nil or is not a pose object, the function will return 0.

    Example:

    local pose = wl_get_object("Maya Pose")
local numBodyPoses = wl_pose_get_num_body_poses(pose)
print("Pose has " .. numBodyPoses .. " body poses")

    This code will get the amount of body poses of a pose object named "Maya Pose" and print the number to the log.


    wl_pose_get_num_face_poses (poseSandboxObject) → integer

    This function will return the amount of face poses which the given 'poseSandboxObject' has. If the given 'poseSandboxObject' is nil or is not a pose object, the function will return 0.

    Example:

    local pose = wl_get_object("Maya Pose")
local numFacePoses = wl_pose_get_num_face_poses(pose)
print("Pose has " .. numFacePoses .. " face poses")

    This code will get the amount of face poses of a pose object named "Maya Pose" and print the number to the log.


    wl_pose_set_control_object (poseObject, controlID, controlObject) → bool

    This function will set the sandbox object which is currently controlling a custom pose with the given 'controlID'. Returns true if successful, otherwise false.

    Example:

    mayaPose = wl_get_object("Maya Pose")
wl_pose_set_control_object(mayaPose, "jBnd_spineA_ctrl", wl_get_object_self())

    This code will set this Lua prop as the control for the SpineA joint on the maya pose.


    wl_pose_set_control_objects (poseObject, controlObjectsTable) → bool

    This function can bulk apply many custom control objects to the given 'poseObject'. Each entry in the 'controlObjectsTable' needs to have the controlID as the key and a sandboxObject in it's value. Returns true if successful, otherwise false.

    Example:

    mayaPose = wl_get_object("Maya Pose")
allControls = wl_pose_get_control_objects(mayaPose)
allControls["jBnd_spineA_ctrl"] = wl_get_object_self()
allControls["jBnd_spineC_ctrl"] = wl_get_object_self()
allControls["jBnd_head_ctrl"] = wl_get_object_self()
wl_pose_set_control_objects(mayaPose, allControls)

    This code gets all existing control objects and replaces a few with this Lua prop as the control object.




    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




    Sex Scene

    wl_sex_scene_get_animations_for_characters (characters_array) → string array

    This function will return a list of all valid animation names for a sex scene pairing with the given characters in the 'characters_array'.

    Example:

    characters = wl_make_name_array("Maya", "Max")
animations = wl_sex_scene_get_animations_for_characters(characters)
wl_print_table(animations)

    This code will get all available animations for a sex pairing between Max and Maya and print them into the log.


    wl_sex_scene_get_camera_sequence (sexSceneObject, animationIndex) → Table

    Returns a table with the camera sequence data for the 'sexSceneObject' for animation at 'animationIndex'.

    Example:

    sexScene = wl_get_object("Max x Maya Sex Scene")
cameraSequence = wl_sex_scene_get_camera_sequence(sexScene, 3)
wl_print_table(cameraSequence)

    This code will try to get a sex scene with the name "Max x Maya Sex Scene" and will print the camera sequence data of the animation at index 3 in the queue to the log.


    wl_sex_scene_get_camera_sequence_index (sexSceneObject, animationIndex, cameraSequenceIndex) → Table

    Returns a table with a specific camera entry (index 'cameraSequenceIndex') in the camera sequence data for the 'sexSceneObject' for animation at 'animationIndex'.

    Example:

    sexScene = wl_get_object("Max x Maya Sex Scene")
cameraSequenceEntry = wl_sex_scene_get_camera_sequence_index(sexScene, 3, 2)
wl_print_table(cameraSequenceEntry)

    This code will try to get a sex scene with the name "Max x Maya Sex Scene" and will print the camera sequence data entry index 2 of the animation at index 3 in the queue to the log.


    wl_sex_scene_get_character_pairings () → table

    This function will return a list of all valid character pairings for sex scenes.

    Example:

    pairings = wl_sex_scene_get_character_pairings()
wl_print_table(pairings)

    This code will get all available sex scene pairings and print them into the log.


    wl_sex_scene_get_controlled_character_at (sexSceneObject, index) → SandboxObject

    This function will return a controlled character object at the specified character 'index' of the 'sexSceneObject'. Returns nil if invalid (empty) or out if the index is out of bounds. Since this function accesses internal data, the index starts at 0 for the first element.

    Example:

    sexScene = wl_get_object("Max x Maya Sex Scene")
firstCharacter = wl_sex_scene_get_controlled_character_at(sexScene, 0)
print(firstCharacter)

    This function will print the first character of the given sex scene into the log.


    wl_sex_scene_get_controlled_characters (sexSceneObject) → SandboxObject array

    This function will return an array table of all the characters the given 'sexSceneObject' is currently controlling. Empty slots will still show up as nil values in the array.

    Example:

    sexScene = wl_get_object("Max x Maya Sex Scene")
characters = wl_sex_scene_get_controlled_characters(sexScene)
wl_print_table(characters)

    This code will print all participants of the given sex scene into the log.


    wl_sex_scene_get_num_controlled_characters (sexSceneObject) → integer

    This function will return the amount of characters the given 'sexSceneObject' can have. Returns 0 if the 'sexSceneObject' is invalid. The amount of characters will always remain the same for the sex scene, even if some character slots are currently empty.

    Example:

    sexScene = wl_get_object("Max x Maya Sex Scene")
numCharacters = wl_sex_scene_get_num_controlled_characters(sexScene)
print(numCharacters)

    This code will print the amount of characters in the sex scene into the log.


    wl_sex_scene_set_camera_sequence (sexSceneObject, animationIndex, cameraSequence) → bool

    This function will apply the given 'cameraSequence' data to the 'sexSceneObject' animation at index 'animationIndex'.

    Example:

    sexScene = wl_get_object("Max x Maya Sex Scene")
cameraSequence = wl_sex_scene_get_camera_sequence(sexScene, 3)
wl_sex_scene_set_camera_sequence(sexScene, 2, cameraSequence )

    This code will get the camera sequence of animation index 3 and apply it to animation at index 2


    wl_sex_scene_set_camera_sequence_index (sexSceneObject, animationIndex, cameraSequenceIndex, cameraSequence) → bool

    This function will apply the given 'cameraSequence' data entry to the 'sexSceneObject' animation at index 'animationIndex', camera sequence index 'cameraSequenceIndex'.

    Example:

    sexScene = wl_get_object("Max x Maya Sex Scene")
cameraSequence = wl_sex_scene_get_camera_sequence_index(sexScene, 3, 2)
wl_sex_scene_set_camera_sequence_index(sexScene, 3, 1, cameraSequence )

    This code will get the camera sequence of animation index 3, camera sequence index 2 and copy it to the same animation, but into camera sequence index 1.




    Transform

    wl_get_object_local_position (sandboxObject [, attachment]) → Vector

    Returns the relative position to the parent of the given 'sandboxObject' as a Vector. The optional 'attachment' parameter can be used if the given 'sandboxObject' is a character, for example, "Head" would return the local position of the characer's head bone.

    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 [, attachment]) → Vector

    Returns the relative rotation to the parent of the given 'sandboxObject' as a Vector. The optional 'attachment' parameter can be used if the given 'sandboxObject' is a character, for example, "Head" would return the local rotation of the characer's head bone.

    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 [, attachment]) → Vector

    Returns the world position of the given 'sandboxObject' as a Vector. The optional 'attachment' parameter can be used if the given 'sandboxObject' is a character, for example, "Head" would return the world position of the characer's head bone.

    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 [, attachment]) → Vector

    Returns the world rotation of the given 'sandboxObject' as a Vector. The optional 'attachment' parameter can be used if the given 'sandboxObject' is a character, for example, "Head" would return the world rotation of the characer's head bone.

    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.


    wl_transform_position (position, sandboxObject) → Vector

    Transforms the 'position' from the local space of 'sandboxObject' into world space.

    Example:

    me = wl_get_object_self()
localPos = wl_make_vector(0, 0, 100)
worldPos = wl_transform_position(localPos, me)
wl_print_table(worldPos)

    This code will convert the Lua prop local location x=0, y=0, z=100 into a world space coordinate representation and print it to the log


    wl_transform_rotation (rotation, sandboxObject) → Vector

    Transforms the 'rotation' from the local space of 'sandboxObject' into world space.

    Example:

    me = wl_get_object_self()
localRot = wl_make_vector(0, 0, 90)
worldRot = wl_transform_rotation(localRot, me)
wl_print_table(worldRot)

    This code will convert the Lua prop local rotation x=0, y=0, z=90 into a world space coordinate representation and print it to the log


    wl_transform_vector (vector, sandboxObject) → Vector

    Transforms the 'vector' from the local space of 'sandboxObject' into world space.

    Example:

    me = wl_get_object_self()
localVector = wl_make_vector(0, 0, 100)
worldVector = wl_transform_vector(localVector, me)
wl_print_table(worldVector)

    This code will convert the Lua prop local vector x=0, y=0, z=100 into a world space coordinate representation and print it to the log


    wl_inverse_transform_position (position, sandboxObject) → Vector

    Transforms the 'position' from world space into the local space of 'sandboxObject'.

    Example:

    me = wl_get_object_self()
worldPos = wl_make_vector(0, 0, 100)
localPos = wl_inverse_transform_position(worldPos, me)
wl_print_table(localPos)

    This code will convert the world location x=0, y=0, z=100 into a local space coordinate representation and print it to the log


    wl_inverse_transform_rotation (rotation, sandboxObject) → Vector

    Transforms the 'rotation' from world space into the local space of 'sandboxObject'.

    Example:

    me = wl_get_object_self()
worldRot = wl_make_vector(0, 0, 90)
localRot = wl_inverse_transform_rotation(worldRot, me)
wl_print_table(localRot)

    This code will convert the world rotation x=0, y=0, z=90 into a local space coordinate representation and print it to the log


    wl_inverse_transform_vector (vector, sandboxObject) → Vector

    Transforms the 'vector' from world space into the local space of 'sandboxObject'.

    Example:

    me = wl_get_object_self()
worldVector = wl_make_vector(0, 0, 100)
localVector = wl_inverse_transform_vector(worldVector, me)
wl_print_table(localVector)

    This code will convert the world vector x=0, y=0, z=100 into a local space coordinate representation and print it to the log




    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_distance (vectorA, vectorB) → float

    Calculates and returns the distance between the two given vectors.

    Example:

    vec1 = wl_make_vector(1,2,3)
vec2 = wl_make_vector(4,5,6)
distance = wl_vector_distance(vec1, vec2)
print(distance)

    This code creates two vectors, calculates the distance and prints the result 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_lerp (vectorA, vectorB, alpha) → Vector

    Calculates a new vector that is between 'vectorA' and 'vectorB' with the given 'alpha' value. An 'alpha' value of 0 will return 'vectorA', a value of 1 will return 'vectorB' and any value inbetween will return a position relative to the 'alpha' value, for example, an 'alpha' value of 0.5 would return the middle between the two vectors.

    Example:

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

    This ocde creates two vectors and calculates the center point between them, in this case if would return the vector x=2.5, y=3.5, z=4.5


    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_rotate_around_axis (vector, axisVector, degrees) → Vector

    This code rotates the given 'vector' around the given 'axisVector' vector by 'degrees'°

    Example:

    vector = wl_make_vector(1, 0, 0)
axis = wl_make_vector(0, 0, 1)
rotatedVector = wl_vector_rotate_around_axis(vector, axis, 45)
wl_print_vector(rotatedVector)

    This code creates an x-aligned vector and rotates it around the z-axis by 45 degrees. The resulting vector is printed to the log.


    wl_vector_rotate_around_axis_offset (vector, axisVector, degrees, offsetVector) → Vector

    Similar to wl_vector_rotate_around_axis, this code rotates the given 'vector' around the given 'axisVector' vector by 'degrees'°. This time however you can specify an offset point you want to rotate around, instead of assuming rotation around the (0, 0, 0) point.

    Example:

    vector = wl_make_vector(1, 0, 0)
axis = wl_make_vector(0, 0, 1)
offset = wl_make_vector(2, 0, 0)
rotatedVector = wl_vector_rotate_around_axis_offset(vector, axis, 45, offset)
wl_print_vector(rotatedVector)

    This code creates an x-aligned vector and rotates it around the z-axis, offset by 2 units on the x axis, by 45 degrees. The resulting vector is printed to the log.


    wl_vector_subtract (vectorA, vectorB) → Vector wl_vector_subtract (vectorA, numB) → 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.