Scripting API

LDCad 1.4 and higher uses lua for all scripting. So before you try using scripts inside LDCad you might first want to familiarize yourself with general lua usage.

Within LDCad the following official lua modules will always be available: base, bit32, math, package, string and table. Also available is the special LDCad module (ldc) in order to access tools and communicate with LDCad's internals.

The LDCad ldc module introduces the folowing userdata objects:

vector, a handy x,y,z vector container.
matrix, LDraw orientated 4x4 matrix container.
subfile, LDCad/LDraw subfile interface.
refLine, LDraw type 1 line interface.
group, LDCad group interface
animation, LDCad animation interface.
session, LDCad editing session interface.

ldc module functions

The ldc module exposes some simple top level functions which are used for general information and top level linking of ldc objects.

ldc.getApiVersion

getApiVersion returns the integer version number of the LDCad api, whenever something changes in the available functions and objects the number will be increased.

ldc.animation.getCurrent

getCurrent returns an new animation object linked to the currently playing animation. It will return an unlinked animation object if no animation is playing.

ldc.session.getCurrent

getCurrent returns a new session object linked to the current LDCad editing session, if no session is active it will return an unlinked session object.

ldc module objects

ldc.vector

The vector object is used to store a single x,y,z coordinate or direction.

A vector object can be obtained as the result from other ldc functions, but you can also create one for custom use using it's constructor, like:

local myVec=ldc.vector()

After that you can use the variable myVec to manipulate the x,y,z data. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.

myVec:clear()

Constructor

When creating a vector using ldc.vector() it will default to the 0,0,0. You can change this behavior by supplying additional parameters, accepted combinations are:

Parameters	Effect
a vector	Copies the given vector
a matrix	Copies the given matrix' position
3 numbers	Uses the given values as x,y and z.
a number	Sets x, y and z to the same given value.

clone

All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a vector you must use it's clone function. It will return a new vector containing identical data.

This function has no additional parameters.

clear

clear resets x,y and z to zero.

This function has no additional parameters.

set

set can be used to change the vector's x, y and z values in the same way you initialized them using the constructor.

It therefore accepts the same parameter combinations as described for the constructor.

This function has no return value.

setComp

setComp is used to change x, y or z using an index as a first paramater, where 1 is for x, 2 is for y and 3 is for z.

A second parameter is used as the new value for the indicated component.

This function has no return value.

setX

setX is used to change the x value of the vector. The only parameter is the new value for x.

This function has no return value.

setY

setX is used to change the y value of the vector. The only parameter is the new value for y.

This function has no return value.

setZ

setX is used to change the z value of the vector. The only parameter is the new value for z.

This function has no return value.

get

Get returns x,y and z in one go, like so:

local x, y, z=myVec:get()

Afterwards you can use the normal lua variables x, y and z to some manual (vector) calculations.

This function has no additional parameters.

getComp

getComp returns x,y or z using an index, where x is 1, y is 2 and z is 3.

getX

getX returns the current x value of the vector.

This function has no additional parameters.

getY

getX returns the current y value of the vector.

This function has no additional parameters.

getZ

getX returns the current z value of the vector.

This function has no additional parameters.

add

add is used to increase x, y and z with a given value. The value can be another vector or any of the valid vector constructor parameter combinations.

This function has no return value.

getAdd

getAdd returns a new vector with the result of x,y and z increased by a value. The value can be another vector or any of the valid vector constructor parameter combinations.

sub

sub is used to decrease x, y and z with a given value. The value can be another vector or any of the valid vector constructor parameter combinations.

This function has no return value.

getSub

getSub returns a new vector with the result of x,y and z decreased by a value. The value can be another vector or any of the valid vector constructor parameter combinations.

mul

mul is used to multiply x, y and z with a given value. The value can be another vector or any of the valid vector constructor parameter combinations.

This function has no return value.

getMul

getMul returns a new vector with the result of x,y and z multiplied by a value. The value can be another vector or any of the valid vector constructor parameter combinations.

transform

transform applies a given matrix transformation to x,y and z. The given matrix can be any of the valid matrix constructor parameter combinations.

This function has no return value.

getTransformed

getTransformed returns a new vector which hold the result of x,y and z transformation with a given matrix. The given matrix can be any of the valid matrix constructor parameter combinations.

normalize

normalize will rescale the vector so it's length becomes 1.0.

This function also returns the old length of the vector.

This function has no additional parameters.

getNormalized

getNormalized will return a new vector with the same direction but a length of 1.0.

This function has no additional parameters.

getLength

getLength returns the length of the vector.

This function has no additional parameters.

getDot

getDot returns the dot product of x,y,z with a second vector. The given vector is accepted in any of the valid vector constructor parameter combinations.

getCross

getCross returns a new vector containing the cross product of x,y,z with a second vector. The given vector is accepted in any of the valid vector constructor parameter combinations.

getAngle

getAngle returns the inner angle with the given second vector in degrees. The second vector can be given using any of the valid vector constructor parameter combinations.

note: this function accepts any vector, normalizing is not required.

getSignedAngle

getSignedAngle returns the angle between two other vectors in degrees, assuming it's own data is the plane normal.

The result will be negative if the first given vector is in front of the second one (e.g. 2 o clock and 3 o clock.).

The first vector must be given using a existing vector object, the second vector may be given using any of the valid vector constructor parameter combinations.

note: this function accepts all vectors, normalizing is not required.

ldc.matrix

The matrix object is a matrix math container/helper object. LDCad orientated matrix operations are highly targeted for use in combination with the LDraw type 1 lines at model level. To this end all matrices are assumed to describe an orientation and a position only. If needed you could also apply scaling but this is not officially supported when applied to the model as shown inside LDCad and will result in lighting problems etc.

A matrix object can be obtained as the result from other ldc functions, but you can also create one for custom use using it's constructor, like:

local myMatrix=ldc.matrix()

After that you can use the variable myMatrix to manipulate the matrix' data. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.

myMatrix:setIdentity()

Constructor

When creating a matrix using ldc.matrix() it will default to the neutral state of "1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1". You can change this behavior by supplying additional parameters, accepted combinations are:

Parameters	Effect
a matrix	Copies the given matrix
12 numbers	LDraw ref line notation
9 numbers	Uses the given values as the 3x3 orientation sub matrix, while still using the default for the position.
3 numbers	Uses the given values as position while still using the default for the orientation.
4 vectors	The first vector will be used as position, the other 3 as the orientation. They are paired the same as the normal 12 number LDraw style variant.
3 vectors	Uses the given vectors as the 3x3 orientation sub matrix, while still using the default for the position.
a vector	Uses the given vector as position while still using the default for the orientation.

clone

All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a matrix you must use it's clone function. It will return a new matrix containing identical data.

The clone function has no additional parameters.

set

The set function can be used to change the matrix' data in the same way you did while using the constructor. Set therefore accepts the same paramter combinations as the constructor call does.

set does not return a value

setIdentity

setIdentitiy loads the neutral state into the matrix data.

It has no additional parameters nor does it return a value.

setOri

setOri can be used to change the orientation (3x3 sub matrix) of matrix data, this can be done using the following parameter combinations:

Parameters	Effect
a matrix	Copies the orientation part of the given matrix
9 numbers	Uses the given values as the 3x3 orientation sub matrix.
3 vectors	Uses the given vectors as the 3x3 orientation sub matrix.

setOri does not return a value

setPos

setPos can be used to change the positional part of the matrix data, this can be done using any of the valid vector constructor parameter combinations.

setPos does not return a value

setMul

setMul is used to store the result of two other matrices multiplied together into the matrix. It therefore takes two matrix objects as parameters

The function does not return a values as it changes the data it self.

getOri

getOri returns a copy of the orientation part of the matrix in a new matrix object. The positional part of the resulting matrix will be set to 0,0,0,

The function has no additional parameters.

getPos

getPos returns a new vector object containing the positional data of the matrix.

The function has no additional parameters.

get

Get returns 12 numbers which hold the current matrix data in LDraw type 1 line style notation, like so:

local x, y, z, a, b, c, d, e, f, g, h, i=myMatrix:get()

You can use these values when you want to do some manual lowlevel matrix math/manipulations or need to pass the data to some third party library.

The function has no additional parameters.

stripOri

stripOri will reset the orientation part of the matrix to it's neutral value while leaving the positional part alone.

A new matrix containing a copy of the old orientation (without position) will also be returned.

The function has no additional parameters.

stripPos

stripPos will reset the positional part of the matrix to 0,0,0 while leaving the orientation part alone.

A new vector containing a copy of the old position will also be returned.

The function has no additional parameters.

limitToOri

limitToOri will remove the positional information from the matrix while retaining the orientation part.

The function has no additional parameters nor will it return a value.

limitToPos

limitToPos will remove the orientation information from the matrix while retaining the positional part.

The function has no additional parameters nor will it return a value.

mulAB

mulAB will use a second matrix to multiply it self with like so: self=self*B

Besides a direct second matrix you can also use any of the matrix constructor parameter combinations as a source for 'B'

The function does not return a value.

mulBA

mulBA will use a second matrix to multiply it self with like so: self=B*self

Besides a direct second matrix you can also use any of the matrix constructor parameter combinations as a source for 'B'

The function does not return a value.

getMulAB

getMulAB is identical to mulAB, except it returns a new matrix with the resulting data without changing it's own data.

getMulBA

getMulBA is identical to mulBA, except it returns a new matrix with the resulting data without changing it's own data.

mulOriAB

mulOriAB will use a second matrix to transform it's 3x3 sub matrix orientation, like so: self=self*B

The positional information of the matrix will remain unchanged.

Besides a direct second matrix you can also use any of the orientation orientated matrix constructor parameter combinations as a source for 'B'. See also setOri

The function does not return a value.

mulOriBA

mulOriBA will use a second matrix to transform it's 3x3 sub matrix orientation, like so: self=B*self

The positional information of the matrix will remain unchanged.

Besides a direct second matrix you can also use any of the orientation orientated matrix constructor parameter combinations as a source for 'B'. See also setOri

The function does not return a value.

getMulOriAB

getMulOriAB is identical to mulOriAB, except it returns a new matrix with the resulting orientation without changing it's own data.

getMulOriBA

getMulOriAB is identical to mulOriBA, except it returns a new matrix with the resulting orientation without changing it's own data.

setTranslate

setTranslate will load a translation transformation into the matrix. It will replace both orientation and positional information.

The translation can be given trough any valid vector describing combination of parameters (see vector constructor)

The function does not return a value.

mulTranslateAB

mulTranslateAB will perform a translation transformation upon it'c current data. The given translation (in matrix form) will be applied like so: self=self*transMatrix

The translation can be given trough any valid vector describing combination of parameters (see vector constructor)

The function does not return a value.

mulTranslateBA

mulTranslateAB will perform a translation transformation upon it'c current data. The given translation (in matrix form) will be applied like so: self=transMatrix*self

The function does not return a value.

getMulTranslateAB

getMulTranslateABis identical to mulTranslateAB, except it returns a new matrix with the resulting data without changing it's own data.

getMulTranslateBA

getMulTranslateBAis identical to mulTranslateBA, except it returns a new matrix with the resulting data without changing it's own data.

setRotate

setRotate loads an rotation transformation into the matrix, this will overwrite any existing data of the matrix.

The desired rotation must be given using an angle (in degrees) and a vector to rotate around. The vector part can be given using any of the valid vector constructor combination of parameters.

The function does not return a value.

mulRotateAB

mulRotateAB will perform a rotation transformation upon it's current data. The given rotation (in matrix form) will be applied like so: self=self*rotateMatrix

The desired rotation must be given using an angle (in degrees) and a vector to rotate around. The vector part can be given using any of the valid vector constructor combination of parameters.

The function does not return a value.

mulRotateBA

mulRotateBA will perform a rotation transformation upon it's current data. The given rotation (in matrix form) will be applied like so: self=rotateMatrix*self

The desired rotation must be given using an angle (in degrees) and a vector to rotate around. The vector part can be given using any of the valid vector constructor combination of parameters.

The function does not return a value.

getMulRotateAB

getMulRotateAB is identical to mulRotateAB, except it returns a new matrix with the resulting data without changing it's own data.

getMulRotateBA

getMulRotateBA is identical to mulRotateBA, except it returns a new matrix with the resulting data without changing it's own data.

invert

invert inverts the matrix so it becomes it's own 'undo' transformation.

This function has no additional parameters nor does it return a value.

invertOri

invertOri inverts (3x3 transpose) it's orientation part without changing the positional information.

This function has no additional parameters nor does it return a value.

invertPos

invertPos flips the signs of the x,y and z positional coordinates. The orientation will remain unchanged.

This function has no additional parameters nor does it return a value.

getInverted

getInverted does the same as invert but returns the result as a new matrix object without changing it's own data.

getInvertedOri

getInverted does the same as invertOri but returns the resulting orientation (so no positional info) as a new matrix object without changing it's own data.

getInvertedPos

getInvertedPos does the same as invertPos but returns the resulting positional as a new vector object without changing it's own data.

getTransformed

getTransformed can be used to apply the current matrix data to some source.

The source must be given as a vector or one of it's valid constructor combination of parameters.

The function will then return the transformed x,y and z values.

ldc.subfile

A subfile object is used to access a single LDraw model inside LDCad. It's called a subfile because an LDraw file can hold multiple models (mpd).

A subfile object can be obtained as the result from other ldc functions, but you can also create one for custom use using it's constructor, like:

local mySF=ldc.subfile()

After that you can use the variable mySF to access the associated LDraw model data. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.

local cnt=mySF:getRefCount()

Constructor

When creating a subfile using ldc.subfile() it will default to the top level model of the current editing session. But You can also point it to somthing alternative by supplying the wanted model's name as the constructor's parameter.

When e.g. 'minifig.ldr' is given and is used anywhere in the current sessions model tree it will be linked to the subfile object. If there is no such model, the subfile object will be unlinked.

Do note an unlinked subfile object will cause a runtime error as soon you try to use it in a way which requires it to be linked.

It's also permitted to supply another subfile object as a parameter to the constructor in order to copy it.

clone

All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a subfile object you must use it's clone function. It will return a new subfile object containing identical data.

The clone function has no additional parameters.

link

link is used to associate the subfile object with a (different) subfile inside LDCad. This is done by giving a name which is then used to search the current session's model tree. If no name is given the object will default to the top level subfile of the current session.

If no session is active or no subfile with the given name could be found the session object will be unlinked.

Do note an unlinked subfile object will cause a runtime error as soon you try to use it in a way which requires it to be linked.

The function will return true if a link was setup successfully, false if not.

isLinked

isLinked returns a boolean indicating if the object is currently linked with a subfile or not.

This function has no additional parameters.

getFileName

getFileName returns the full filename of the currently linked (if any) subfile.

If the object is not linked an empty string will be returned.

This function has no additional parameters.

getRefCount

getRefCount returns the number of type 1 lines in the linked subfile.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getRef

getRef is used to obtain a new refLine object linked to one of the type 1 lines the linked subfile holds.

You can access the lines by index, starting at 1, or by part name (e.g. 3001.dat). If a partname is given the first reference in the subfile pointing to it will be returned. If a partname and a index is given the nth reference pointing to it will be returned

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getGroupCount

getGroupCount returns the number of groups that have their top level at the linked subfile.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getGroup

getGroup is used to obtain a new group object linked to one of the LDCad groups living in the linked subfile.

You can access the groups by index, starting at 1, or by group name (e.g. Group 1).

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

ldc.refLine

A refLine object is used to access a single LDraw type 1 line inside LDCad.

refLine objects are always obtained from other ldc functions. Like for example:

local myRef=mySF:getRef(1)

After that you can use the variable myRef to manipulate the associated LDraw type 1 line data. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.

myRef:setColor(15)

Constructor

The refLine constructor has no parameters and the object will therefore be not linked to any real LDraw type 1 line.

Do note an unlinked refLine object will cause a runtime error as soon you try to use it in a way which requires it to be linked.

It's also permitted to supply another refLine object as a parameter to the constructor in order to copy it.

clone

All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a refLine object you must use it's clone function. It will return a new refLine object containing identical data.

The clone function has no additional parameters.

isLinked

isLinked returns a boolean indicating if the object is currently linked with a refLine or not.

This function has no additional parameters

getOri

getOri returns a new matrix object containing the current orientation of the linked refLine. Do note the orientation is relative to the level it's parent subfile is at.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getPos

getPos returns a new vector containing the position of the linked type 1 line. Do note the given information is relative to the level it's parent subfile is at.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getPosOri

getPosOri returns a new matrix object containing the full placement matrix of the linked type 1 line. Do note the given information is relative to the level it's parent subfile is at.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setOri

setOri is used to change the orientation of the linked type 1 line, without changing it's position. You can use any of the orientation oriented matrix constructor combination of parameters in order to supply the new placement. For more info about the parameters see also the setOri function of the matrix object it self.

Do note the given information must be relative to the level the refLine's parent subfile is at.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setPos

setPos is used change the position of the linked type 1 line without changing it's orientation. The new position can be supplied using any of the valid vector constructor parameter combinations.

Do note the given information must be relative to the level the refLine's parent subfile is at.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setPosOri

setPosOri is used to change the full LDraw placement matrix of the linked type 1 line. You can use any of the valid matrix constructor combination of parameters in order to supply the new placement.

Do note the given information must be relative to the level the refLine's parent subfile is at.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getVisible

getVisible returns a boolean indicating if the linked type 1 line is currently visible inside the LDCad editor.

Do note the visibility state is only relavant during playback of animations.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setVisible

setVisible is used to change the visible state of the linked type 1 line inside the LDCad editor. This is done by supplying a boolean parameter.

Do note the visibility state is only relavant during playback of animations.

This function has no return value.

If the object is unlinked a runtime error will occur, calling this function will terminate the script's execution.

getColor

getColor returns the currently used LDraw color code of the linked type 1 line.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setColor

setColor is used to change the color of the linked type 1 line. The color must be given using it's LDraw color code.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getSubfile

getSubfile returns a new subfile object linked to the subfile this refLine belongs to.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

ldc.group

The group object is used to access the LDraw content inside a LDCad group. Group objects can be obtained from other ldc functions or created standalone using their constrcutor, like for example:

local myGrp=ldc.group()

The myGrp variable can then be used to access the contents of a linked group. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.

myGrp:setColor(15)

Constructor

When creating a group object using ldc.group() it will default to it's unlinked state. But You can also point it to something useful from the get go by supplying the wanted group name as the constructor's parameter.

When e.g. 'Group 1' is used, the current session's main subfile will be searched for the given group. You can optionally request an recursive search for the group by supplying true as a second parameter.

If found it will be linked and you can start working with that group, if not found the state will remain unlinked. Do note an unlinked group object will cause a runtime error as soon you try to use it in a way which requires it to be linked.

It's also permitted to supply another group object as a parameter to the constructor in order to copy it.

clone

All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a group object you must use it's clone function. It will return a new group object containing identical data.

The clone function has no additional parameters.

link

link is used to associate the group object with a (different) LDCad group using a name as it's first parameter.

Optionally a second boolean paramater can be used to indicatie if the function must recursively search the current sessions model tree (true) or just it's main subfile (false, the default).

If a group with the given name is not found the object will become unlinked.

A boolean is returned indicating if the link was succesful.

isLinked

isLinked returns a boolean indicating if the object is currently linked with a group or not.

This function has no additional parameters

getGroupName

getGroupName returns the linked group's name. If there is no group currently linked it will return an empty string.

This function has no additional parameters

getRefCount

getRefCount returns the number of type 1 lines inside the linked LDCad group. Do note this count might not be equal to the total number of items in the group as a group's content does not have to be exclusively type 1 lines.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getRef

getRef is used to obtain a new refLine object linked to one of the type 1 lines the linked LDCad group holds. If a partname is given instead the function will return the first reference pointing to it. If a partname and an index is given the function will return the nth reference pointing to it.

You can access the lines by index, starting at 1, or by part name (e.g. 3001.dat). If a partname is given the first reference in the group pointing to it will be returned.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getOri

getOri returns a new matrix object containing the current orientation of the linked LDCad group. Do note the orientation is relative to the level the main item of the linked group is at.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getPos

getPos returns a new vector containing the position of the linked LDCad group current center point.

Do note the position is relative to the level the main item of the linked group is at. It also indicates the groups center position not the main items true position.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getPosOri

getPosOri returns a new matrix object containing the full placement matrix of the linked LDCad group. Do note this placement is relative to the level the main item of the linked group is at. It's positional part is taken from the group's current center point.

This function has no additional parameters.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setOri

setOri is used to change the orientation of the linked LDCad group, without changing it's position. You can use any of the orientation oriented matrix constructor combination of parameters in order to supply the new placement. For more info about the parameters see also the setOri function of the matrix object it self.

Do note the given information must be relative to the level the main item of the linked group is at.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setPos

setPos is used change the position of the linked type 1 line without changing it's orientation. The new position can be supplied using any of the valid vector constructor parameter combinations.

Do note the given information must be relative to the level the main item of the linked group is at. It also applies to the groups center position not the main item's true position.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setPosOri

setPosOri is used to change the full LDraw placement matrix of the linked LDCad group. You can use any of the valid matrix constructor combination of parameters in order to supply the new placement.

Do note the given information must be relative to the level the main item of the linked group is at. It also applies to the groups center position not the main item's true position.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setVisible

setVisible will show or hide all items in the linked group using a boolean parameter.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setColor

setColor will apply a given LDraw color code to all items in the linked group.

This function has no return value.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

ldc.animation

The animation object is used to access and or create an animation inside LDCad. It's almost always created using it's constrcutor, like for example:

local myAni=ldc.animation()

The myAni variable can then be used to manipulate an animation. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.

myAni:register('kick ass movie')

Constructor

When creating an animation object using ldc.animation() it will default to it's unlinked state. But You can also point it to an existing or new animation in one go by supplying the wanted animation name as the constructor's parameter.

When the given name is an existing animation inside the current editing session it will be linked to it. If there is no such animation it will be added en then linked.

Do note an unlinked animation object will cause a runtime error as soon you try to use it in a way which requires it to be linked.

It's also permitted to supply another animation object as a parameter to the constructor in order to copy it.

clone

All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a animation object you must use it's clone function. It will return an new animation object containing identical data.

The clone function has no additional parameters.

This is done by supplying a name, if an animation is found with that name it will be linked to, otherwise it will be created and then linked to.

This function has no return value.

link

link is used to link the animation object to an (diffent) animation inside the current editing session.

This is done by supplying a name, if an animation is found with that name it will be linked to, otherwise it the object will revert to it's unlinked state.

A boolean is returned indicating a link was succesful or not.

isLinked

isLinked returns a boolean indicating if the object is currently linked with a animation or not.

This function has no additional parameters

getName

getName returns the name of the current linked animation, if none is currently linked a empty string will be returned.

The clone function has no additional parameters.

setFPS

setFPS is used to set the linked animation's number of frames per second for playback.

When this function is never called the animation will default to the current LDCad internal default. Only change the fps through script if you want to enforce a static frame rate for some reason.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getFPS

getFPS returns the current number of frames per second the linked animation uses during playback.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getFrameNr

getFrameNr returns the currently active frame of the linked animation. Do note contrary to normal lua behavior this first frame in an animation is numbered zero, this is mainly because of math purposes.

Also note the number does not have to lie within the 0..fps*length-1 range as it accounts for extra frames resulting from things like slow motion.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getFrameCount

getFrameCount returns the currently active number of frames of the linked animation.

Do note the number does not have to be equal to fps*length as it accounts for extra frames resulting from things like slow motion.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getFrameTime

getFrameTime returns the time in seconds the current frame in the linked animation represents. This will be zero for the first frame and (length-1/fps) for the last.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setLength

setLength is used to configure the linked animation's playback time. You must supply the desired length in seconds.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

getLength

getLength returns the linked animation playback time in seconds.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

setEvent

setEvent is used to control which lua script function is called when a certain animation event occurs. This is done by supplying two string paramters.

The first parameter identifies the event you want to subscribe to, available events are:

Event	Description
start	Called whenever an animation is about to begin playback. You can use this event to do some global precalculations etc.
end	Called whenever an animation just stopped. You can use this to do some clean up or something.
frame	Called when ever the current frame of the animation changes. This event is the main workhorse as it must calculate and apply the state of all animated stuff in your animation. Do note frame calls can be complete random in regards of their associated frameNr. This as the result of the kind of playback and or seeking.

The second paramater is the name (without the '()') of the lua function inside your script you want executed when ever the given event occurs.

Do note events are linked at the LDCad level, not just for the animation object you are working with.

If the object is unlinked calling this function will cause a runtime error terminating the script's execution.

ldc.session

A session object is used to access an LDCad editing session. It's always created using it's constructor, like so:

local mySes=ldc.session()

The mySes variable can then be used to access the information about a linked session. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.

print(mySes:getName())

Constructor

When creating a session object using ldc.session() it will default to the current editing session, it there is none it will be in it's unlinked state.

Do note an unlinked session object will cause a runtime error as soon you try to use it in a way which requires it to be linked.

It's also permitted to supply another session object as a parameter to the constructor in order to copy it.

clone

All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a session object you must use it's clone function. It will return a new session object containing identical data.

The clone function has no additional parameters.

isLinked

isLinked returns a boolean indicating if the object is currently linked with a session or not.

This function has no additional parameters

getName

getName returns the name of the linked session. The given name is identical to the one displayed in the top right of the LDCad editing area. If no session is currently linked an empty string will be returned.

This function has no additional parameters

Name
Pass