#include <LUA_API_Bone.h>

Public Member Functions
float3	getLocalPosition (int entityID, string boneName)
	Get the local position of a bone relative to its parent. More...

float3	getWorldPosition (int entityID, string boneName)
	Get the world position of a bone relative to the world space zero. More...

float4	getLocalOrientation (int entityID, string boneName)
	Get the local orientation of a bone relative to its parent. More...

float4	getWorldOrientation (int entityID, string boneName)
	Get the world orientation of a bone relative to the world space zero. More...

float3	getScale (int entityID, string boneName)
	Get the scale of the bone. More...

void	setLocalPosition (int entityID, string boneName, float posX, float posY, float posZ)
	Set the local position of a bone. This is a position relative to its parent bone. More...

void	setWorldPosition (int entityID, string boneName, float posX, float posY, float posZ)
	Set the world space position of a bone. This is a position relative to world space zero. More...

void	setLocalOrientation (int entityID, string boneName, float OrientW, float OrientX, float OrientY, float OrientZ)
	Set the local orientation of a bone relative to its parent bone. More...

void	setWorldOrientation (int entityID, string boneName, float OrientW, float OrientX, float OrientY, float OrientZ)
	Set the world orientation of a bone relative to world space zero. More...

void	setScale (int entityID, string boneName, float scaleX, float scaleY, float scaleZ)
	Set the scale of a bone, useful for exploding character limbs lol. More...

void	pitch (int entityID, string boneName, float degree)
	pitch a bone locally by a certain degree. is an acculative effect. Keep adding 1 to rotate continuously. More...

void	roll (int entityID, string boneName, float degree)
	roll a bone locally by a certain degree. is an acculative effect. Keep adding 1 to rotate continuously. More...

void	yaw (int entityID, string boneName, float degree)
	yaw a bone locally by a certain degree. is an acculative effect. Keep adding 1 to rotate continuously. More...

void	scale (int entityID, string boneName, float scaleX, float scaleY, float scaleZ)
	scale a bone accumulatively. Unlike bone.setScale(), this is added to the previous scale rather than setting a scale. More...

float3	getInitialPosition (int entityID, string boneName)
	Get the initial position of a bone based on the original bind pose. More...

float4	getInitialOrientation (int entityID, string boneName)
	Get the initial rotation quaternion of a bone based on the original bind pose. More...

float3	getInitialScale (int entityID, string boneName)
	Get the initial scale quaternion of a bone based on the original bind pose. More...

void	printBones (int entityID)
	Calling this function and passing the entity id as an argument will print all bone names associated with the skeleton. This is useful when you dont know what the names are. Recommended to place in the onInit() to always know the bones. Then remove the line when releasing your game. More...

int	getHandle (int entityID, string boneName)
	This function is needed in order to retrieve the bone handle index for the anim.setBlendMaskEntry() and anim.getBlendMaskEntry(). More...

void	setManuallyControlled (int entityID, string boneName, int state)
	Set whether to override control to the user for this bone. This allows you to program the position, rotation and scale of the bone manually. More...

void	storeAnimTracks (int entityID, string boneName)
	Using this function you can store all the animation tracks and keyframes so you can destroy the bones animations to control it manually. More...

void	destroyAnimTracks (int entityID, string boneName)
	Using this function you can destroy all the animation tracks and keyframes on a bone to manually control it movement. If you do not call storeAnimTracks() first, then this function will call it for you :D. More...

void	restoreAnimTracks (int entityID, string boneName)
	Using this function you can restore all the animation tracks and keyframes on a bone to replace your code. Once set back and you have disabled manual control on a bone, then it will carry on animating with the rest of the mesh. More...

float3	getPositionOffset (int entityID, string boneName)
	Get a world space position offset from a bone, this is useful for putting a sword in a hand, or raycasting from a bones location with an offset. More...

Detailed Description

This area covers Entity Bone Controls. Use as bone.function()

Member Function Documentation

void bone::destroyAnimTracks	(	int	entityID,
		string	boneName
	)

Using this function you can destroy all the animation tracks and keyframes on a bone to manually control it movement. If you do not call storeAnimTracks() first, then this function will call it for you :D.

NOTE: It is important to manually restore the animation tracks since this is an advanced feature.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to destroy all animation tracks on.

The following is a Small Example on how to use this function:

function onInit(objID)
    bone.destroyAnimTracks(obj, "Bip001_Head"); -- destroy to empty all tracks.
    bone.setManuallyControlled(obj, "Bip001_Head", 1);
end

function onUpdate(td)
    bone.yaw(obj, "Bip001_Head", 1);
end

function onStop()
    bone.restoreAnimTracks(obj, "Bip001_Head"); -- replace all anim tracks, for next time play.
end

int bone::getHandle	(	int	entityID,
		string	boneName
	)

This function is needed in order to retrieve the bone handle index for the anim.setBlendMaskEntry() and anim.getBlendMaskEntry().

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.

Returns: boneHandleID: This is the internal handle to the bone inside the engine.

The following is a Small Example on how to use this function:

function onInit(objID)
    boneHnd = bone.getHandle(obj, "Bip001_Head"); 
    bone.setBlendMaskEntry(obj, "myAnimation", boneHnd, 0.5); -- apply animation on this bone by 50% all the time.
end

float4 bone::getInitialOrientation	(	int	entityID,
		string	boneName
	)

Get the initial rotation quaternion of a bone based on the original bind pose.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.

Returns: initRotW: The initial Rotation(Quaternion) W of the bone.; initRotX: The initial Rotation(Quaternion) X of the bone.; initRotY: The initial Rotation(Quaternion) Y of the bone.; initRotZ: The initial Rotation(Quaternion) Z of the bone.

The following is a Small Example on how to use this function:

function onInit(objID)
    initialRot = newType.vec4(bone.getInitialOrientation(obj, "Bip001_Head")); 
end

float3 bone::getInitialPosition	(	int	entityID,
		string	boneName
	)

Get the initial position of a bone based on the original bind pose.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.

Returns: initPosX: The initial Position X of the bone.; initPosY: The initial Position Y of the bone.; initPosZ: The initial Position Z of the bone.

The following is a Small Example on how to use this function:

function onInit(objID)
    initialPos = newType.vec3(bone.getInitialPosition(obj, "Bip001_Head")); 
end

float3 bone::getInitialScale	(	int	entityID,
		string	boneName
	)

Get the initial scale quaternion of a bone based on the original bind pose.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.

Returns: initScaleX: The initial Scale X of the bone.; initScaleY: The initial Scale Y of the bone.; initScaleZ: The initial Scale Z of the bone.

The following is a Small Example on how to use this function:

function onInit(objID)
    initialScale = newType.vec3(bone.getInitialScale(obj, "Bip001_Head")); 
end

float4 bone::getLocalOrientation	(	int	entityID,
		string	boneName
	)

Get the local orientation of a bone relative to its parent.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.

Returns: QuatW : Returns the Quaternion W Component.; QuatX : Returns the Quaternion X Component.; QuatY : Returns the Quaternion Y Component.; QuatZ : Returns the Quaternion Z Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    localOrientation = newType.vec4(bone.getLocalOrientation(obj, "Bip001_Head")); 
end

float3 bone::getLocalPosition	(	int	entityID,
		string	boneName
	)

Get the local position of a bone relative to its parent.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the position.

Returns: PosX : Returns the Position X Component.; PosY : Returns the Position Y Component.; PosZ : Returns the Position Z Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    x,y,z = bone.getLocalPosition(obj, "Bip001_Head"); 
end

float3 bone::getPositionOffset	(	int	entityID,
		string	boneName
	)

Get a world space position offset from a bone, this is useful for putting a sword in a hand, or raycasting from a bones location with an offset.

It is always a good idea to put bones in places you want to get an exact position from, but this is always a good second option.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to destroy all animation tracks on.

Returns: offsetX : The offsets X Axis.; offsetY : The offsets Y Axis.; offsetZ : The offsets Z Axis.

The following is a Small Example on how to use this function:

function onUpdate(td)
    offset = newType.vec3(bone.getPositionOffset(obj, "Bip001_R_Hand"));
    bonePos = newType.vec3(bone.getWorldPosition(obj, "Bip001_R_Hand"));

    entity.setPosition(swordID, bonePos.x + offset.x,
                                bonePos.y + offset.y,
                                bonePos.z + offset.z);
end

float3 bone::getScale	(	int	entityID,
		string	boneName
	)

Get the scale of the bone.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.

Returns: ScaleX : Returns the Scale X Component.; ScaleY : Returns the Scale Y Component.; ScaleZ : Returns the Scale Z Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    scale = newType.vec3(bone.getScale(obj, "Bip001_Head")); 
end

float4 bone::getWorldOrientation	(	int	entityID,
		string	boneName
	)

Get the world orientation of a bone relative to the world space zero.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.

Returns: QuatW : Returns the Quaternion W Component.; QuatX : Returns the Quaternion X Component.; QuatY : Returns the Quaternion Y Component.; QuatZ : Returns the Quaternion Z Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    localOrientation = newType.vec4(bone.getWorldOrientation(obj, "Bip001_Head")); 
end

float3 bone::getWorldPosition	(	int	entityID,
		string	boneName
	)

Get the world position of a bone relative to the world space zero.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the position.

Returns: PosX : Returns the Position X Component.; PosY : Returns the Position Y Component.; PosZ : Returns the Position Z Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    position = newType.vec3(bone.getWorldPosition(obj, "Bip001_Head")); 
end

void bone::pitch	(	int	entityID,
		string	boneName,
		float	degree
	)

pitch a bone locally by a certain degree. is an acculative effect. Keep adding 1 to rotate continuously.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
degree	: The angle in degrees to pitch the bone.

The following is a Small Example on how to use this function:

function onInit(objID)
    bone.pitch(obj, "Bip001_Head", 1); 
end

void bone::printBones ( int entityID )

Calling this function and passing the entity id as an argument will print all bone names associated with the skeleton. This is useful when you dont know what the names are. Recommended to place in the onInit() to always know the bones. Then remove the line when releasing your game.

Parameters

entityID : The entity in the scene you wish to edit their bones.

The following is a Small Example on how to use this function:

function onInit(objID)
    printBones(obj);
end

void bone::restoreAnimTracks	(	int	entityID,
		string	boneName
	)

Using this function you can restore all the animation tracks and keyframes on a bone to replace your code. Once set back and you have disabled manual control on a bone, then it will carry on animating with the rest of the mesh.

This must be called in the onStop() otherwise you may experience weird issues in editor or next play.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to destroy all animation tracks on.

The following is a Small Example on how to use this function:

function onInit(objID)
    bone.storeAnimTracks(obj, "Bip001_Head");
    bone.destroyAnimTracks(obj, "Bip001_Head"); -- destroy to empty all tracks.
    bone.setManuallyControlled(obj, "Bip001_Head", 1);
end

function onUpdate(td)
    bone.yaw(obj, "Bip001_Head", 1);
end

function onStop()
    bone.restoreAnimTracks(obj, "Bip001_Head"); -- replace all anim tracks, for next time play.
end

void bone::roll	(	int	entityID,
		string	boneName,
		float	degree
	)

roll a bone locally by a certain degree. is an acculative effect. Keep adding 1 to rotate continuously.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
degree	: The angle in degrees to roll the bone.

The following is a Small Example on how to use this function:

function onInit(objID)
    bone.roll(obj, "Bip001_Head", 1); 
end

void bone::scale	(	int	entityID,
		string	boneName,
		float	scaleX,
		float	scaleY,
		float	scaleZ
	)

scale a bone accumulatively. Unlike bone.setScale(), this is added to the previous scale rather than setting a scale.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
scaleX	The acculative X Axis to scale by.
scaleY	The acculative X Axis to scale by.
scaleZ	The acculative X Axis to scale by.

The following is a Small Example on how to use this function:

function onUpdate(td)
    bone.scale(obj, "Bip001_Head", 1.2, 1.2, 1.2); 
end

void bone::setLocalOrientation	(	int	entityID,
		string	boneName,
		float	OrientW,
		float	OrientX,
		float	OrientY,
		float	OrientZ
	)

Set the local orientation of a bone relative to its parent bone.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
OrientW	: Set the Rotation(Quaternion) W Axis Component.
OrientX	: Set the Rotation(Quaternion) X Axis Component.
OrientY	: Set the Rotation(Quaternion) Y Axis Component.
OrientZ	: Set the Rotation(Quaternion) Z Axis Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat = newType.vec4(0,0,0,0);
    bone.setLocalOrientation(obj, "Bip001_Head", quat.w, quat.x,quat.y,quat.z); 
end

void bone::setLocalPosition	(	int	entityID,
		string	boneName,
		float	posX,
		float	posY,
		float	posZ
	)

Set the local position of a bone. This is a position relative to its parent bone.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
posX	: Set the Position X Axis Component.
posY	: Set the Position Y Axis Component.
posZ	: Set the Position Z Axis Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    position = newType.vec3(0,0,0);
    bone.setLocalPosition(obj, "Bip001_Head", position.x,position.y,position.z); 
end

void bone::setManuallyControlled	(	int	entityID,
		string	boneName,
		int	state
	)

Set whether to override control to the user for this bone. This allows you to program the position, rotation and scale of the bone manually.

It is best if you use storeAnimTracks() before editing a bones animation in the onInit() and restoreAnimTracks() the animations in the onStop().

NOTE: It is important to manually restore the animation tracks since this is an advanced feature.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
state	1 - true, 0 - false. Set to overwrite the bone or not.

The following is a Small Example on how to use this function:

function onInit(objID)
    bone.setManuallyControlled(obj, "Bip001_Head", 1);
end

void bone::setScale	(	int	entityID,
		string	boneName,
		float	scaleX,
		float	scaleY,
		float	scaleZ
	)

Set the scale of a bone, useful for exploding character limbs lol.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
scaleX	: Set the Rotation(Quaternion) X Axis Component.
scaleY	: Set the Rotation(Quaternion) Y Axis Component.
scaleZ	: Set the Rotation(Quaternion) Z Axis Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    scale = newType.vec3(1,1,1);
    bone.setScale(obj, "Bip001_Head", scale.x,scale.y,scale.z); 
end

void bone::setWorldOrientation	(	int	entityID,
		string	boneName,
		float	OrientW,
		float	OrientX,
		float	OrientY,
		float	OrientZ
	)

Set the world orientation of a bone relative to world space zero.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
OrientW	: Set the Rotation(Quaternion) W Axis Component.
OrientX	: Set the Rotation(Quaternion) X Axis Component.
OrientY	: Set the Rotation(Quaternion) Y Axis Component.
OrientZ	: Set the Rotation(Quaternion) Z Axis Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    quat = newType.vec4(0,0,0,0);
    bone.setWorldOrientation(obj, "Bip001_Head", quat.w, quat.x,quat.y,quat.z); 
end

void bone::setWorldPosition	(	int	entityID,
		string	boneName,
		float	posX,
		float	posY,
		float	posZ
	)

Set the world space position of a bone. This is a position relative to world space zero.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
posX	: Set the Position X Axis Component.
posY	: Set the Position Y Axis Component.
posZ	: Set the Position Z Axis Component.

The following is a Small Example on how to use this function:

function onInit(objID)
    position = newType.vec3(0,0,0);
    bone.setWorldPosition(obj, "Bip001_Head", position.x,position.y,position.z); 
end

void bone::storeAnimTracks	(	int	entityID,
		string	boneName
	)

Using this function you can store all the animation tracks and keyframes
so you can destroy the bones animations to control it manually.

NOTE: It is important to manually restore the animation tracks since this is an advanced feature.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to store animation tracks for

The following is a Small Example on how to use this function:

function onInit(objID)
    bone.storeAnimTracks(obj, "Bip001_Head");
    bone.destroyAnimTracks(obj, "Bip001_Head"); -- destroy to empty all tracks.
    bone.setManuallyControlled(obj, "Bip001_Head", 1);
end

function onUpdate(td)
    bone.yaw(obj, "Bip001_Head", 1);
end

function onStop()
    bone.restoreAnimTracks(obj, "Bip001_Head"); -- replace all anim tracks, for next time play.
end

void bone::yaw	(	int	entityID,
		string	boneName,
		float	degree
	)

yaw a bone locally by a certain degree. is an acculative effect. Keep adding 1 to rotate continuously.

Parameters

entityID	: The entity in the scene you wish to edit their bones.
boneName	: The bone name to get the orientation.
degree	: The angle in degrees to yaw the bone.

The following is a Small Example on how to use this function:

function onInit(objID)
    bone.yaw(obj, "Bip001_Head", 1); 
end

The documentation for this class was generated from the following file:

LUA_API_Bone.h

Public Member Functions

Detailed Description

Member Function Documentation