Abstract
Throughout the tutorial chapters of the book, we used many internally defined functions in the systems of the mods. While the purpose and function of these mods were explained in context, you may find official use and documentation for each of them useful in your own projects. In this chapter, you will find the official engine API documentation used by GIANTS Software engineers. Please note that you can find the latest version of the documentation on the GDN:
You have full access to this open access chapter, Download chapter PDF
Throughout the tutorial chapters of the book, we used many internally defined functions in the systems of the mods. While the purpose and function of these mods were explained in context, you may find official use and documentation for each of them useful in your own projects. In this chapter, you will find the official engine API documentation used by GIANTS Software engineers. Please note that you can find the latest version of the documentation on the GDN:
Debugging
Prints given arguments to the console.
Arguments
any arg1 – [optional]
any arg2 – [optional]
any arg3 – [optional]
any arg4 – [optional]
any arg5 – [optional]
any arg6 – [optional]
any arg7 – [optional]
any arg8 – [optional]
printCallstack
Prints the current application callstack.
Position, Orientation, and Size
getWorldTranslation
Gets world translation of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
float x – x position in entityId’s world space.
float y – y position in entityId’s world space.
float z – z position in entityId’s world space.
setWorldTranslation
Sets world translation of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x position in entityId’s world space.
float y – y position in entityId’s world space.
float z – z position in entityId’s world space.
setTranslation
Sets local translation of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x position in entityId’s local space.
float y – y position in entityId’s local space.
float z – z position in entityId’s local space.
getTranslation
Gets local translation of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
float x – x position in entityId’s local space.
float y – y position in entityId’s local space.
float z – z position in entityId’s local space.
worldToLocal
Converts the world position into entityId’s local space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x position in entityId’s world space.
float y – y position in entityId’s world space.
float z – z position in entityId’s world space.
Returns
float x – x position in entityId’s local space.
float y – y position in entityId’s local space.
float z – z position in entityId’s local space.
localToWorld
Converts the given position from entityId’s local space to world space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x position in entityId’s local space.
float y – y position in entityId’s local space.
float z – z position in entityId’s local space.
Returns
float x – x position in entityId’s world space.
float y – y position in entityId’s world space.
float z – z position in entityId’s world space.
localToLocal
Converts the given position from entityId’s local space to targetEntityId’s local space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
integer targetEntityId – ID of the target entity (transformGroup, shape, etc.).
float x – x position in entityId’s local space.
float y – y position in entityId’s local space.
float z – z position in entityId’s local space.
Returns
float x – x position in targetEntityId’s local space.
float y – y position in targetEntityId’s local space.
float z – z position in targetEntityId’s local space.
setRotation
Sets the local rotation of the given transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
float x – x rotation (radians) in entityId’s local space.
float y – y rotation (radians) in entityId’s local space.
float z – z rotation (radians) in entityId’s local space.
getRotation
Gets the local rotation of the given transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
float x – x rotation (radians) in entityId’s local space.
float y – y rotation (radians) in entityId’s local space.
float z – z rotation (radians) in entityId’s local space.
getWorldRotation
Gets world rotation of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
float x – x rotation (radians) in entityId’s world space.
float y – y rotation (radians) in entityId’s world space.
float z – z rotation (radians) in entityId’s world space.
setWorldRotation
Sets world rotation of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x rotation (radians) in entityId’s world space.
float y – y rotation (radians) in entityId’s world space.
float z – z rotation (radians) in entityId’s world space.
localRotationToWorld
Converts the rotation in entityId’s local space to world space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x rotation (radians) in entityId’s local space.
float y – y rotation (radians) in entityId’s local space.
float z – z rotation (radians) in entityId’s local space.
Returns
float x – x rotation (radians) in entityId’s world space.
float y – y rotation (radians) in entityId’s world space.
float z – z rotation (radians) in entityId’s world space.
worldRotationToLocal
Converts the world rotation into entityId’s local space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x rotation (radians) in entityId’s world space.
float y – y rotation (radians) in entityId’s world space.
float z – z rotation (radians) in entityId’s world space.
Returns
float x – x rotation (radians) in entityId’s local space.
float y – y rotation (radians) in entityId’s local space.
float z – z rotation (radians) in entityId’s local space.
worldDirectionToLocal
Converts a world direction vector into entityId’s local space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x component of direction vector in world space.
float y – y component of direction vector in world space.
float z – z component of direction vector in world space.
Returns
float x – x component of direction vector in entityId’s local space.
float y – y component of direction vector in entityId’s local space.
float z – z component of direction vector in entityId’s local space.
localDirectionToLocal
Converts a direction vector in entityId’s local space to targetEntityId’s local space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
integer targetEntityId – ID of the target entity (transformGroup, shape, etc.).
float x – x component of direction vector in entityId’s local space.
float y – y component of direction vector in entityId’s local space.
float z – z component of direction vector in entityId’s local space.
Returns
float x – x component of direction vector in targetEntityId’s local space.
float y – y component of direction vector in targetEntityId’s local space.
float z – z component of direction vector in targetEntityId’s local space.
localDirectionToWorld
Converts a local space direction vector into world space.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x component of direction vector in entityId’s local space.
float y – y component of direction vector in entityId’s local space.
float z – z component of direction vector in entityId’s local space.
Returns
float x – x component of direction vector in world space.
float y – y component of direction vector in world space.
float z – z component of direction vector in world space.
setDirection
Sets the direction of an object; the positive Z axis points toward the given direction. The Y axis lies in the direction-up-plane.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x component of direction vector (z axis) in entityId’s local space.
float y – y component of direction vector (z axis) in entityId’s local space.
float z – z component of direction vector (z axis) in entityId’s local space.
float upX – x component of up vector (y axis) in entityId’s local space.
float upY – y component of up vector (y axis) in entityId’s local space.
float upZ – z component of up vector (y axis) in entityId’s local space.
setScale
Sets scale of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
float x – x scale of entityId in local space.
float y – y scale of entityId in local space.
float z – z scale of entityId in local space.
getScale
Gets the scale of a transform object.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
float x – x scale of entityId in local space.
float y – y scale of entityId in local space.
float z – z scale of entityId in local space.
Entities
clone
Clones a scenegraph object (transformGroup, shape, etc.).
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
boolean groupUnderParent – If the cloned entity should be parented to the same parent.
boolean callOnCreate – If script callbacks (onCreate) should be called.
boolean addPhysics – If the cloned entity should be added to physics.
Returns
integer clonedEntityId – ID of the cloned entity (transformGroup, shape, etc.).
createTransformGroup
Creates a transform group.
Arguments
string transformName – Name of the transform group.
Returns
integer entityId – ID of the transformGroup entity.
setName
Sets the name of an entity.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
string transformName – Name of the object.
getName
Gets the name of an entity.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
string objectName – Name of the object.
setVisibility
Sets transform object visibility.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
boolean visibility – Visibility state of the object.
getVisibility
Gets transform object visibility.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
boolean visibility – Visibility state of the object.
setUserAttribute
Sets user attribute value.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
string attributeName – Name of the attribute.
string typeName – Name of the attribute type (Float, Integer, String).
any value – Value of the attribute.
getUserAttribute
Gets the user attribute value.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
string attributeName – Name of the attribute.
Returns
any attributeValue – Value of the attribute.
getHasClassId
Gets if an entity has the given class id.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
integer classId – The class ID. See ClassIds enum.
Returns
boolean hasClassId – True if the entity has the classId.
ClassIds Enum
ClassIds.OVERLAY
ClassIds.IMAGE_OVERLAY
ClassIds.VIDEO_OVERLAY
ClassIds.TERRAIN_TRANSFORM_GROUP
ClassIds.FOLIAGE_TRANSFORM_GROUP
ClassIds.TERRAIN_DETAIL_TRANSFORM_GROUP
ClassIds.TERRAIN_LAYER_TRANSFORM_GROUP
ClassIds.SHAPE
ClassIds.LIGHT_SOURCE
ClassIds.AUDIO_SOURCE
ClassIds.CAMERA
ClassIds.NAVIGATION_MESH
ClassIds.MESH_SPLIT_SHAPE
ClassIds.GEOMETRY
ClassIds.TRANSFORM_GROUP
ClassIds.PARTICLE_SYSTEM
ClassIds.SPLINE
Entity Relations
link
Links a transform object to another transform object.
Arguments
integer parentEntityId – ID of the parent entity (transformGroup, shape, etc.).
integer childEntityId – ID of the child entity (transformGroup, shape, etc.).
integer index – [optional] Position of the child among children.
unlink
Unlinks a transform object from the parent.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
getParent
Gets the entity id of the parent.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
integer parentEntityId – ID of the parent entity (transformGroup, shape, etc.).
getChild
Gets the id of the first child that matches the given name.
Arguments
integer entityId – ID of the child entity (transformGroup, shape, etc.).
string childName – Name of the child.
Returns
integer childEntityId – ID of the child entity (transformGroup, shape, etc.).
getChildAt
Gets the entity id at a given child index.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
integer childIndex – Index (zero based) of the child
Returns
integer childEntityId – ID of the child entity (transformGroup, shape, etc.).
getNumOfChildren
Gets the number of children.
Arguments
integer entityId – ID of the entity (transformGroup, shape, etc.).
Returns
integer numOfChildren – Number of children.
getRootNode
Gets the root node of the scenegraph.
Returns
integer entityId – ID of the entity (transformGroup, shape, etc.).
Camera
getCamera
Gets the active camera.
Returns
integer entityId – ID of the camera entity.
setCamera
Sets the active camera.
Arguments
integer entityId – ID of the camera entity.
I3D
loadI3DFile
Loads the I3D file (blocking).
Arguments
string filename – The I3D file name.
boolean addPhysics – If entities should be added to physics.
boolean callOnCreate – If script callbacks (onCreate) should be called.
boolean verbose – [optional] If the loading info should be displayed in the log file.
Returns
integer rootNodeId – ID of the root entity (transformGroup, shape, etc.) of the loaded file.
integer failedReason – The failed reason. See LoadI3dFailedReason enum.
loadSharedI3DFile
Loads a shared I3D file (blocking). If the file is already in cache, the system clones the objects. If another shared stream request is still pending for the same i3d, the call blocks until this request is finished.
Arguments
string filename – The I3D file name.
boolean addPhysics – If the objects should be added to physics.
boolean callOnCreate – If script callbacks (onCreate) should be called.
boolean verbose – [optional] If the loading info should be displayed in the log file.
Returns
integer rootNodeId – ID of the root entity (transformGroup, shape, etc.) of the loaded file.
integer requestId – The ID of the load request (used to cancel or release files).
integer failedReason – A specific reason why the loading failed.
LoadI3dFailedReason Enum
LoadI3DFailedReason.NONE
LoadI3DFailedReason.CANCELLED
LoadI3DFailedReason.FILE_NOT_FOUND
LoadI3DFailedReason.UNKNOWN
streamI3DFile
Streams the I3D file (non-blocking).
Arguments
string filename – The I3D file name.
string callbackFunctionName – [optional] Callback function if the loading is done.
object target – [optional] Target object of the callback function.
object args – [optional] Arguments for callback function.
boolean addPhysics – If the objects should be added to physics.
boolean callOnCreate – If script callbacks (onCreate) should be called.
boolean verbose – [optional] If the loading info should be displayed in the log file.
Returns
integer requestId – Request id for streaming, used to cancel the stream request.
cancelStreamI3DFile
Cancels streaming the I3D file.
Arguments
integer requestId – Request id of the streamed load request.
streamSharedI3DFile
Streams the shared I3D file (non-blocking). Can call the callback in the same callstack when the file is already loaded.
Arguments
string filename – The I3D file name.
string callbackFunctionName – [optional] Callback function if the loading is done.
object target – [optional] Target object of the callback function.
object args – [optional] Arguments for the callback function.
boolean addPhysics – If the objects should be added to physics.
boolean callOnCreate – If script callbacks (onCreate) should be called.
boolean verbose – [optional] If the loading info should be displayed in the log file.
Returns
integer requestId – Request id for streaming, used to cancel the stream request.
releaseSharedI3DFile
Reduces the ref count of the given shared i3d. Must be called for every successfull loadSharedI3DFile and streamSharedI3DFile call to avoid memory leaks.
Arguments
integer requestId – Stream I3D request ID.
integer warnIfInvalid – [optional, default=false] Print a warning if the request ID is invalid.
Physics
getRigidBodyType
Gets the rigid body type of a physics shape entity.
Arguments
integer entityId – ID of the physics shape entity.
Returns
integer RIGID_BODY_TYPE – Type of the rigid body (see RigidBodyType Enum).
RigidBodyType Enum
RigidBodyType.NONE
RigidBodyType.STATIC
RigidBodyType.DYNAMIC
RigidBodyType.KINEMATIC
setRigidBodyType
Sets the rigid body type of a physics shape entity.
Arguments
integer entityId – ID of the physics shape entity.
integer rigidBodyType – Type of the rigid body (see RigidBody Enum).
getCenterOfMass
Gets the center of mass of a physics shape entity.
Arguments
integer entityId – ID of the physics shape entity.
Returns
float x – x position of the center of mass in entityId’s local space.
float y – y position of the center of mass in entityId’s local space.
float z – z position of the center of mass in entityId’s local space.
setCenterOfMass
Sets the center of mass of a physics shape entity.
Arguments
integer entityId – ID of the physics shape entity.
float x – x position of the center of mass in entityId’s local space.
float y – y position of the center of mass in entityId’s local space.
float z – z position of the center of mass in entityId’s local space.
getMass
Gets the mass of a physics shape entity.
Arguments
integer entityId – ID of the physics shape entity.
Returns
float mass – Mass in tons.
setMass
Sets the mass of a physics shape entity.
Arguments
integer entityId – ID of the physics shape entity.
float mass – Mass in tons.
raycastAll
Raycast objects.
Arguments
float x – x position in world space.
float y – y position in world space.
float z – z position in world space.
float nx – x component of direction vector in world space.
float ny – y component of direction vector in world space.
float nz – z component of direction vector in world space.
string raycastFunctionCallback – See raycastCallback documentation.
float maxDistance – Max distance of the raycast.
object targetObject – [optional] Target object of the callback function.
integer collisionMask – [optional] The collision mask of the raycast.
boolean generateNormal – [optional, default=false] If a normal should be generated for each hit.
boolean async – [optional, default=false] If true, callback will be called in the next frame and calculations will be done in a background thread. In Async mode, the return value has no meaning, and if no hit is found, the callback is called once with 0 ids.
Returns
integer numShapes – numShapes if async is false.
raycastClosest
Raycast closest object.
Arguments
float x – x position in world space.
float y – y position in world space.
float z – z position in world space.
float nx – x component of direction vector in world space.
float ny – y component of direction vector in world space.
float nz – z component of direction vector in world space.
string raycastFunctionCallback – See raycastCallback documentation.
float maxDistance – Max distance of the raycast.
object targetObject – [optional] Target object of the callback function.
integer collisionMask – [optional] The collision mask of the raycast.
boolean generateNormal – [optional, default=false] If a normal should be generated for each hit.
boolean async – [optional, default=false] If true, callback will be called in the next frame and calculations will be done in a background thread. In Async mode, the return value has no meaning, and if no hit is found, the callback is called once with 0 ids.
Returns
integer numShapes – numShapes if async is false.
raycastCallback
A valid raycastCallback function requires the parameters of the following header. The function itself can be renamed as the developer desires:
callbackFunctionName(integer actorEntityId, float x, float y, float z, float distance, float nx, float ny, float nz, integer subShapeIndex, integer shapeId, boolean isLast)
overlapBox
Checks for possible overlaps in the defined box.
Arguments
float x – x position in world space.
float y – y position in world space.
float z – z position in world space.
float rx – x rotation (radians) in world space.
float ry – y rotation (radians) in world space.
float rz – z rotation (radians) in world space.
float ex – x half dimension (meters) in world space.
float ey – y half dimension (meters) in world space.
float ez – z half dimension (meters) in world space.
string overlapFunctionCallback – See overlapFunctionCallback documentation.
object targetObject – [optional] Target object of the callback function.
integer collisionMask – [optional, default=ALL_BITS]
boolean includeDynamics – [optional, default=true] If dynamic objects should be included.
boolean includeStatics – [optional, default=true] If static objects should be included.
boolean exactTest – [optional, default=false] If an exact test should be done instead of a simple AABB collision check.
boolean async – [optional, default=false] If true, callback will be called in the next frame and calculations will be done in a background thread.
Returns
integer numShapes
overlapSphere
Overlap sphere objects.
Arguments
float x – x position in world space.
float y – y position in world space.
float z – z position in world space.
float radius – Sphere radius in meters.
string overlapFunctionCallback – See overlapFunctionCallback documentation.
object targetObject – [optional] Target object of the callback function.
integer collisionMask – [optional, default=ALL_BITS]
boolean includeDynamics – [optional, default=true] If dynamic objects should be included.
boolean includeStatics – [optional, default=true] If static objects should be included.
boolean exactTest – [optional, default=false] If an exact test should be done instead of a simple AABB collision check.
boolean async – [optional, default=false] If true, callback will be called in the next frame and calculations will be done in a background thread.
Returns
integer numShapes
overlapCallback
A valid overlapCallback function requires the parameters of the following header. The function itself can be renamed as the developer desires:
callbackFunctionName(integer entityId, integer subShapeIndex, boolean isLastAsync (only set if async was true))
Network
streamReadBool
Reads a bool value from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
boolean value – A bool value.
streamReadFloat32
Reads a 32-bit float from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
float value – 32-bit float value.
streamReadInt16
Reads a 16-bit signed integer from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
integer value – 16-bit signed integer value.
streamReadInt32
Reads a 32-bit signed integer from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
integer value – 32-bit signed integer value.
streamReadInt8
Reads an 8-bit signed integer from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
integer value – 8-bit signed integer value.
streamReadIntN
Reads an N-bit signed integer from the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer numberofBits – Number of bits used to send the value.
Returns
integer value – N-bit signed integer value.
streamReadString
Reads a string from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
string value – A piece of text.
streamReadUInt16
Reads a 16-bit unsigned integer from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
integer value – 16-bit unsigned integer value.
streamReadUInt8
Reads an 8-bit unsigned integer from the network stream.
Arguments
integer streamId – ID of the network stream entity.
Returns
integer value – 8-bit unsigned integer value.
streamReadUIntN
Reads an N-bit unsigned integer from the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer numberOfBits – Number of bits used to send the value.
Returns
integer value – N-bit unsigned integer value.
streamWriteBool
Writes a bool value to the network stream.
Arguments
integer streamId – ID of the network stream entity.
boolean value – A bool value.
Returns
boolean value – The sent bool value.
streamWriteFloat32
Writes a 32-bit float to the network stream.
Arguments
integer streamId – ID of the network stream entity.
float value – 32-bit float value.
streamWriteInt16
Writes a 16-bit signed integer to the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer value – 16-bit signed integer value.
streamWriteInt32
Writes a 32-bit signed integer to the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer value – 32-bit signed integer value.
streamWriteInt8
Writes an 8-bit signed integer to the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer value – 8-bit signed integer value.
streamWriteIntN
Writes an N-bit signed integer to the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer value – N-bit signed integer value.
integer numberOfBits – Number of bits used to send the value.
streamWriteString
Writes a string to the network stream.
Arguments
integer streamId – ID of the network stream entity.
string value – A piece of text.
streamWriteUInt16
Writes a 16-bit unsigned integer to the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer value – 16-bit unsigned integer value.
streamWriteUInt8
Writes an 8-bit unsigned integer to the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer value – 8-bit unsigned integer value.
streamWriteUIntN
Writes an N-bit unsigned integer to the network stream.
Arguments
integer streamId – ID of the network stream entity.
integer value – N-bit unsigned integer value.
integer numberofBits – Number of bits used to send the value.
Author information
Authors and Affiliations
Rights and permissions
Open Access This chapter is licensed under the terms of the Creative Commons Attribution 4.0 International License (http://creativecommons.org/licenses/by/4.0/), which permits use, sharing, adaptation, distribution and reproduction in any medium or format, as long as you give appropriate credit to the original author(s) and the source, provide a link to the Creative Commons license and indicate if changes were made.
The images or other third party material in this chapter are included in the chapter's Creative Commons license, unless indicated otherwise in a credit line to the material. If material is not included in the chapter's Creative Commons license and your intended use is not permitted by statutory regulation or exceeds the permitted use, you will need to obtain permission directly from the copyright holder.
Copyright information
© 2024 The Author(s)
About this chapter
Cite this chapter
Brumbaugh, Z., Leithner, M. (2024). Documentation and Appendix. In: Scripting Farming Simulator with Lua. Apress, Berkeley, CA. https://doi.org/10.1007/979-8-8688-0060-3_12
Download citation
DOI: https://doi.org/10.1007/979-8-8688-0060-3_12
Published:
Publisher Name: Apress, Berkeley, CA
Print ISBN: 979-8-8688-0059-7
Online ISBN: 979-8-8688-0060-3
eBook Packages: Professional and Applied ComputingProfessional and Applied Computing (R0)Apress Access Books