NAV

Switch to Light Mode

Poly Bridge 3 Lua API

Unofficial API documentation for the official Poly Bridge 3 Lua API. Automatically generated from the Lua code library.

Bridge functions

BreakEdge

nil BreakEdge(id: string)

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds

GetBridgeEdgeAngle

number GetBridgeEdgeAngle(id: string)

Returns the angle of the edge

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds

GetBridgeEdgeIds

string[] GetBridgeEdgeIds()

Returns a list of id strings for all currently active bridge edges(List)

GetBridgeEdgeIdsSelected

string[] GetBridgeEdgeIdsSelected()

Returns a list of id strings for all edges that are currently selected(List)

Return Type Comment
edgeIds string[] list of id strings for all edges that are currently selected

GetBridgeEdgeIsBroken

boolean GetBridgeEdgeIsBroken(id: string)

Returns true if the edge is broken, or false if it isn't

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds

GetBridgeEdgeIsPrebuilt

boolean GetBridgeEdgeIsPrebuilt(id: string)

Returns true if the edge is prebuilt, or false if it isn't

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds()
Return Type Comment
isPrebuilt boolean true if the edge is prebuilt, or false if it isn't

GetBridgeEdgeJoints

string[] GetBridgeEdgeJoints(id: string)

Returns a list of id strings representing the two joints this edge is connected to (List)

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds

GetBridgeEdgeLength

number GetBridgeEdgeLength(id: string)

Returns the length of the edge

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds

GetBridgeEdgeMaterial

string GetBridgeEdgeMaterial(id: string)

Returns the material name of the edge, see appendix for valid material names

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds

GetBridgeEdgePosition

Vec3 GetBridgeEdgePosition(id: string)

Returns the current game world position of the bridge edge as a float list of length 3 (corresponding to x, y, and z position) (List)

Argument Type Comment
id string is the id of the bridge edge, usually obtained from GetBridgeEdgeIds()

GetBridgeEdgeStressNormalized

number GetBridgeEdgeStressNormalized(id: string)

Returns the current normalized stress of the edge (float)

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds()

GetBridgeEdgeStressSigned

number GetBridgeEdgeStressSigned(id: string)

Returns the current unsigned normalized stress of the edge (float). 0 to +1 is compression, and 0 to -1 is tension.

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds()

GetFoundationIds

string[] GetFoundationIds()

Returns a list of id strings for all currently active foundations (List)

GetFoundationIdsSelected

string[] GetFoundationIdsSelected()

Returns a list of id strings for all foundations that are currently selected(List)

Return Type Comment
foundationIds string[] list of id strings for all foundations that are currently selected

GetJointEdges

string[] GetJointEdges(id: string)

Returns list of id strings representing all edges attached to this joint (List)

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
Return Type Comment
edgeIds string[] list of id strings representing all edges attached to this joint

GetJointIds

string[] GetJointIds()

Returns a list of id strings for all currently active joints (List)

Return Type Comment
jointIds string[] list of id strings for all currently active joints

GetJointIdsSelected

string[] GetJointIdsSelected()

Returns a list of id strings for all joints that are currently selected(List)

Return Type Comment
jointIds string[] list of id strings for all joints that are currently selected

GetJointIsAnchor

boolean GetJointIsAnchor(id: string)

Returns true if the joint is an anchor, returns false if it isn't

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
Return Type Comment
isAnchor boolean true if the joint is an anchor, returns false if it isn't

GetJointIsPrebuilt

boolean GetJointIsPrebuilt(id: string)

Returns true if the edge is prebuilt, or false if it isn't

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
Return Type Comment
isPrebuilt boolean true if the edge is prebuilt, or false if it isn't

GetJointIsSplit

boolean GetJointIsSplit(id: string)

Returns true if the joint is a split joint, returns false if it isn't

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
Return Type Comment
isSplit boolean true if the joint is a split joint, returns false if it isn't

GetJointIsUnbuildable

boolean GetJointIsUnbuildable(id: string)

Returns true if the joint is unbuildable

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
Return Type Comment
isUnbuildable boolean true if the joint is unbuildable

GetJointPosition

Vec3 GetJointPosition(id: string)

Returns the current game world position of the joint as a float list of length 3 (corresponding to x, y, and z position)

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
Return Type Comment
jointPosition Vec3 the current game world position of the joint as a float list of length 3

GetOverrideEdgeColor

string GetOverrideEdgeColor(id: string)

Returns the override color string of this edge, returns empty string if uncolored

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds

GetPermanentEdgeColor

string GetPermanentEdgeColor(id: string)

Returns the permanent color string of this edge, returns empty string if uncolored

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds()
Return Type Comment
overrideColor string the permanent color string of this edge, returns empty string if uncolored

IgnoreEdgePlacementRestrictions

nil IgnoreEdgePlacementRestrictions(value: boolean)

Argument Type Comment
value boolean determines if edge placement restrictions are ignored or not.

PlaceEdgeJointToJoint

string PlaceEdgeJointToJoint(materialName: string, jointIdA: string, jointIdB: string)

Attempts to place an edge between two joints, respecting all placement restrictions to only place edges legally. Can only be used in BUILD or SANDBOX modes. Returns “SUCCESS” on success, or an error message on failure.

Argument Type Comment
materialName string is the name of the desired material.
jointIdA string is the id of the start joint, usually obtained from GetJointIds
jointIdB string is the id of the end joint, usually obtained from GetJointIds
Return Type Comment
success string “SUCCESS” on success, or an error message on failure.

PlaceEdgeJointToJointCheat

string PlaceEdgeJointToJointCheat(materialName: string, jointIdA: string, jointIdB: string)

Argument Type Comment
materialName string is the name of the desired material.
jointIdA string is the id of the start joint, usually obtained from GetJointIds
jointIdB string is the id of the end joint, usually obtained from GetJointIds
Return Type Comment
success string “SUCCESS” on success, or an error message on failure.

PlaceEdgeJointToPos

string PlaceEdgeJointToPos(materialName: string, jointIdA: string, posB: Vec3)

Attempts to place an edge starting at the given joint and ending at the given position, respecting all placement restrictions to only place edges legally. Can only be used in BUILD or SANDBOX modes. Returns “SUCCESS” on success, or an error message on failure.

Argument Type Comment
materialName string is the name of the desired material.
jointIdA string is the id of the start joint, usually obtained from GetJointIds.
posB Vec3 is the end position of the edge.
Return Type Comment
success string “SUCCESS” on success, or an error message on failure.

PlaceEdgeJointToPosCheat

string PlaceEdgeJointToPosCheat(materialName: string, jointIdA: string, posB: Vec3)

Argument Type Comment
materialName string is the name of the desired material.
jointIdA string is the id of the start joint, usually obtained from GetJointIds
posB Vec3 is the end position of the edge.
Return Type Comment
success string “SUCCESS” on success, or an error message on failure.

PlaceEdgePosToPos

string PlaceEdgePosToPos(materialName: string, posA: Vec3, posB: Vec3)

Attempts to place an edge starting at posA and ending at posB, respecting all placement restrictions to only place edges legally. Can only be used in BUILD or SANDBOX modes. Returns “SUCCESS” on success, or an error message on failure.

Argument Type Comment
materialName string is the name of the desired material.
posA Vec3 is the start position of the edge. This MUST be near enough to an existing joint so that edge placement can begin at that joint.
posB Vec3 is the end position of the edge.
Return Type Comment
success string “SUCCESS” on success, or an error message on failure.

PlaceEdgePosToPosCheat

string PlaceEdgePosToPosCheat(materialName: string, posA: Vec3, posB: Vec3)

Argument Type Comment
materialName string is the name of the desired material.
posA Vec3 is the start position of the edge. If there is no nearby joint, a joint will be created as the start joint.
posB Vec3 is the end position of the edge.
Return Type Comment
success string “SUCCESS” on success, or an error message on failure.

SetJointIsSplit

nil SetJointIsSplit(id: string, isSplit: boolean)

Sets joint split state. NOTE: joints can only be split in Build mode on levels with hydraulic phases

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
isSplit boolean determines if the joint is split or not

SetJointLegalPosition

nil SetJointLegalPosition(id: string, targetPosition: Vec3)

Attempts to set a joint’s position to the target position, following all normal joint movement restrictions

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
targetPosition Vec3 is the position to move the joint to

SetJointPosition

nil SetJointPosition(id: string, position: Vec3)

Argument Type Comment
id string is the id of the joint, usually obtained from GetJointIds
position Vec3 is the desired position of the joint

SetOverrideEdgeColor

nil SetOverrideEdgeColor(id: string, overrideColor: string)

Set the color of this edge, overriding the normal texture and stress color visualization

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds
overrideColor string is the color to set the edge. Format: #RRGGBBAA

SetPermanentEdgeColor

nil SetPermanentEdgeColor(id: string, overrideColor: string)

Set the color of this edge, overriding the normal texture and stress color visualization. This color will persist when switching between build mode and sim mode, as well as persist through save/load. Note that SetOverrideEdgeColor takes priority over the permanent color if it is used.

Argument Type Comment
id string is the id of the edge, usually obtained from GetBridgeEdgeIds()
overrideColor string is the color to set the edge. Format: #RRGGBBAA

Camera functions

GetCameraFOV

number GetCameraFOV()

returns the Field Of View value of the camera (float)

Return Type Comment
fov number the Field Of View value of the camera

GetCameraOrthographic

boolean GetCameraOrthographic()

Returns true if the camera is set to Orthographic, otherwise returns false

Return Type Comment
isOrthographic boolean true if the camera is set to Orthographic, otherwise returns false

GetCameraOrthographicSize

number GetCameraOrthographicSize()

Returns the Orthographic Size value of the camera (float)

Return Type Comment
size number the Orthographic Size value of the camera

GetCameraPosition

Vec3 GetCameraPosition()

Returns the current game world position of the camera as a float list of length 3 (corresponding to x, y, and z position)

Return Type Comment
position Vec3 the current game world position of the camera as a float list of length 3

GetCameraRotation

Vec3 GetCameraRotation()

Returns the current game world rotation of the camera as a float list of length 3 (corresponding to x, y, and z euler angles)

Return Type Comment
rotation Vec3 the current game world rotation of the camera as a float list of length 3

SetCameraFOV

nil SetCameraFOV(value: number)

Sets the Field Of View value of the camera to the desired value

Argument Type Comment
value number is the desired Field Of View value of the camera

SetCameraLookAtObject

nil SetCameraLookAtObject(objectId: string)

Sets the camera's rotation so that it looks at the desired object, note this will only work correctly if Orthographic is set to false

Argument Type Comment
objectId string is the id of the vehicle, edge, or joint to look at

SetCameraOrthographic

nil SetCameraOrthographic(value: boolean)

Sets the Orthographic setting of the camera to the desired value

Argument Type Comment
value boolean is the desired Orthographic state

SetCameraOrthographicSize

nil SetCameraOrthographicSize(value: number)

Sets the Orthographic Size value of the camera to the desired value

Argument Type Comment
value number is the desired Orthographic Size value of the camera

SetCameraPosition

nil SetCameraPosition(position: Vec3)

Sets the current game world position of the camera

Argument Type Comment
position Vec3 is the desired position of the camera (corresponding to x, y, and z position)

SetCameraRotation

nil SetCameraRotation(rotation: Vec3)

Sets the current game world rotation of the camera

Argument Type Comment
rotation Vec3 is the desired rotation of the camera (corresponding to x, y, and z euler angles)

Debug functions

AddDebugConsoleCommand

Example:

-- OnModLoad.lua:
EnableDebugConsole()
AddDebugConsoleCommand("set_material_cost", "usage: set_material_cost <material_name> <cost_value>", 2)
-- ConsoleCommands.lua:
function set_material_cost(args)
  materialName = args[1]
  costValue = tonumber(args[2])
  SetMaterialCost(materialName, costValue)
end

nil AddDebugConsoleCommand(commandName: string, helpText: string, numParameters: integer)

Adds a console command that calls a named function from ConsoleCommands.lua

Argument Type Comment
commandName string is the name of the command the user will type into the debug console
helpText string is the help text string the user will see when they type “help” in the debug console
numParameters integer is the number of parameters the command requires (use 0 to make app parameters optional and use varargs (...) in the command function)

EnableDebugConsole

nil EnableDebugConsole()

Unlocks the debug console, allowing it to be opened using the ~ key

EnableLevelNavArrows

nil EnableLevelNavArrows()

Enables buttons in the top bar for navigation forward and backwards through campaign levels.

ShowLevelID

nil ShowLevelID()

Shows the current level ID in the level info panel

Game State functions

EndLevelFail

boolean EndLevelFail(failReasonText: string)

If you are in sim mode and the simulation has started, immediately end the simulation and go to level failed screen, showing failReason text. returns true if successful.

Argument Type Comment
failReasonText string Message to show in the fail panel

EndLevelSuccess

boolean EndLevelSuccess()

GetCurrentLevelID

string GetCurrentLevelID()

Returns the current level ID (string)

Return Type Comment
levelID string the current level ID

GetDefaultSimSpeed

number GetDefaultSimSpeed()

Returns the default normalized sim speed (float)

Return Type Comment
simSpeed number the default normalized sim speed

GetSimSpeed

number GetSimSpeed()

Returns the current normalized sim speed (float)

Return Type Comment
simSpeed number the current normalized sim speed

IsSimulating

boolean IsSimulating()

Returns true if you are in sim mode and the simulation has started, otherwise returns false.

IsSimulatingWithoutPassOrFail

boolean IsSimulatingWithoutPassOrFail()

Returns true or false based on if the game is currently simulating but pass/fail has yet to be determined

SetSimSpeed

nil SetSimSpeed(speed: number)

Sets the current sim speed to the desired value, note that the desired value must be a valid sim speed in the current sim speed list. Default valid sim speeds are {0.1, 0.2, 0.5, 1, 2, 3, 5}

Argument Type Comment
speed number is the desired normalized sim speed

SimulationEnd

boolean SimulationEnd()

Ends simulation if you are in sim mode and the simulation has started. returns true if successful.

SimulationPause

boolean SimulationPause()

Pauses simulation if you are in sim mode and the simulation has started. returns true if successful.

SimulationStart

boolean SimulationStart()

Starts simulation if you are in build mode, or resumes simulating if you are in a paused simulation. returns true if successful.

SimulationTogglePause

boolean SimulationTogglePause()

Toggles pause state of simulation if you are in sim mode and the simulation has started. returns true if successful.

SimulationUnpause

boolean SimulationUnpause()

Unpauses simulation if you are in sim mode and the simulation has started. returns true if successful.

Generic functions

GetVehiclePhysicsVelocity

nil GetVehiclePhysicsVelocity(undefined)

OpenLevel

nil OpenLevel(undefined)

OpenWorkshopLevel

nil OpenWorkshopLevel(undefined)

SetRoadEdgeTint

nil SetRoadEdgeTint(undefined)

SetVehiclePhysicsVelocity

nil SetVehiclePhysicsVelocity(undefined)

SetVehiclePosition

nil SetVehiclePosition(undefined)

SetVehicleRotation

nil SetVehicleRotation(undefined)

SetVehicleSpeed

nil SetVehicleSpeed(undefined)

Language functions

AddLanguageCSV

nil AddLanguageCSV(filename: string)

Add a translation for the game UI. A template for this file can be created on the Workshop -> Created panel.

Argument Type Comment
filename string The name of the csv file located in the same directory as the lua script.

Material functions

GetHydraulicsBaseTint

string GetHydraulicsBaseTint()

Returns the tint color string for hydraulics base texture

Return Type Comment
tintColor string The tint color string for hydraulics base texture

GetMaterialCost

number GetMaterialCost(materialName: string)

Returns the cost per meter of the given material

Argument Type Comment
materialName string must match one of the material names above.
Return Type Comment
cost number The cost per meter of the given material

GetMaterialMaxLength

number GetMaterialMaxLength(materialName: string)

Returns the max length of the given material

Argument Type Comment
materialName string must match one of the material names above.
Return Type Comment
cost number The max length of the given material

GetMaterialStrength

number GetMaterialStrength(materialName: string)

Returns the strength of the given material

Argument Type Comment
materialName string must match one of the material names above.
Return Type Comment
strength number The strength of the given material

GetMaterialTint

string GetMaterialTint(materialName: string)

Returns the tint color string for this material

Argument Type Comment
materialName string The name of the material to permanently tint, see appendix for valid material names
Return Type Comment
tintColor string The tint color string for this material

GetRoadEdgeTint

string GetRoadEdgeTint()

Returns the tint color string for road edge texture

Return Type Comment
tintColor string The tint color string for road edge texture

SetHydraulicsBaseTint

nil SetHydraulicsBaseTint(tintColor: string)

Permanently tints the texture of the base of the hydraulic. Note that the extending/contracting part of the hydraulic can be tinted using SetMaterialTint()

Argument Type Comment
tintColor string The color to tint the material. Format: #RRGGBBAA

SetMaterialCost

nil SetMaterialCost(materialName: string, value: number)

Argument Type Comment
materialName string must match one of the material names in the Appendix.
value number can be any decimal value.

SetMaterialMaxLength

nil SetMaterialMaxLength(materialName: string, value: number)

Argument Type Comment
materialName string must match one of the material names in the Appendix.
value number can be any decimal value.

SetMaterialStrength

nil SetMaterialStrength(materialName: string, value: number)

Argument Type Comment
materialName string must match one of the material names in the Appendix.
value number can be any decimal value.

SetMaterialTint

nil SetMaterialTint(materialName: string, tintColor: string)

Permanently tints the texture of the given material. Note that Hydraulics and Roads use a secondary texture, which can be tinted using SetHydraulicsBaseTint and SetRoadEdgeTint respectively

Argument Type Comment
materialName string The name of the material to permanently tint, see appendix for valid material names
tintColor string The color to tint the material. Format: #RRGGBBAA

Sandbox functions

AddCustomShape

nil AddCustomShape(folderName: string)

Add custom shape(s) to be used in sandbox

Argument Type Comment
folderName string The name of directory containing the custom shape(s)

AddCustomShapeTexture

nil AddCustomShapeTexture(filename: string, textureName: string, id: string)

Adds a texture to be used in custom shapes in sandbox

Argument Type Comment
filename string The name of the png file located in the same directory as the lua script.
textureName string The name that will appear in the dropdown when selecting custom shape textures.
id string ID for this texture. If you have multiple textures in your mod, they must have unique id values. If you edit your mod after uploading, do not change this id value.

DisableRandomVehicleSpawn

nil DisableRandomVehicleSpawn()

Disables the random vehicle spawning that occurs when a new Sandbox is created

Screen UI functions

CreateButtonObject

nil CreateButtonObject(buttonId: string, callback: string, width: integer, height: integer)

Creates a new button object NOTE: Please make your callback function name as unique as possible. If multiple callbacks across different mods share the same name, the one loaded last will overwrite the others.

Argument Type Comment
buttonId string is the name of the button object, used to update it later
callback string is the name of the LUA function this button will execute when pressed
width integer is the width of the button
height integer is the height of the button

CreateSpriteObject

nil CreateSpriteObject(spriteId: string, imagePath: string, width: integer, height: integer)

Creates a new sprite object

Argument Type Comment
spriteId string is the name of the sprite object, used to update it later
imagePath string is the local path of the image file to use for this sprite object
width integer is the width of the sprite object
height integer is the height of the sprite object

CreateTextObject

nil CreateTextObject(objectId: string, width: integer, height: integer)

Creates a new text object

Argument Type Comment
objectId string is the name of the text object, used to update it later
width integer is the width of the text field, used for pivot points and to determine when longer text will wrap
height integer is the height of the text field, used for pivot points

DestroyButtonObject

nil DestroyButtonObject(buttonId: string)

Destroys a button by id

Argument Type Comment
buttonId string is the name of the button object

DestroySpriteObject

nil DestroySpriteObject(spriteId: string)

Destroys a sprite object

Argument Type Comment
spriteId string is the name of the sprite object

DestroyTextObject

nil DestroyTextObject(objectId: string)

Destroys a previously created text object with the given id

Argument Type Comment
objectId string is the name of the text object

UpdateButtonAddHoverScale

nil UpdateButtonAddHoverScale(buttonId: string)

Adds a scale-up effect when the button is hovered

Argument Type Comment
buttonId string is the name of the button object

UpdateButtonCallback

nil UpdateButtonCallback(buttonId: string, callback: string)

Sets the button callback to a named global function name NOTE: Please make your callback function name as unique as possible. If multiple callbacks across different mods share the same name, the one loaded last will overwrite the others.

Argument Type Comment
buttonId string is the name of the button object
callback string is the name of the LUA function this button will execute when pressed

UpdateButtonColor

nil UpdateButtonColor(buttonId: string, normalColorStr: string, hoverColorStr: string)

Sets the background color of a button

Argument Type Comment
buttonId string is the name of the button object
normalColorStr string is the new color value for the color of the button when not being hovered, using format: #RRGGBBAA
hoverColorStr string is the new color value for the color of the button when it is being hovered, using format: #RRGGBBAA

UpdateButtonImage

nil UpdateButtonImage(buttonId: string, imagePath: string)

Sets the image of a button

Argument Type Comment
buttonId string is the name of the button object
imagePath string is the local path of the image file to use for the sprite of this button

UpdateButtonPivot

nil UpdateButtonPivot(buttonId: string, xPivot: number, yPivot: number)

sets the pivot point of a button

Argument Type Comment
buttonId string is the name of the button object
xPivot number is the x-axis of the button’s pivot point, 0 being the left side and 1 being the right side
yPivot number is the y-axis of the button’s pivot point, 0 being the bottom and 1 being the top

UpdateButtonScreenPos

nil UpdateButtonScreenPos(buttonId: string, xScreenPos: number, yScreenPos: number)

Sets the screen position of a button

Argument Type Comment
buttonId string is the name of the button object
xScreenPos number is the x-axis screen position, 0 being the left side and 1 being the right side
yScreenPos number is the y-axis screen position, 0 being the bottom and 1 being the top

UpdateButtonSetInteractable

nil UpdateButtonSetInteractable(buttonId: string, interactable: boolean)

Enables or disables a button

Argument Type Comment
buttonId string is the name of the button object
interactable boolean determines if the button can be clicked or not

UpdateButtonSetOutlineActive

nil UpdateButtonSetOutlineActive(buttonId: string, outlineActive: boolean)

Enables the outline of a button

Argument Type Comment
buttonId string is the name of the button object
outlineActive boolean determines if the outline is active or not

UpdateButtonText

nil UpdateButtonText(buttonId: string, buttonText: string)

Sets the text of a button

Argument Type Comment
buttonId string is the name of the button object
buttonText string is the display text on the button object

UpdateButtonTextColor

nil UpdateButtonTextColor(buttonId: string, colorStr: string)

Sets the text color of a button

Argument Type Comment
buttonId string is the name of the button object
colorStr string is the new color value for the display text of the button, using format: #RRGGBBAA

UpdateButtonTooltipText

nil UpdateButtonTooltipText(buttonId: string, tooltipText: string)

Sets the hover tooltip of a button

Argument Type Comment
buttonId string is the name of the button object
tooltipText string is the display text of the tooltip when hovering the button

UpdateSpriteColor

nil UpdateSpriteColor(spriteId: string, colorString: string)

Sets the color filter of a sprite object. For example a 1x1 solid white image with a 50% transparent red color (#FF000080) will draw a 50% transparent red sprite.

Argument Type Comment
spriteId string is the name of the sprite object
colorString string is the new color value for the sprite, using format: #RRGGBBAA

UpdateSpriteImage

nil UpdateSpriteImage(spriteId: string, imagePath: string)

Sets the image of a sprite object

Argument Type Comment
spriteId string is the name of the sprite object
imagePath string is the local path of the image file to use for this sprite object

UpdateSpritePivot

nil UpdateSpritePivot(spriteId: string, xPivot: number, yPivot: number)

Sets the pivot point of a sprite object

Argument Type Comment
spriteId string is the name of the sprite object
xPivot number is the x-axis of the sprite’s pivot point, 0 being the left side and 1 being the right side
yPivot number is the y-axis of the sprite’s pivot point, 0 being the bottom and 1 being the top

UpdateSpriteScreenPos

nil UpdateSpriteScreenPos(spriteId: string, xScreenPos: number, yScreenPos: number)

Sets the screen position of a sprite object

Argument Type Comment
spriteId string is the name of the sprite object
xScreenPos number is the x-axis screen position, 0 being the left side and 1 being the right side
yScreenPos number is the y-axis screen position, 0 being the bottom and 1 being the top

UpdateTextAlignment

nil UpdateTextAlignment(objectId: string, horizontalAlign: string, verticalAlign: string)

Sets the alignment of a text object

Argument Type Comment
objectId string is the name of the text object used when calling CreateTextObject
horizontalAlign string is the horizontal text alignment, acceptable values are: “Left”, “Center”, “Right”, and “Justified”
verticalAlign string is the vertical text alignment, acceptable values are: “Top”, “Middle”, and “Bottom”

UpdateTextColor

nil UpdateTextColor(objectId: string, colorString: string)

Sets the color of a text object

Argument Type Comment
objectId string is the name of the text object used when calling CreateTextObject
colorString string is the new color value for the text field, using format: #RRGGBBAA

UpdateTextFontSize

nil UpdateTextFontSize(objectId: string, fontSize: integer)

Sets the font size of a text object

Argument Type Comment
objectId string is the name of the text object used when calling CreateTextObject
fontSize integer is the new font size value for the text field

UpdateTextMaxWidth

nil UpdateTextMaxWidth(objectId: string, maxWidth: integer)

Sets the maximum width of a text object

Argument Type Comment
objectId string is the name of the text object used when calling CreateTextObject
maxWidth integer is the max width value for the text field to start wrapping

UpdateTextPivot

nil UpdateTextPivot(objectId: string, xPivot: number, yPivot: number)

Sets the pivot point of a text object

Argument Type Comment
objectId string is the name of the text object used when calling CreateTextObject
xPivot number is the x-axis of the text field’s pivot point, 0 being the left side and 1 being the right side
yPivot number is the y-axis of the text field’s pivot point, 0 being the bottom and 1 being the top

UpdateTextScreenPos

nil UpdateTextScreenPos(objectId: string, xScreenPos: number, yScreenPos: number)

Sets the screen position of a text object

Argument Type Comment
objectId string is the name of the text object used when calling CreateTextObject
xScreenPos number is the x-axis screen position, 0 being the left side and 1 being the right side
yScreenPos number is the y-axis screen position, 0 being the bottom and 1 being the top

UpdateTextSetBackgroundActive

nil UpdateTextSetBackgroundActive(objectId: string, bgActive: boolean)

Enables the background of a text object NOTE: the background auto-scales to the display size of the text, which will prevent the text pivot and alignment from working as expected

Argument Type Comment
objectId string is the name of the text object
bgActive boolean determines if the background is active or not.

UpdateTextSetBackgroundColor

nil UpdateTextSetBackgroundColor(objectId: string, bgColorString: string, outlineColorString: string)

Sets the background color of a text object

Argument Type Comment
objectId string is the name of the text object
bgColorString string is the new color value for the overall background, using format: #RRGGBBAA
outlineColorString string is the new color value for the outline around the background, using format: #RRGGBBAA

UpdateTextString

nil UpdateTextString(objectId: string, textString: string)

Sets the text in a text object

Argument Type Comment
objectId string is the name of the text object used when calling CreateTextObject
textString string is the string that will appear in the text field

Theme functions

SetThemeSky

Example:

SetThemeSky("rocks", "#FF0000", "#00FF00", "#0000FF", "0.5")

nil SetThemeSky(themeName: string, topColor: string, midColor: string, botColor: string, offset: number)

Sets the sky color in different level themes

Argument Type Comment
themeName string name of the theme to be modified. Currently one of: Alpine, Rocks, HighDesert, SkyCreeper
topColor string Color of top portion of sky using format: #RRGGBBAA
midColor string Color of top portion of sky using format: #RRGGBBAA
botColor string Color of top portion of sky using format: #RRGGBBAA
offset number Value between 0 and 1 that controls how colors blend. 0: blend between top and mid colors, 0.5: ⅓ top, ⅓ mid, ⅓ bot, 1: blend between mid and bot colors

UGC functions

AddAssetBoat

nil AddAssetBoat(iconFilename: string, boatName: string, prefabAddress: string, mass: number)

Loads a z-axis boat asset from an addressable prefab to be used in sandbox and workshop. See the UGC Pipeline section of the documentation for more info.

Argument Type Comment
iconFilename string is the name of the png file located in the same directory as the lua script, representing the icon that will appear in the dropdown to select this item.
boatName string is the name that will appear in game.
prefabAddress string is the address of the prefab object defined in the Mod Creation project.
mass number is the default mass of the object, used to sort UGC assets.

AddAssetDecor

nil AddAssetDecor(iconFilename: string, decorName: string, prefabAddress: string)

Loads a decor asset from an addressable prefab to be used in sandbox and workshop. See the UGC Pipeline section of the documentation for more info.

Argument Type Comment
iconFilename string The name of the png file located in the same directory as the lua script, representing the icon that will appear in the dropdown to select this decor item.
decorName string The name that will appear in the decor dropdown.
prefabAddress string The address of the prefab object defined in the Mod Creation project. See the UGC Pipeline section for more info.

AddAssetPlane

nil AddAssetPlane(iconFilename: string, planeName: string, prefabAddress: string, mass: number)

Loads a z-axis plane asset from an addressable prefab to be used in sandbox and workshop. See the UGC Pipeline section of the documentation for more info.

Argument Type Comment
iconFilename string is the name of the png file located in the same directory as the lua script, representing the icon that will appear in the dropdown to select this item.
planeName string is the name that will appear in game.
prefabAddress string is the address of the prefab object defined in the Mod Creation project.
mass number is the default mass of the object, used to sort UGC assets.

AddAssetVehicle

nil AddAssetVehicle(iconFilename: string, vehicleName: string, prefabAddress: string, mass: number)

Loads a vehicle asset from an addressable prefab to be used in sandbox and workshop. See the UGC Pipeline section of the documentation for more info.

Argument Type Comment
iconFilename string is the name of the png file located in the same directory as the lua script, representing the icon that will appear in the dropdown to select this vehicle.
vehicleName string is the name that will appear in the vehicle dropdown.
prefabAddress string is the address of the prefab object defined in the Mod Creation project.
mass number is the default mass of the object, used to sort UGC assets.

UI functions

IsMenuOpen

boolean IsMenuOpen()

Returns true if any menu is open, otherwise returns false

Return Type Comment
isOpen boolean true if any menu (modal) is open, otherwise returns false

IsStressVisibilityEnabled

boolean IsStressVisibilityEnabled()

Returns true if stress visibility is enabled, otherwise returns false

Return Type Comment
isEnabled boolean true if stress visibility is enabled, otherwise returns false

SetDefaultSimSpeed

nil SetDefaultSimSpeed(speed: integer)

Sets the default sim speed from the available speeds. If speed does not exist in list of simulation speeds, then value is ignored

Argument Type Comment
speed integer Default simulation speed

SetSimSpeeds

nil SetSimSpeeds(speeds: integer[])

Sets the available simulation speeds to use in game as table of integers where 1000=1.0x. Default: {100, 200, 500, 1000, 2000, 3000, 5000}

Argument Type Comment
speeds integer[] Simulation speeds to use in game

ShowMessage

nil ShowMessage(text: string)

Shows an information popup message in the center of the screen with an OK button

Argument Type Comment
text string is the text to show in a popup

Utils functions

ConsoleLog

nil ConsoleLog(message: string)

Log a message to the consoles

Argument Type Comment
message string will be printed to the Unity Editor console

GetFrameCount

number GetFrameCount()

Returns the total number of frames since the start of the game (int)

Return Type Comment
frames number the total number of frames since the start of the game

GetGameState

string GetGameState()

Returns the current game state (string). Valid values include: MAIN_MENU, BUILD, SANDBOX, SIM.

Return Type Comment
state string the current game state (string). (MAIN_MENU, BUILD, SANDBOX, SIM)

GetGameTime

number GetGameTime()

Returns the time in seconds since the start of the game (float)

GetKeycodeDown

boolean GetKeycodeDown(keycodeNumber: integer)

Returns true if the key is currently held down, otherwise returns false

Argument Type Comment
keycodeNumber integer is the integer value of the desired key, like 112 for "P" or 303 for "RightShift". Full list can be found here: https://gist.github.com/Extremelyd1/4bcd495e21453ed9e1dffa27f6ba5f69

GetKeycodeJustPressed

boolean GetKeycodeJustPressed(keycodeNumber: integer)

Returns true if the key was just pressed this frame, otherwise returns false

Argument Type Comment
keycodeNumber integer is the integer value of the desired key, like 112 for "P" or 303 for "RightShift". Full list can be found here: https://gist.github.com/Extremelyd1/4bcd495e21453ed9e1dffa27f6ba5f69

GetKeyDown

boolean GetKeyDown(keycodeString: string)

Returns true if the key is currently held down, otherwise returns false

Argument Type Comment
keycodeString string is the name of the desired key, like "P" or "RightShift". Full list can be found here: https://gist.github.com/Extremelyd1/4bcd495e21453ed9e1dffa27f6ba5f69

GetKeyJustPressed

boolean GetKeyJustPressed(keycodeString: string)

Returns true if the key was just pressed this frame, otherwise returns false

Argument Type Comment
keycodeString string is the name of the desired key, like "P" or "RightShift". Full list can be found here: https://gist.github.com/Extremelyd1/4bcd495e21453ed9e1dffa27f6ba5f69

GetMouseButtonDown

boolean GetMouseButtonDown(mouseButton: integer)

Returns true if the button is currently held down, otherwise returns false

Argument Type Comment
mouseButton integer is the value of the desired mouse button: 0 is the primary button, 1 is the secondary button, and 2 is the middle button

GetMouseButtonJustPressed

boolean GetMouseButtonJustPressed(mouseButton: integer)

Returns true if the button was just pressed this frame, otherwise returns false

Argument Type Comment
mouseButton integer is the value of the desired mouse button: 0 is the primary button, 1 is the secondary button, and 2 is the middle button

GetMousePosition

Vec2 GetMousePosition()

Returns the current x,y position of the mouse in pixels (List)

GetMouseScreenPosition

Vec2 GetMouseScreenPosition()

Returns the current x,y position of the mouse normalized to screen position, where 0,0 is the bottom left and 1,1 is the top right (List)

GetMouseWorldPosition

Vec3 GetMouseWorldPosition()

Returns the world position of the mouse (List)

GetNameOfKeyDownThisFrame

string GetNameOfKeyDownThisFrame()

Returns the name (string) of the first detected key pressed this frame

GetScreenResolution

Vec2 GetScreenResolution()

Returns the current screen resolution as a float list of length 2 (corresponding to width and height) (List)

GetUnscaledDeltaTime

number GetUnscaledDeltaTime()

Returns the interval in seconds from the last frame to the current one (float)

Return Type Comment
interval number the interval in seconds from the last frame to the current one

GetVar_Float

number GetVar_Float(varName: string)

Returns the value of the variable (float)

Argument Type Comment
varName string is the name of the float variable previously set using SetVar_Float

GetVar_FloatList

number[] GetVar_FloatList(varName: string)

Returns the value of the variable (List)

Argument Type Comment
varName string is the name of the float list variable previously set using SetVar_FloatList

GetVar_Int

integer GetVar_Int(varName: string)

Returns the value of the variable (int)

Argument Type Comment
varName string is the name of the integer variable previously set using SetVar_Int

GetVar_IntList

integer[] GetVar_IntList(varName: string)

Returns the value of the variable (List)

Argument Type Comment
varName string is the name of the integer list variable previously set using SetVar_IntList

GetVar_String

string GetVar_String(varName: string)

Returns the value of the variable (string)

Argument Type Comment
varName string is the name of the string variable previously set using SetVar_String

GetVar_StringList

string[] GetVar_StringList(varName: string)

Returns the value of the variable (List)

Argument Type Comment
varName string is the name of the string list variable previously set using SetVar_StringList

RunLuaDelayed

nil RunLuaDelayed(luaString: string, delaySeconds: number)

Evaluates and runs the given lua string after a delay NOTE: the given lua string must be formatted exactly as it would be written in a lua script, so you may need to use escape characters.

Argument Type Comment
luaString string is the lua string to be executed
delaySeconds number is the number of seconds to wait before executing the string

SetGameInputActive

nil SetGameInputActive(isActive: boolean)

Enables or disables normal game input completely

Argument Type Comment
isActive boolean determines if normal game input is active or not

SetIgnoreGameInputKey

nil SetIgnoreGameInputKey(keycodeString: string)

After being set, holding down this key will cause normal game input to be ignored

Argument Type Comment
keycodeString string is the name of the desired key, like "P" or "RightShift". Full list can be found here: https://gist.github.com/Extremelyd1/4bcd495e21453ed9e1dffa27f6ba5f69

SetIgnoreGameInputKeycode

nil SetIgnoreGameInputKeycode(keycodeNumber: integer)

After being set, holding down this key will cause normal game input to be ignored

Argument Type Comment
keycodeNumber integer is the integer value of the desired key, like 112 for "P" or 303 for "RightShift". Full list can be found here: https://gist.github.com/Extremelyd1/4bcd495e21453ed9e1dffa27f6ba5f69

SetVar_Float

nil SetVar_Float(varName: string, floatValue: number)

Argument Type Comment
varName string is the name of the float variable
floatValue number is the value of the variable

SetVar_FloatList

nil SetVar_FloatList(varName: string, listValue: number[])

Argument Type Comment
varName string is the name of the float list variable
listValue number[] is the value of the variable

SetVar_Int

nil SetVar_Int(varName: string, intValue: integer)

Argument Type Comment
varName string is the name of the integer variable
intValue integer is the value of the variable

SetVar_IntList

nil SetVar_IntList(varName: string, listValue: integer[])

Argument Type Comment
varName string is the name of the integer list variable
listValue integer[] is the value of the variable

SetVar_String

nil SetVar_String(varName: string, stringValue: string)

Argument Type Comment
varName string is the name of the string variable
stringValue string is the value of the variable

SetVar_StringList

nil SetVar_StringList(varName: string, listValue: string[])

Argument Type Comment
varName string is the name of the string list variable
listValue string[] is the value of the variable

WorldToScreenPos

Vec3 WorldToScreenPos(worldPos: Vec3)

Returns the screen position as a float list of length 3 (corresponding to x, y, and z position) representing the position on screen (List)

Argument Type Comment
worldPos Vec3 is a float list of length 3 (corresponding to x, y, and z position) representing the game world position
Return Type Comment
screenPos Vec3 the screen position as a float list of length 3

Vehicle functions

AddVehicleSkin

nil AddVehicleSkin(vehicleAddressableName: string, filename: string, displayName: string, flagColor: string, id: string)

Adds a skin for a vanilla vehicle

Argument Type Comment
vehicleAddressableName string Unique name that is used to identify the vehicle type. See Vehicle Addressable Names table in Appendix for list of all vehicle addressable names.
filename string is the name of the png file located in the same directory as the lua script.
displayName string is the name that will appear in the dropdown when selecting vehicle skins.
flagColor string Default color to use for flag and checkpoints. Format: #RRGGBBAA
id string is an id for this skin. If you have multiple textures in your mod, they must have unique id values. If you edit your mod after uploading, do not change this id value.

GetVehicleAcceleration

number GetVehicleAcceleration(id: string)

Returns the acceleration of the vehicle (float)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
acceleration number the acceleration of the vehicle

GetVehicleBrakingForce

number GetVehicleBrakingForce(id: string)

Returns the braking force of the vehicle (float)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
brakingForce number the braking force of the vehicle

GetVehicleFlippedDirection

boolean GetVehicleFlippedDirection(id: string)

Returns true if the vehicle is flipped (facing left), otherwise returns false

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
isFlipped boolean true if the vehicle is flipped (facing left), otherwise returns false

GetVehicleGameState

string GetVehicleGameState(id: string)

Returns string representing vehicle game state: "REACHED_FLAG", "UNDERWATER", "DRIVING", "WAITING_START", "WAITING_CHECKPOINT", or "WAITING_BUILD_MODE"

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
state string string representing vehicle game state: "REACHED_FLAG", "UNDERWATER", "DRIVING", "WAITING_START", "WAITING_CHECKPOINT", or "WAITING_BUILD_MODE"

GetVehicleHorsepower

number GetVehicleHorsepower(id: string)

Returns the horsepower of the vehicle (float)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
horsepower number the horsepower of the vehicle

GetVehicleIdleDownhill

boolean GetVehicleIdleDownhill(id: string)

Returns true if the idle downhill setting is true on the vehicle, otherwise returns false

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
idleDownhill boolean true if the idle downhill setting is true on the vehicle, otherwise returns false

GetVehicleIds

integer[] GetVehicleIds()

Returns a list of id strings for all currently active vehicles (List)

Return Type Comment
vehicleIds integer[] list of id strings for all currently active vehicles

GetVehicleMass

number GetVehicleMass(id: string)

Returns the mass of the vehicle (float)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
mass number the mass of the vehicle

GetVehiclePosition

Vec3 GetVehiclePosition(id: string)

Returns the current game world position of the vehicle as a float list of length 3 (corresponding to x, y, and z position) (List)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()

GetVehicleRotation

Vec3 GetVehicleRotation(id: string)

Returns the current game world rotation of the vehicle as a float list of length 3 (corresponding to x, y, and z euler angles) (List)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
rotation Vec3 the current game world rotation of the vehicle as a float list of length 3

GetVehicleSpeed

number GetVehicleSpeed(id: string)

Returns the current speed of the vehicle (float)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
speed number the current speed of the vehicle

GetVehicleTargetSpeed

number GetVehicleTargetSpeed(id: string)

Returns the target speed of the vehicle (float)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
Return Type Comment
targetSpeed number the target speed of the vehicle

SetVehicleAcceleration

nil SetVehicleAcceleration(id: string, value: number)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
value number is the desired acceleration of the vehicle

SetVehicleBrakingForce

nil SetVehicleBrakingForce(id: string, value: number)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
value number is the desired braking force of the vehicle

SetVehicleFlippedDirection

nil SetVehicleFlippedDirection(id: string, value: boolean)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
value boolean is the desired flipped direction of the vehicle

SetVehicleHorsepower

nil SetVehicleHorsepower(id: string, value: number)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
value number is the desired horsepower of the vehicle

SetVehicleIdleDownhill

nil SetVehicleIdleDownhill(id: string, value: boolean)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
value boolean is the desired idle downhill setting of the vehicle

SetVehicleMass

nil SetVehicleMass(id: string, value: number)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
value number is the desired mass of the vehicle

SetVehicleTargetSpeed

nil SetVehicleTargetSpeed(id: string, value: number)

Argument Type Comment
id string is the id of the vehicle, usually obtained from GetVehicleIds()
value number is the desired target speed of the vehicle

Workshop Campaign functions

WorkshopCampaignAddLevelToWorld

nil WorkshopCampaignAddLevelToWorld(worldName: string, levelId: string)

Adds the given level to the given world.

Argument Type Comment
worldName string is the display name of the world.
levelId string is the steam workshop item id of the level, should be a long set of numbers.

WorkshopCampaignAddTutorialLevelToWorld

nil WorkshopCampaignAddTutorialLevelToWorld(worldName: string, levelId: string)

Adds the given level to the given world, and puts a T in front of the name to indicate it is a tutorial.

Argument Type Comment
worldName string is the display name of the world.
levelId string is the steam workshop item id of the level, should be a long set of numbers.

WorkshopCampaignCreate

nil WorkshopCampaignCreate(winMessage: string)

Creates a workshop campaign, must happen before WorkshopCampaignCreateWorld or WorkshopCampaignAddLevelToWorld.

Argument Type Comment
winMessage string is the message shown to the player when they beat all the levels in the campaign.

WorkshopCampaignCreateWorld

nil WorkshopCampaignCreateWorld(worldName: string, prefix: string, subtitle: string, worldDifficulty: integer)

Creates a world for a workshop campaign, must happen after WorkshopCampaignCreate

Argument Type Comment
worldName string is the display name of the world.
prefix string is the two or three character prefix that appears before the level name.
subtitle string is the world type, like Generic or Custom Shapes.
worldDifficulty integer is the difficulty rating of the world, from 1 to 5.

WorkshopCampaignSetWorldIcon

nil WorkshopCampaignSetWorldIcon(worldName: string, iconSpritePath: string, selectedIconSpritePath: string)

Sets the icon of the created world to the given sprites.

Argument Type Comment
worldName string is the display name of the world.
iconSpritePath string is the path to the sprite for this world when it is unselected.
selectedIconSpritePath string is the path to the sprite for this world when it is selected.

WorkshopCampaignSetWorldIconByPrefix

nil WorkshopCampaignSetWorldIconByPrefix(worldName: string, prefix: string)

Sets the icon of the created world to the icon from the normal campaign mode world that matches the prefix.

Argument Type Comment
worldName string is the display name of the world.
prefix string is the two or three character prefix that appears before the level name.

WorkshopCampaignSetWorldIconPosition

nil WorkshopCampaignSetWorldIconPosition(worldName: string, iconPositionX: number, iconPositionY: number)

Sets the position of the icon for the given world. Note that the X value is clamped between -125 and 125, and the Y value is clamped between -210 and 210.

Argument Type Comment
worldName string is the display name of the world.
iconPositionX number is the X position of the icon.
iconPositionY number is the Y position of the icon.