Content/Documentation/ScriptingAPI-Documentation.md
This is a reference and explanation of Lua scripting features in Wicked Engine.
Scripting in Wicked Engine is powered by Lua, meaning that the user can make use of the syntax and features of the flexible and powerful Lua language. Apart from the common features, certain engine features are also available to use. You can load lua script files and execute them, or the engine scripting console (also known as the BackLog) can also be used to execute single line scripts (or you can execute file scripts by the dofile command here). Upon startup, the engine will try to load a startup script file named startup.lua in the root directory of the application. If not found, an error message will be thrown followed by the normal execution by the program. In the startup file, you can specify any startup logic, for example loading content or anything.
The Backlog is mapped to the HOME button on the keyboard. This will bring down an interface where lua commands can be entered with the keyboard. The ENTER button will execute the command that was entered. Pressing the HOME button again will exit the Backlog.
Tip: You can inspect any object's functionality by calling getprops(YourObject) on them (where YourObject is the object which is to be inspected). The result will be displayed on the BackLog.
Tags used in this documentation:
This section describes the common tools for scripting which are not necessarily engine features.
These are some helpers to aid in debugging:
The scripting API provides functions for the developer to manipulate engine behaviour or query it for information.
The scripting console of the engine. Input text with the keyboard, run the input with the RETURN key. The script errors are also displayed here. The scripting API provides some functions which manipulate the BackLog. These functions are in he global scope:
This is the graphics renderer, which is also responsible for managing the scene graph which consists of keeping track of parent-child relationships between the scene hierarchy, updating the world, animating armatures. You can use the Renderer with the following functions, all of which are in the global scope:
Render images on the screen.
Specify Sprite properties, like position, size, etc.
[constructor]ImageParams(opt float width, opt float height)
[constructor]ImageParams(float posX, float posY, float width, opt float height)
GetPos() : Vector result
GetSize() : Vector result
GetPivot() : Vector result
GetColor() : Vector result
GetOpacity() : float result
GetFade() : float result
GetRotation() : float result
GetMipLevel() : float result
GetTexOffset() : Vector result
GetTexOffset2() : Vector result
GetBorderSoften() : float result
GetDrawRect() : Vector result
GetDrawRect2() : Vector result
IsDrawRectEnabled() : bool result
IsDrawRect2Enabled() : bool result
IsMirrorEnabled() : bool result
IsBackgroundEnabled() : bool result
IsDistortionMaskEnabled() : bool result
SetPos(Vector pos)
SetSize(Vector size)
SetPivot(Vector value)
SetColor(Vector value)
SetOpacity(float opacity)
SetFade(float fade)
SetStencil(int stencilMode,stencilRef)
SetStencilRefMode(int stencilrefmode)
SetBlendMode(int blendMode)
SetQuality(int quality)
SetSampleMode(int sampleMode)
SetRotation(float rotation)
SetMipLevel(float mipLevel)
SetTexOffset()
SetTexOffset2()
SetBorderSoften(float alpha)
EnableDrawRect(Vector value)
EnableDrawRect2(Vector value)
DisableDrawRect()
DisableDrawRect2()
EnableMirror()
DisableMirror()
EnableBackground()
DisableBackground()
EnableDistortionMask()
DisableDistortionMask()
SetMaskAlphaRange(float start, end)
GetMaskAlphaRange() : float start, end
SetAngularSoftnessDirection(Vector value)
SetAngularSoftnessInnerAngle(float value)
SetAngularSoftnessOuterAngle(float value)
EnableAngularSoftnessDoubleSided()
EnableAngularSoftnessInverse()
DisableAngularSoftnessDoubleSided()
DisableAngularSoftnessInverse()
[outer]STENCILMODE_DISABLED : int
[outer]STENCILMODE_EQUAL : int
[outer]STENCILMODE_LESS : int
[outer]STENCILMODE_LESSEQUAL : int
[outer]STENCILMODE_GREATER : int
[outer]STENCILMODE_GREATEREQUAL : int
[outer]STENCILMODE_NOT : int
[outer]STENCILREFMODE_ENGINE : int
[outer]STENCILREFMODE_USER : int
[outer]STENCILREFMODE_ALL : int
[outer]SAMPLEMODE_CLAMP : int
[outer]SAMPLEMODE_WRAP : int
[outer]SAMPLEMODE_MIRROR : int
[outer]QUALITY_NEAREST : int
[outer]QUALITY_LINEAR : int
[outer]QUALITY_ANISOTROPIC : int
[outer]QUALITY_BICUBIC : int
[outer]BLENDMODE_OPAQUE : int
[outer]BLENDMODE_ALPHA : int
[outer]BLENDMODE_PREMULTIPLIED : int
[outer]BLENDMODE_ADDITIVE : int
Animate Sprites easily with this helper.
Move texture continuously along the sprite.
Animate sprite frame by frame.
Gives you the ability to render text with a custom font.
A texture image data.
GradientType = {
Linear = 0,
Circular = 1,
Angular = 2,
}
GradientFlags = {
None = 0,
Inverse = 1 << 0,
Smoothstep = 1 << 1,
PerlinNoise = 1 << 2,
R16Unorm = 1 << 3,
}
Example texture creation:
texture = texturehelper.CreateGradientTexture(
GradientType.Circular, -- gradient type
256, 256, -- resolution of the texture
Vector(0.5, 0.5), Vector(0.5, 0), -- start and end uv coordinates will specify the gradient direction and extents
GradientFlags.Inverse | GradientFlags.Smoothstep | GradientFlags.PerlinNoise, -- modifier flags bitwise combination
"rrr1", -- for each channel, you can specify one of the following characters: 0, 1, r, g, b, a, x, y, z, w (lower or upper case)
2, -- perlin noise scale
123, -- perlin noise seed
6, -- perlin noise octaves
0.8 -- perlin noise persistence
)
texture.Save("gradient.png") -- you can save it to file
sprite.SetTexture(texture) -- you can set it to a sprite
material.SetTexture(TextureSlot.BASECOLORMAP, texture) -- you can set it to a material
Loads and plays an audio files.
An audio file. Can be instanced several times via SoundInstance.
An audio file instance that can be played. Note: after modifying parameters of the SoundInstance, the SoundInstance will need to be recreated from a specified sound
Describes the relation between a sound instance and a listener in a 3D world
The video interface consists of two types of objects: Video and VideoInstance. Note: these are the underlying objects that VideoComponents use in the scene, to easily set videos to materials or lights, look at the VideoComponent object that you can use with the scene's entity component system.
The Video object stores the compressed video data in a GPU buffer
The VideoInstance object is responsible to decode the video frames and output them to textures. One Video can be decoded with multiple VideoInstances to display frames of the video at different timings. Normally yout would use one VideoInstance for a video, unless you want to show the video multiple times at once at different locations.
The submix types group sound instances together to be controlled together
The reverb types are built in presets that can mimic a specific kind of environment
A four component floating point vector. Provides efficient calculations with SIMD support.
A four by four matrix, efficient calculations with SIMD support.
The Async object can be used for tracking or Wait for completion of functions that are running on background threads.
Manipulate the 3D scene with these components.
An entity is just an int value (int in LUA and uint32 in C++) and works as a handle to retrieve associated components
The scene holds components. Entity handles can be used to retrieve associated components through the scene.
[constructor]Scene() : Scene result -- creates a custom scene
[outer]GetScene() : Scene result -- returns the global scene
[outer]GetCamera() : Camera result -- returns the global camera
[outer]LoadModel(string fileName, opt Matrix transform) : int rootEntity -- Load Model from file. returns a root entity that everything in this model is attached to
[outer]LoadModel(Scene scene, string fileName, opt Matrix transform) : int rootEntity -- Load Model from file into specified scene. returns a root entity that everything in this model is attached to
[deprecated][outer]PICK_OPAQUE : uint -- deprecated, you can use FILTER_ enums instead
[deprecated][outer]PICK_TRANSPARENT : uint -- deprecated, you can use FILTER_ enums instead
[deprecated][outer]PICK_WATER : uint -- deprecated, you can use FILTER_ enums instead
[deprecated][outer]Pick(Ray ray, opt uint filterMask = ~0, opt uint layerMask = ~0, opt Scene scene = GetScene(), uint lod = 0) : int entity, Vector position,normal, float distance -- Perform ray-picking in the scene. pickType is a bitmask specifying object types to check against. layerMask is a bitmask specifying which layers to check against. Scene parameter is optional and will use the global scene if not specified. (deprecated, you can use the scene's Intersects() function instead)
[deprecated][outer]SceneIntersectSphere(Sphere sphere, opt uint filterMask = ~0, opt uint layerMask = ~0, opt Scene scene = GetScene(), opt uint lod = 0) : int entity, Vector position,normal, float distance -- Perform ray-picking in the scene. pickType is a bitmask specifying object types to check against. layerMask is a bitmask specifying which layers to check against. Scene parameter is optional and will use the global scene if not specified. (deprecated, you can use the scene's Intersects() function instead)
[deprecated][outer]SceneIntersectCapsule(Capsule capsule, opt uint filterMask = ~0, opt uint layerMask = ~0, opt Scene scene = GetScene(), opt uint lod = 0) : int entity, Vector position,normal, float distance -- Perform ray-picking in the scene. pickType is a bitmask specifying object types to check against. layerMask is a bitmask specifying which layers to check against. Scene parameter is optional and will use the global scene if not specified. (deprecated, you can use the scene's Intersects() function instead)
[outer]FILTER_NONE : uint -- include nothing
[outer]FILTER_OPAQUE : uint -- include opaque meshes
[outer]FILTER_TRANSPARENT : uint -- include transparent meshes
[outer]FILTER_WATER : uint -- include water meshes
[outer]FILTER_NAVIGATION_MESH : uint -- include navigation meshes
[outer]FILTER_OBJECT_ALL : uint -- include all objects, meshes
[outer]FILTER_COLLIDER : uint -- include colliders
[outer]FILTER_RAGDOLL : uint -- include ragdoll body parts
[outer]FILTER_ALL : uint -- include everything
Intersects(Ray|Sphere|Capsule primitive, opt uint filterMask = ~0u, opt uint layerMask = ~0u, opt uint lod = 0) : int entity, Vector position,normal, float distance, Vector velocity, int subsetIndex, Matrix orientation, Vector uv, HumanoidBone humanoid_bone -- intersects a primitive with the scene and returns collision parameters. If humanoid_bone is not HumanoidBone.Count then the intersection is a ragdoll, and entity refers to the humanoid entity
IntersectsFirst(Ray primitive, opt uint filterMask = ~0u, opt uint layerMask = ~0u, opt uint lod = 0) : bool -- intersects a primitive with the scene and returns true immediately on intersection, false if there was no intersection. This can be faster for occlusion check than regular Intersects that searches for closest intersection.
IntersectsAll(Ray|Sphere|Capsule primitive, opt uint filterMask = ~0u, opt uint layerMask = ~0u, opt uint lod = 0) results[] -- intersects the scene with a primitive and returns array of results. In case of Ray, RayIntersectionResult will be returned, for Sphere and Capsule SphereIntersectionResult will be returned
Update() -- updates the scene and every entity and component inside the scene
Clear() -- deletes every entity and component inside the scene
Merge(Scene other) -- moves contents from an other scene into this one. The other scene will be empty after this operation (contents are moved, not copied)
UpdateHierarchy() -- updates the full scene hierarchy system. Useful if you modified for example a parent transform and children immediately need up to date result in the script
Instantiate(Scene prefab, opt bool attached = false) : Entity -- Duplicates everything in the prefab scene into the current scene. If attached parameter is set to true then everything in prefab scene will be attached to a common root entity (with TransformComponent and LayerComponent) and the function will return that root entity.
CreateEntity() : int entity -- creates an empty entity and returns it
FindAllEntities() : table[entities] -- returns a table with all the entities present in the given scene
Entity_FindByName(string value, opt Entity ancestor = INVALID_ENTITY) : int entity -- returns an entity ID if it exists, and INVALID_ENTITY otherwise. You can specify an ancestor entity if you only want to find entities that are descendants of ancestor entity
Entity_Remove(Entity entity, bool recursive = true, bool keep_sorted = false) -- removes an entity and deletes all its components if it exists. If recursive is specified, then all children will be removed as well (enabled by default). If keep_sorted is specified, then component order will be kept (disabled by default, slower)
Entity_Remove_Async(Async async, Entity entity, bool recursive = true, bool keep_sorted = false) -- Same as Entity_Remove, but it runs on a background thread, status can be tracked by the Async object that you provide
Entity_Duplicate(Entity entity) : int entity -- duplicates all of an entity's components and creates a new entity with them. Returns the clone entity handle
Entity_IsDescendant(Entity entity, Entity ancestor) : bool result -- Check whether entity is a descendant of ancestor. Returns true if entity is in the hierarchy tree of ancestor, false otherwise
Component_CreateName(Entity entity) : NameComponent result -- attach a name component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateLayer(Entity entity) : LayerComponent result -- attach a layer component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateTransform(Entity entity) : TransformComponent result -- attach a transform component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateCamera(Entity entity) : CameraComponent result -- attach a camera component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateLight(Entity entity) : LightComponent result -- attach a light component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateObject(Entity entity) : ObjectComponent result -- attach an object component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateInverseKinematics(Entity entity) : InverseKinematicsComponent result -- attach an IK component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateSpring(Entity entity) : SpringComponent result -- attach a spring component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateScript(Entity entity) : ScriptComponent result -- attach a script component to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateRigidBodyPhysics(Entity entity) : RigidBodyPhysicsComponent result -- attach a RigidBodyPhysicsComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateSoftBodyPhysics(Entity entity) : SoftBodyPhysicsComponent result -- attach a SoftBodyPhysicsComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateForceField(Entity entity) : ForceFieldComponent result -- attach a ForceFieldComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateWeather(Entity entity) : WeatherComponent result -- attach a WeatherComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateSound(Entity entity) : SoundComponent result -- attach a SoundComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateVideo(Entity entity) : VideoComponent result -- attach a VideoComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateCollider(Entity entity) : ColliderComponent result -- attach a ColliderComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateExpression(Entity entity) : ExpressionComponent result -- attach a ExpressionComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateHumanoid(Entity entity) : HumanoidComponent result -- attach a HumanoidComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateDecal(Entity entity) : DecalComponent result -- attach a DecalComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateSprite(Entity entity) : Sprite result -- attach a Sprite to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateFont(Entity entity) : SpriteFont result -- attach a SpriteFont to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateVoxelGrid(Entity entity) : VoxelGrid result -- attach a VoxelGrid to an entity. The returned component is associated with the entity and can be manipulated
Component_CreateMetadata(Entity entity) : MetadataComponent result -- attach a MetadataComponent to an entity. The returned component is associated with the entity and can be manipulated
Component_GetName(Entity entity) : NameComponent? result -- query the name component of the entity (if exists)
Component_GetLayer(Entity entity) : LayerComponent? result -- query the layer component of the entity (if exists)
Component_GetTransform(Entity entity) : TransformComponent? result -- query the transform component of the entity (if exists)
Component_GetCamera(Entity entity) : CameraComponent? result -- query the camera component of the entity (if exists)
Component_GetAnimation(Entity entity) : AnimationComponent? result -- query the animation component of the entity (if exists)
Component_GetMaterial(Entity entity) : MaterialComponent? result -- query the material component of the entity (if exists)
Component_GetEmitter(Entity entity) : EmitterComponent? result -- query the emitter component of the entity (if exists)
Component_GetLight(Entity entity) : LightComponent? result -- query the light component of the entity (if exists)
Component_GetObject(Entity entity) : ObjectComponent? result -- query the object component of the entity (if exists)
Component_GetInverseKinematics(Entity entity) : InverseKinematicsComponent? result -- query the IK component of the entity (if exists)
Component_GetSpring(Entity entity) : SpringComponent? result -- query the spring component of the entity (if exists)
Component_GetScript(Entity entity) : ScriptComponent? result -- query the script component of the entity (if exists)
Component_GetRigidBodyPhysics(Entity entity) : RigidBodyPhysicsComponent? result -- query the RigidBodyPhysicsComponent of the entity (if exists)
Component_GetSoftBodyPhysics(Entity entity) : SoftBodyPhysicsComponent? result -- query the SoftBodyPhysicsComponent of the entity (if exists)
Component_GetForceField(Entity entity) : ForceFieldComponent? result -- query the ForceFieldComponent of the entity (if exists)
Component_GetWeather(Entity entity) : WeatherComponent? result -- query the WeatherComponent of the entity (if exists)
Component_GetSound(Entity entity) : SoundComponent? result -- query the SoundComponent of the entity (if exists)
Component_GetVideo(Entity entity) : VideoComponent? result -- query the VideoComponent of the entity (if exists)
Component_GetCollider(Entity entity) : ColliderComponent? result -- query the ColliderComponent of the entity (if exists)
Component_GetExpression(Entity entity) : ExpressionComponent? result -- query the ExpressionComponent of the entity (if exists)
Component_GetHumanoid(Entity entity) : HumanoidComponent? result -- query the HumanoidComponent of the entity (if exists)
Component_GetDecal(Entity entity) : DecalComponent? result -- query the DecalComponent of the entity (if exists)
Component_GetSprite(Entity entity) : Sprite? result -- query the Sprite of the entity (if exists)
Component_GetVoxelGrid(Entity entity) : VoxelGrid? result -- query the VoxelGrid of the entity (if exists)
Component_GetMetadata(Entity entity) : MetadataComponent? result -- query the MetadataComponent of the entity (if exists)
Component_GetNameArray() : NameComponent[] result -- returns the array of all components of this type
Component_GetLayerArray() : LayerComponent[] result -- returns the array of all components of this type
Component_GetTransformArray() : TransformComponent[] result -- returns the array of all components of this type
Component_GetCameraArray() : CameraComponent[] result -- returns the array of all components of this type
Component_GetAnimationArray() : AnimationComponent[] result -- returns the array of all components of this type
Component_GetMaterialArray() : MaterialComponent[] result -- returns the array of all components of this type
Component_GetEmitterArray() : EmitterComponent[] result -- returns the array of all components of this type
Component_GetLightArray() : LightComponent[] result -- returns the array of all components of this type
Component_GetObjectArray() : ObjectComponent[] result -- returns the array of all components of this type
Component_GetMeshArray() : MeshComponent[] result -- returns the array of all components of this type
Component_GetInverseKinematicsArray() : InverseKinematicsComponent[] result -- returns the array of all components of this type
Component_GetSpringArray() : SpringComponent[] result -- returns the array of all components of this type
Component_GetScriptArray() : ScriptComponent[] result -- returns the array of all components of this type
Component_GetRigidBodyPhysicsArray() : RigidBodyPhysicsComponent[] result -- returns the array of all components of this type
Component_GetSoftBodyPhysicsArray() : SoftBodyPhysicsComponent[] result -- returns the array of all components of this type
Component_GetForceFieldArray() : ForceFieldComponent[] result -- returns the array of all components of this type
Component_GetWeatherArray() : WeatherComponent[] result -- returns the array of all components of this type
Component_GetSoundArray() : SoundComponent[] result -- returns the array of all components of this type
Component_GetVideoArray() : VideoComponent[] result -- returns the array of all components of this type
Component_GetColliderArray() : ColliderComponent[] result -- returns the array of all components of this type
Component_GetExpressionArray() : ExpressionComponent[] result -- returns the array of all components of this type
Component_GetHumanoidArray() : HumanoidComponent[] result -- returns the array of all components of this type
Component_GetDecalArray() : DecalComponent[] result -- returns the array of all components of this type
Component_GetSpriteArray() : Sprite[] result -- returns the array of all components of this type
Component_GetFontArray() : SpriteFont[] result -- returns the array of all components of this type
Component_GetVoxelGridArray() : VoxelGrid[] result -- returns the array of all components of this type
Component_GetMetadataArray() : MetadataComponent[] result -- returns the array of all components of this type
Entity_GetNameArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetLayerArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetTransformArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetCameraArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetAnimationArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetAnimationDataArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetMaterialArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetEmitterArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetLightArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetObjectArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetMeshArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetInverseKinematicsArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetSpringArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetScriptArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetRigidBodyPhysicsArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetSoftBodyPhysicsArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetForceFieldArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetWeatherArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetSoundArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetVideoArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetColliderArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetExpressionArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetHumanoidArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetDecalArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetSpriteArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetFontArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetVoxelGridArray() : Entity[] result -- returns the array of all entities that have this component type
Entity_GetMetadataArray() : Entity[] result -- returns the array of all entities that have this component type
Component_RemoveName(Entity entity) -- remove the name component of the entity (if exists)
Component_RemoveLayer(Entity entity) -- remove the layer component of the entity (if exists)
Component_RemoveTransform(Entity entity) -- remove the transform component of the entity (if exists)
Component_RemoveCamera(Entity entity) -- remove the camera component of the entity (if exists)
Component_RemoveAnimation(Entity entity) -- remove the animation component of the entity (if exists)
Component_RemoveAnimationData(Entity entity)
Component_RemoveMaterial(Entity entity) -- remove the material component of the entity (if exists)
Component_RemoveEmitter(Entity entity) -- remove the emitter component of the entity (if exists)
Component_RemoveLight(Entity entity) -- remove the light component of the entity (if exists)
Component_RemoveObject(Entity entity) -- remove the object component of the entity (if exists)
Component_RemoveInverseKinematics(Entity entity) -- remove the IK component of the entity (if exists)
Component_RemoveSpring(Entity entity) -- remove the spring component of the entity (if exists)
Component_RemoveScript(Entity entity) -- remove the script component of the entity (if exists)
Component_RemoveRigidBodyPhysics(Entity entity) -- remove the RigidBodyPhysicsComponent of the entity (if exists)
Component_RemoveSoftBodyPhysics(Entity entity) -- remove the SoftBodyPhysicsComponent of the entity (if exists)
Component_RemoveForceField(Entity entity) -- remove the ForceFieldComponent of the entity (if exists)
Component_RemoveWeather(Entity entity) -- remove the WeatherComponent of the entity (if exists)
Component_RemoveSound(Entity entity) -- remove the SoundComponent of the entity (if exists)
Component_RemoveVideo(Entity entity) -- remove the VideoComponent of the entity (if exists)
Component_RemoveCollider(Entity entity) -- remove the ColliderComponent of the entity (if exists)
Component_RemoveExpression(Entity entity) -- remove the ExpressionComponent of the entity (if exists)
Component_RemoveHumanoid(Entity entity) -- remove the HumanoidComponent of the entity (if exists)
Component_RemoveDecal(Entity entity) -- remove the DecalComponent of the entity (if exists)
Component_RemoveSprite(Entity entity) -- remove the Sprite of the entity (if exists)
Component_RemoveFont(Entity entity) -- remove the SpriteFont of the entity (if exists)
Component_RemoveVoxelGrid(Entity entity) -- remove the VoxelGrid of the entity (if exists)
Component_RemoveMetadata(Entity entity) -- remove the MetadataComponent of the entity (if exists)
Component_Attach(Entity entity,parent, opt bool child_already_in_local_space = false) -- attaches entity to parent (adds a hierarchy component to entity). From now on, entity will inherit certain properties from parent, such as transform (entity will move with parent) or layer (entity's layer will be a sublayer of parent's layer). If child_already_in_local_space is false, then child will be transformed into parent's local space, if true, it will be used as-is.
Component_Detach(Entity entity) -- detaches entity from parent (if hierarchycomponent exists for it). Restores entity's original layer, and applies current transformation to entity
Component_DetachChildren(Entity parent) -- detaches all children from parent, as if calling Component_Detach for all of its children
GetBounds() : AABB result -- returns an AABB fully containing objects in the scene. Only valid after scene has been updated.
GetWeather() : WeatherComponent
SetWeather(WeatherComponent weather)
RetargetAnimation(Entity dst, src, bool bake_data) : Entity entity -- Retargets an animation from a Humanoid to an other Humanoid such that the new animation will play back on the destination humanoid. dst : destination humanoid that the animation will be fit onto src : the animation to copy, it should already target humanoid bones. bake_data : if true, the retargeted data will be baked into a new animation data. If false, it will reuse the source animation data without creating a new one and retargeting will be applied at runtime on every Update. Returns entity ID of the new animation or INVALID_ENTITY if retargeting was not successful
ResetPose(Entity entity) -- resets the pose of the specified entity to bind pose. The bind pose is taken from the bind matrices of bones of an ArmatureComponent. If the entity does not have an armature, then it will find the child armatures of the entity.
GetOceanPosAt(Vector worldPosition) -- returns the approximate position on the ocean surface seen from a position in world space. If current weather doesn't have ocean enabled, returns the world position itself. The result position is approximate because it involves reading back from GPU to the CPU, so the result can be delayed compared to the current GPU simulation. Note that the input position to this function will be taken on the XZ plane and modified by the displacement map's XZ value, and the Y (vertical) position will be taken from the ocean water height and displacement map only.
VoxelizeObject(int objectIndex, VoxelGrid voxelgrid, opt bool subtract = false, opt int lod = 0) -- voxelizes a single object into the voxel grid. Subtract parameter controls whether the voxels are added (true) or removed (false). Lod argument selects object's level of detail
VoxelizeScene(VoxelGrid voxelgrid, opt bool subtract = false, opt uint filterMask = ~0u, opt uint layerMask = ~0u, opt uint lod = 0) -- voxelizes all entities in the scene which intersect the voxel grid volume and match the filterMask and layerMask. Subtract parameter controls whether the voxels are added (true) or removed (false). Lod argument selects object's level of detail
FixupNans() -- maintenance utility to help fix Nan issues in TransformComponents. Transforms containing nans will be cleared and renamed with _nanfix postfix
Result of one hit in scene.IntersectsAll
Result of one hit in scene.IntersectsAll
Holds a string that can more easily identify an entity to humans than an entity ID.
An integer mask that can be used to group entities together for certain operations such as: picking, rendering, etc.
Describes an orientation in 3D space.
.X element specifies the horizontal, the .Y element specifies the vertical shape.UpdateCamera() should be used after this to apply the value.Vector, relative to the camera position, and also perpendicular to the up direction. UpdateCamera() should be used after this to apply the value. This value will also be set if using the TransformCamera() function, from the transform's rotation.Vector, relative to the camera position, and also perpendicular to the look direction. UpdateCamera() should be used after this to apply the value. This value will also be set if using the TransformCamera() function, from the transform's rotation.TextureSlot = {
BASECOLORMAP = 0,
NORMALMAP = 1,
SURFACEMAP = 2,
EMISSIVEMAP = 3,
DISPLACEMENTMAP = 4,
OCCLUSIONMAP = 5,
TRANSMISSIONMAP = 6,
SHEENCOLORMAP = 7,
SHEENROUGHNESSMAP = 8,
CLEARCOATMAP = 9,
CLEARCOATROUGHNESSMAP = 10,
CLEARCOATNORMALMAP = 11,
SPECULARMAP = 12,
}
Describes an Inverse Kinematics effector.
Enables jiggle effect on transforms such as bones for example.
A lua script bound to an entity
Describes a Rigid Body Physics object.
SetKinematic(true) as it will be moved continuously with the physics update rate)Describes a Soft Body Physics object.
Mass : float
Friction : float
Restitution : float
VertexRadius : float -- how much distance vertices keep from other physics bodies
SetDetail(float value) -- Set how much detail the soft body simulation has compared to the graphics mesh. Setting this will rebuild the soft body, so individual physics vertex settings will be lost.
GetDetail() : float
SetDisableDeactivation(bool value)
IsDisableDeactivation() : bool
SetWindEnabled(bool value)
IsWindEnabled() : bool
CreateFromMesh(MeshComponent mesh)
Describes a Force Field effector.
Describes a Weather
Describes a Sound object.
Describes a video object
Describes a Collider object.
Shape : int -- Shape of the collider
Radius : float
Offset : Vector
Tail : Vector
SetCPUEnabled(bool value)
SetGPUEnabled(bool value)
GetCapsule() : Capsule
GetSphere() : Sphere
[outer] ColliderShape = { Sphere = 0, Capsule = 1, Plane = 2, }
[outer] ExpressionPreset = {
Happy = 0,
Angry = 1,
Sad = 2,
Relaxed = 3,
Surprised = 4,
Aa = 5,
Ih = 6,
Ou = 7,
Ee = 8,
Oh = 9,
Blink = 10,
BlinkLeft = 11,
BlinkRight = 12,
LookUp = 13,
LookDown = 14,
LookLeft = 15,
LookRight = 16,
Neutral = 17,
}
[outer] ExpressionOverride = {
None = 0,
Block = 1,
Blend = 2,
}
[outer] HumanoidBone = {
Hips = 0, -- included in ragdoll
Spine = 1, -- included in ragdoll
Chest = 2,
UpperChest = 3,
Neck = 4, -- included in ragdoll
Head = 5, -- included in ragdoll if Neck is not available
LeftEye = 6,
RightEye = 7,
Jaw = 8,
LeftUpperLeg = 9, -- included in ragdoll
LeftLowerLeg = 10, -- included in ragdoll
LeftFoot = 11, -- included in ragdoll
LeftToes = 12,
RightUpperLeg = 13, -- included in ragdoll
RightLowerLeg = 14, -- included in ragdoll
RightFoot = 15, -- included in ragdoll
RightToes = 16,
LeftShoulder = 17,
LeftUpperArm = 18, -- included in ragdoll
LeftLowerArm = 19, -- included in ragdoll
LeftHand = 20,
RightShoulder = 21,
RightUpperArm = 22, -- included in ragdoll
RightLowerArm = 23, -- included in ragdoll
RightHand = 24,
LeftThumbMetacarpal = 25,
LeftThumbProximal = 26,
LeftThumbDistal = 27,
LeftIndexProximal = 28,
LeftIndexIntermediate = 29,
LeftIndexDistal = 30,
LeftMiddleProximal = 31,
LeftMiddleIntermediate = 32,
LeftMiddleDistal = 33,
LeftRingProximal = 34,
LeftRingIntermediate = 35,
LeftRingDistal = 36,
LeftLittleProximal = 37,
LeftLittleIntermediate = 38,
LeftLittleDistal = 39,
RightThumbMetacarpal = 40,
RightThumbProximal = 41,
RightThumbDistal = 42,
RightIndexIntermediate = 43,
RightIndexDistal = 44,
RightIndexProximal = 45,
RightMiddleProximal = 46,
RightMiddleIntermediate = 47,
RightMiddleDistal = 48,
RightRingProximal = 49,
RightRingIntermediate = 50,
RightRingDistal = 51,
RightLittleProximal = 52,
RightLittleIntermediate = 53,
RightLittleDistal = 54,
Count = 55
}
The decal component is a textured sticker that can be put down onto meshes. Most of the properties can be controlled through an attached TransformComponent and MaterialComponent.
The metadata component can store and retrieve an arbitrary amount of named user values for an entity. It is possible to use the same name for multiple of different value types, but one value can not have multiple entries with the same name.
HasBool(string name) : bool
HasInt(string name) : bool
HasFloat(string name) : bool
HasString(string name) : bool
GetPreset() : int
GetBool(string name) : bool
GetInt(string name) : int
GetFloat(string name) : float
GetString(string name) : string
SetPreset(int preset)
SetBool(string name, bool value)
SetInt(string name, int value)
SetFloat(string name, float value)
SetString(string name, string value)
[outer] MetadataPreset = { Custom = 0, Waypoint = 1, Player = 2, Enemy = 3, NPC = 4, Pickup = 5, Vehicle = 6, }
Implementation of basic character controller features such as movement in the scene, inverse kinematics for legs, swimming, water ripples, etc. Note that CharacterComponent is NOT using physics, but a custom character logic. The character will collide with other characters, objects that are tagged as Navmesh, and colliders that are tagged with CPU enabled.
SetActive(bool value) -- Enable/disable character processing (enabled by default)
IsActive() : bool -- Returns whether the character processing is active or not
Move(Vector value) -- Move the character in a direction continuously. The given vector doesn't need to be normalized, the length of it corresponds to the movement amount. The character will be moved the next time the scene is updated. The movement will be blocked by objects tagged as navigation mesh and CPU colliders. If this entity has a layer component, the layer will be used to ensure that the character doesn't collide with that layer.
Strafe(Vector value) -- Similar to Move, but relative to the facing direction.
Jump(float amount) -- Jump upwards by an amount. The jump will be executed in the next scene update, with collisions.
Turn(Vector value) -- Turn towards a direction continuously.
Lean(float value) -- Lean sideways, negative values mean left, positive values mean right
Shake(float horizontal, opt float vertical = 0, opt float frequency = 100, opt float decay = 10) -- Apply shaking to the character. horizontal, vertical: movement amount in directions; frequency: speed of movement; decay: speed of slowing down
AddAnimation(Entity entity) -- Adds animation for tracking blending state. The simple animation blending will perform blend-out for each animation except the currenttly active one
PlayAnimation(Entity entity) -- Play the animation. This will be blended in as primary animation, others will be belnded out.
StopAnimation() -- stops current animation
SetAnimationAmount(float value) -- Set target blend amount of current animation
GetAnimationAmount() : float -- returns target blend amount of current animation
GetAnimationTimer() : float -- returns the timer of current animation
IsAnimationEnded() : bool --returns true if the current animation is ended, false otherwise
SetGroundFriction(float value) -- velocity multiplier when moving on ground, default: 0.92
SetWaterFriction(float value) -- velocity multiplier when swimming in water, default: 0.9
SetSlopeThreshold(float value) -- Slope detection threshold, default: 0.2
SetLeaningLimit(float value) -- Leaning min/max clamping, default: 0.12
SetTurningSpeed(float value) -- Turning smoothing speed when using Turn(), default: 10.0
SetFixedUpdateFPS(float value) -- Frame rate of simulation, default: 120
SetGravity(float value) -- Gravity value, default: -30
SetWaterVerticalOffset(float value) -- vertical offset to keep from water. Useful if character is too submerged in the swimming state
SetHealth(int value) -- Set health of the character
SetWidth(float value) -- Set the horizontal size of the character capsule (same as capsule radius)
SetHeight(float value) -- Set the vertical size of the character capsule (same as capsule height)
SetScale(float value) -- Apply an overall scale on the character
SetPosition(Vector value) -- Set current position immediately (teleport)
SetVelocity(Vector value) -- Set current velocity immediately
SetFacing(Vector value) -- Set the facing direction of the character
SetRelativeOffset(Vector value) -- Apply a relative offset (relative to facing direction)
SetFootPlacementEnabled(bool value) --Enable/disable foot placement with inverse kinematics
SetCharacterToCharacterCollisionDisabled(bool value) -- Set whether character collision with other characters is disabled or not for this character (default: false)
GetHealth() : int -- Get the current health
GetWidth() : float -- Get the horizontal size of the character capsule (same as capsule radius)
GetHeight() : float -- Get the vertical size of the character capsule (same as capsule height)
GetScale() : float -- Get the overall scale of the character
GetPosition() : Vector -- Retrieve the current position without interpolation (this is the raw value from fixed timestep update)
GetPositionInterpolated() : Vector -- Retrieve the current position with interpolation (this is the position that is rendered)
GetVelocity() : Vector -- Get current velocity
GetMovement() : Vector -- Get current movement direction
IsGrounded() : bool -- returns whether the character is currently standing on ground or not
IsWallIntersect() : bool -- returns whether the character is currently intersecting a wall or not
IsSwimming() : bool -- returns whether the character is currently swimming or not
IsFootPlacementEnabled() : bool -- Returns whether foot placement with inverse kinematics is currently enabled or not
IsCharacterToCharacterCollisionDisabled() -- returns whether character collision with other characters is disabled or not for this character (default: false)
GetCapsule() : Capsule -- returns the capsule representing the character
GetFacing() : Vector -- returns the immediate facing of the character
GetFacingSmoothed() : Vector -- returns the smoothed facing of the character
GetRelativeOffset() : Vector -- returns the relative offset (relative to facing direction)
GetLeaning() : float -- returns immediate leaning amount
GetLeaningSmoothed() : float -- returns smoothed leaning amount
GetFootOffset() : float -- returns vertical offset that accounts for character's position after foot placements
SetPathGoal(Vector goal, VoxelGrid voxelgrid) -- Set the goal for path finding, it will be processed the next time the scene is updated. You can get the results by accessing the pathquery object of the character with GetPathQuery().
GetPathQuery() : PathQuery -- returns the PathQuery object of this character
This is used to describe a drawable area
<b>This section must only be used from standalone lua scripts, and must not be used from a ScriptComponent.</b> This is because ScriptComponent is always running inside scene.Update(), and paths can not be switched at that time safely. On the other hand, a standalone lua script can define its own update logic and render path and cahnge application behaviour.
This is the main entry point and manages the lifetime of the application.
FadeType = { FadeToColor, CrossFade, }
A RenderPath is a high level system that represents a part of the whole application. It is responsible to handle high level rendering and logic flow. A render path can be for example a loading screen, a menu screen, or primary game screen, etc.
It can hold Sprites and SpriteFonts and can sort them by layers, update and render them.
This is the default scene render path. It inherits functions from RenderPath2D, so it can render a 2D overlay.
FSR2_Preset = {
Quality = 0, -- 1.5x scaling, -1.58 sampler LOD bias
Balanced = 1, -- 1.7x scaling, -1.76 sampler LOD bias
Performance = 2, -- 2.0x scaling, -2.0 sampler LOD bias
Ultra_Performance = 3, -- 3.0x scaling, -2.58 sampler LOD bias
}
Tonemap = {
Reinhard = 0,
ACES = 1,
}
It is a RenderPath2D but one that internally manages resource loading and can display information about the process. It inherits functions from RenderPath2D.
BackgroundMode = {
Fill, -- fill the whole screen, will cut off parts of the image if aspects don't match
Fit, -- fit the image completely inside the screen, will result in black bars on screen if aspects don't match
Stretch -- fill the whole screen, and stretch the image if needed
}
A ray is defined by an origin Vector and a normalized direction Vector. It can be used to intersect with other primitives or the scene
vector.PlaneFromPointNormal(Vector point, normal) or vector.PlaneFromPoints(Vector a,b,c) to construct a plane.Axis Aligned Bounding Box. Can be intersected with other primitives.
Sphere defined by center Vector and radius. Can be intersected with other primitives.
It's like two spheres connected by a cylinder. Base and Tip are the two endpoints, radius is the cylinder's radius.
Query input devices
BUTTON_NONE) if nothing is pressed, or the first appropriate button code otherwiseDescribes controller feedback such as touch and LED color which can be replayed on a controller
Describes a touch contact point
Helpers to check mouse wheel scrolling like buttons:
Generic button codes:
Helpers to check analog sticks and triggers like buttons:
Xbox button codes:
Playstation button codes:
CharacterGroundStates of the character physicsCharacterGroundStates = {
OnGround = 0, -- Character is on the ground and can move freely.
OnSteepGround = 1, -- Character is on a slope that is too steep and can't climb up any further. The caller should start applying downward velocity if sliding from the slope is desired.
NotSupported = 2, -- Character is touching an object, but is not supported by it and should fall. The GetGroundXXX functions will return information about the touched object.
InAir = 3, -- Character is in the air and is not touching anything.
}
Intersects(Scene scene, Ray ray) : Entity entity, Vector position,normal, Entity humanoid_ragdoll_entity, HumanoidBone humanoid_bone, Vector position_local -- Performns physics scene intersection for closest hit with a ray
DriveVehicle(RigidBodyPhysicsComponent rigidbody, opt float forward = 0, opt float right = 0, opt float brake = 0, opt float handbrake = 0) -- set input from driver: forward and right values are values between -1 and 1 to indicate reverse/forward or left/right. brake and handbrake (handbrake = back brake for motorcycles) are values between 0 and 1.
GetVehicleForwardVelocity(RigidBodyPhysicsComponent rigidbody) : float -- Signed velocity amount in forward direction
PickDrag(Scene scene, Ray, ray, PickDragOperation op, opt ConstraintType constraint, opt float break_distance = FLT_MAX) -- pick and drag physics objects such as ragdolls and rigid bodies.
ConstraintType = {
Fixed = 0,
Point = 1
}
Tracks a physics pick drag operation. Use it with phyiscs.PickDrag() function. When using this object first time to PickDrag, the operation will be started and the operation will end when you call Finish() or when the object is destroyed
Path finding operations can be made by using a voxel grid and path queries. The voxel grid can store spatial information about a scene, or a part of the scene, while the path query manages the path finding result from a point to a different point within the voxel grid.