Scripting API
api version 6 (1.7 Alpha 2)
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, io, 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 following items:
- vector, a handy x,y,z vector container. This is mainly use for vector math and 3D positional manipulations.
- matrix, LDraw orientated 4x4 matrix container. This is mainly used to manipulate the position and orientation of objects.
- subfile, LDCad/LDraw subfile interface, used to manipulate the contents of a single LDraw subfile.
- srcLine, generic LDraw line interface, used to manipulate lines without worrying about the exact line type.
- refLine, LDraw type 1 line interface, used to manipulate reference lines.
- group, LDCad group interface, used to manipulate the custom made groups inside your models.
- selection, LDCad selection interface, used to manipulate the selection of the current session.
- animation, LDCad animation interface, used to setup and interact with an animation inside LDCad.
- camera, LDCad camera interface, used to setup and interact with cameras inside LDCad.
- light, LDCad light interface, used to setup and interact with lights inside LDCad.
- control, LDCad animation control, used to create and manipulate interactive objects inside an animation.
- event, Script event state information, used to query environment states while inside a LDCad lua callback function.
- input, mouse and keyboard interaction interface, for use in interactive animations.
- dialog, simple user dialog object, used to ask the user simple questions or to relay messages.
- session, LDCad editing session interface, used to access the current editing session.
- view, LDCad (3D) view interface, used to access view related features.
- partBin, LDCad partBin interface, used to manipulate the partBin.
- colorBin, LDCad colorBin interface, used to manipulate the partBin.
- action, LDCad action interface, used to access and execute hot key related tasks inside LDCad.
- macro, LDCad macro interface, used to create or access a LDCad macro.
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.getVersion
getVersion returns the full LDCad version string, e.g. "LDCad 1.7 (LNX64).
ldc.getLuaVersion
getLuaVersion returns the current lua version string, e.g. "5.3.1"
ldc.getClipboardText
getClipboardText returns the current system clipboard text.
ldc.setClipboardText
setClipboardText can be used to set the system clipboard text.
The function has a single string parameter.
ldc submodules
ldc.vector
The vector submodule is used to manipulate 3D vectors.
Constructor
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()
When creating a vector using ldc.vector() it will default to the 0,0,0. You can change this behaviour 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 its 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 parameter, 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.
invert
This function will multiply x, y and z with -1.
getInverted
The function will return a new vector which will be initialized with this vector's x, y and z multiplied by -1.
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.
getLength
getLength returns the length of the vector.
This function has no additional parameters.
getDistance
getDistance will return the shortest distance between the current x,y and z position relative to a given directional vector.
This function takes one or two vectors as parameters. If two vectors are given the first one must be a ldc.vector object which will be used as the origin of the directional vector.
The second or only vector wil be used as the directional vector and can be given using any of the ldc.vector constructor combination of 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 submodule is used to manipulate LDraw oriented 4x4 matrices.
Constructor
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()
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 its clone function.
It will return a new matrix containing identical data.
This 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.
getOriCol
getOriCol will return a single column of the 3x3 orientation submatrix as a new vector object. This is in the same order as the constructor as the constructor is also column orientated.
The function takes a single integer parameter indicating the wanted column, 1 for X, 2 for Y and 3 for Z.
local myMatrix=ldc.matrix(x, y, z, a, b, c, d, e, f, g, h, i)
local yCol=myMatrix:getOriCol(2)
In the above example the new yCol vector would contain the d, e, f values for its x, y and z components.
getOriXCol
getOriXCol is a alias for getOriCol(1), see above for details.
getOriYCol
getOriYCol is a alias for getOriCol(2), see above for details.
getOriZCol
getOriZCol is a alias for getOriCol(3), see above for details.
getOriCols
getOriCols will return all three 3x3 orientation matrix columns at once, like so:
local xCol, yCol, zCol=myMatrix:getOriCols()
setOriCols
The setOriCols function is used to initialize the 3x3 orientation submatrix using three column vectors. The three given vectors are used in the same way the ldc.matrix constructor would use them.
getOriRow
getOriRow will return a single row of the 3x3 orientation submatrix as a new vector object. Please not this is a different order when comparing to the constructor as the constructor is column orientated.
The function takes a single integer parameter indicating the wanted row, 1 for X, 2 for Y and 3 for Z.
local myMatrix=ldc.matrix(x, y, z, a, b, c, d, e, f, g, h, i)
local yRow=myMatrix:getOriRow(2)
In the above example the new yRow vector would contain the b, e, h values for its x, y and z components.
getOriXRow
getOriXRow is a alias for getOriRow(1), see above for details.
getOriYRow
getOriYRow is a alias for getOriRow(2), see above for details.
getOriZRow
getOriZRow is a alias for getOriRow(3), see above for details.
getOriRows
getOriCols will return all three 3x3 orientation matrix rows at once, like so:
local xRow, yRow, zRow=myMatrix:getOriRows()
setOriRows
The setOriRow function is used to initialize the 3x3 orientation submatrix using three row vectors. Please not this is in a different order then the constructor would use them as the constructor is column oriented.
All three vectors will automatically be normalized but are expected to be orthogonal.
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
The subfile submodule is used to access and manipulate LDraw subfile content.
Constructor
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()
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 its clone function.
It will return a new subfile object containing identical data.
This 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.
hasSameLink
hasSameLink takes a single subfile object as a parameter and returns a boolean indicating if that object is linked to the same LDCad/LDraw subfile or not.
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.
getLineCount
getLineCount will return the number of LDraw lines in the linked subfile.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getLine
getLine takes a single integer parameter and will return the a new ldc.srcLine object linked to the nth LDraw line in the currently linked subfile. The first line in the sbufile has a index of 1.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getStepCount
getStepCount will return the number of steps in the linked subfile.
Please note this is equal to the number of step meta's plus one, as there is always at least one step in a subfile.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getStepLineInfo
getStepLineInfo takes a single integer parameter indicating a step number, starting with 1.
It then returns the offset, starting with 1, to the first LDRaw line and the number of lines in that step, like so:
local ofs,cnt=mySF:getStepLineInfo(2)
ofs and cnt can then be used together with mySF:getLine to e.g. loop all the LDraw lines inside that step.
If the given step does not exist or if the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getStepRefInfo
getStepRefInfo takes a single integer parameter indicating a step number, starting with 1.
It then returns the offset, starting with 1, to the first LDRaw type 1 line and the number of such lines in that step, like so:
local ofs,cnt=mySF:getStepRefInfo(2)
ofs and cnt can then be used together with mySF:getRef to e.g. loop the reference lines inside that step.
If the given step does not exist or if the object is unlinked calling this function will cause a runtime error terminating the script's execution.
addNewLine
addNewLine takes an optional index followed by a string or line related object. It will then add a new LDraw line to the currently linked subfile. The new line will be appended after the last one if no index is given or inserted at the given index pushing all following (including the line currently at the index position) content one line down.
If a string is given as the only or second parameter it will be parsed as a LDraw line just like if it where in a file.
If a line object is given as the only or second parameter the new line will be a copy of it it and the given line will remain unchanged.
The function returns a new ldc.srcLine object linked to the new LDraw line, like so:
local newLine=mySF:addNewLine('0 //Hello all')
If the given (optional) index is out of range or the object is unlinked calling this function will cause a runtime error terminating the script's execution.
deleteLine
deleteLine takes a single integer or line object parameter.
If an integer is given it will be used to delete the nth (starting at 1) line from the linked subfile.
If a line object is given the function will delete it from the linked subfile if it's currently linked to a line in the object's subfile. It will do nothing if the given line belongs to another subfile.
The function will return a boolean (no matter the parameter type) indicating if the line was indeed deleted or not.
If the given index is out of range or the object is unlinked calling this function will cause a runtime error terminating the script's execution.
moveLine
moveLine takes an index or line object combined with a second integer in order to move the first line.
The function will move the given line (or the one at the given index) to the (second) given index counting lines as they where, meaning if you have a line order of "a b c d" and you use the function like moveLine(1, 3) the resulting line order would be "b c a d".
The function returns a boolean indicating if the line was actually moved or not.
If a line object is given as the first parameter it must be linked with a line inside the same subfile, if not a runtime error will terminate the script's execution.
If a given index is out of range or the object is unlinked calling this function will cause a runtime error terminating the script's execution.
addNewRef
addNewRef takes an optional index followed by a ldc.refLine object or a partName string. It will then add a new LDraw type 1 line to the currently linked subfile. The new line will be appended after the last type 1 line if no index is given or inserted at the given index pushing all following (including the line currently at the index position) content one line down.
If a string is given as the only or second parameter a new type 1 line referencing the named part using color 16 at position 0,0,0 and in a neutral orientation.
If a refLine object is given as the only or second parameter the new line will be a copy of it it and the given line will remain unchanged.
The function returns a new ldc.refLine object linked to the new LDraw type 1 line and the index of the new line, like so:
local newRef=mySF:addNewRef('3001.dat')
If the given (optional) index is out of range or the object is unlinked calling this function will cause a runtime error terminating the script's execution.
deleteRef
deleteRef takes a single integer or line object parameter.
If an integer is given it will be used to delete the nth (starting at 1) type 1 line from the linked subfile.
If a line object is given the function will delete it from the linked subfile if it's currently linked to a type 1 line in the object's subfile. It will do nothing if the given line is not a type 1 line or if it belongs to another subfile.
The function will return a boolean (no matter the parameter type) indicating if the line was indeed deleted or not.
If the given index is out of range or the object is unlinked calling this function will cause a runtime error terminating the script's execution.
moveRef
moveRef takes an index or line object combined with a second integer in order to move the first line.
The function will move the given type 1 line (or the one at the given index) to the (second) given index counting type 1 lines as they where, meaning if you have a ref order of "a b c d" and you use the function like moveRef(1, 3) the resulting ref order would be "b c a d".
The function returns a boolean indicating if the line was actually moved or not.
If a line object is given as the first parameter it must be linked with a type 1 line inside the same subfile, if not a runtime error will terminate the script's execution.
If a given index is out of range or the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isPart
isPart returns a boolean indicating if the linked subfile is considered to be a part by the LDCad internals.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isRealPart
isRealPart returns a boolean indicating if the linked subfile is considered to be a real/native part by the LDCad internals.
The difference between isRealPart and isPart is isRealPart will exclude redirect and alias parts.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isColourPart
isColourPart returns a boolean indicating if the linked subfile is considered to be a part with a fixed colour by the LDCad internals.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isShortCut
isShortCut returns a boolean indicating if the linked subfile is considered to be a short cut part by the LDCad internals.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isModel
isModel returns a boolean indicating if the linked subfile is considered to be a model by the LDCad internals.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isGenerated
isGenerated returns a boolean indicating if the linked subfile is using one of LDCad's generators.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isOfficialPart
isOfficialPart returns a boolean indicating if the linked subfile is considered to be an official library part by the LDCad internals.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isMoved
isMoved returns a boolean indicating if the linked subfile is considered to be an 'moved' part alias by the LDCad internals.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isAliasPart
isAliasPart returns a boolean indicating if the linked subfile is considered to be a part alias by the LDCad internals.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isMissing
isMissing returns a boolean indicating if the linked subfile is a place holder for missing content or not.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isRedirectedPart
isRedirectedPart returns a boolean indicating if the linked subfile is considered to be a redirected part by the LDCad internals.
This function is a combination of (isPart and not isRealPart).
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getDescription
getDescription will return a string containing the currently linked subfile's description text from its header.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getAuthor
getAuthor will return a string containing the currently linked subfile's author text from its header.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getCategory
getCategory will return a string containing the currently linked subfile's category text from its header.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getLicense
getLicense will return a string containing the currently linked subfile's license text from its header.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
ldc.srcLine
The srcLine submodule is used to manipulate LDraw line and group item content inside LDCad.
Constructor
A srcLine object is used to access a single LDraw line or group item inside LDCad.
A srcLine 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 myLine=ldc.srcLine()
After that you can use the variable myLine 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.
print(myLine:isLinked())
When creating a subfile using ldc.srcLine() it will default to an unlinked state. An unlinked srcLine object isn't very useful, so you usually obtain srcLine objects from other functions.
It's also permitted to supply another subfile object as a parameter to the constructor in order to copy it.
Do note an unlinked srcLine object will cause a runtime error as soon you try to use it in a way which requires it to be linked.
clone
All ldc objects are lua userdata orientated, and therefore always passed by reference. So to obtain a copy of a srcLine object you must use its clone function.
It will return a new srcLine object containing identical data.
link
The link function can be used to link the srcLine object to another ldraw line. It takes only one parameter which must be another (compatible) line orientated object.
isLinked
isLinked returns a boolean indicating if the object is currently linked with a LDraw line or not.
hasSameLink
hasSameLink takes a single line based object as a parameter and returns a boolean indicating if that object is linked to the same LDraw line or not.
isGroupItem
isGroupItem returns a boolean indicating if this object is linked to a group item instead of a normal subfile line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isGroupRef
isGroupRef returns a boolean indicating if this object is linked to group reference group item.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getGroupRef
getGroupRef returns a new group object linked to the group this group item is referencing. It will return an unlinked group object if this line object is currently not linked to an group reference item.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getLineIndex
getLineIndex returns the index, starting with 1, of the current linked line inside the containing subfile object.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getOwner
getOwner returns a new subfile object linked to this lines containing subfile.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
delete
delete can be used to remove the currently linked LDraw line from its containing subfile. If the object is linked to an group item this function will do nothing.
If the line was actually removed the object will no longer be linked.
The function will return a boolean indicating if something was deleted or not.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isMeta
isMeta returns a boolean indicating if this line is LDraw meta line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isRef
isRef returns a boolean indicating if this line is a LDraw type 1 line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isStatEdge
isStatEdge returns a boolean indicating if this line is LDraw a type 2 (edge) line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isTriangle
isTriangle returns a boolean indicating if this line is LDraw a type 3 (triangle) line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isQuad
isQuad returns a boolean indicating if this line is LDraw a type 4 (quad) line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isCondEdge
isCondEdge returns a boolean indicating if this line is LDraw a type 5 (conditional edge) line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isEdge
isEdge returns a boolean indicating if this line is a LDraw type 2 or 5 line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isStepMeta
isStepMeta returns a boolean indicating if this line is a step meta line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isNormalStepMeta
isNormalStepMeta returns a boolean indicating if this line is a basic (non rotational) step meta line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
isRotationStepMeta
isRotationStepMeta returns a boolean indicating if this line is a step rotation meta line.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
ldc.refLine
The refLine sub module is used to manipulate LDraw type 1 lines inside LDCad.
Constructor
the constructor is used to create a new refLine object.
Optionally another refLine object can be given as the only parameter in order to copy that object. Without another object the new object will default to the unlinked state.
Useful 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)
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.
srcLine functions
A refLine object also offers all functions a srcLine object offers, see above for their details.
getRefIndex
getRefIndex returns the index of the linked LDraw type 1 line inside the containing subfile as counted from 1.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getName
getName returns a string containing the name of the subfile this type 1 line is currently referencing.
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 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 submodule is used to access and manupulate LDCad editing groups.
Constructor
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)
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 its clone function.
It will return a new group object containing identical data.
This 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
hasSameLink
hasSameLink takes a single group object as a parameter and returns a boolean indicating if that object is linked to the same LDCad group or not.
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
getLineCount
getLineCount returns the number of lines/items in the current linked group.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getLine
getLine returns the nth line in the currently linked group. It takes an integer parameter indicating the index, starting with 1, of the requested line.
If the object is unlinked or if the index is out of bound calling this function will cause a runtime error terminating the script's execution.
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 or if the index out of bound 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.selection
The selection submodule provides access to selections made inside LDCad's editor.
Constructor
The constructor is used to create a new selection object.
If no parameters are given it will default to the current editing session selection. If no session is active it will default to the unlinked state.
It is also allowed to supply another selection object as the only parameter, in order to copy that one.
local mySel=ldc.selection()
The above example will create a selection object named 'mySel'. Afterwards the mySel variable can be used to manipulate the linked selection. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
mySel:inverse()
Do note an unlinked selection object will cause a runtime error when you try to use it in a way which requires it to be linked.
Group functions
Inside LDCad a selection is just a special kind of group. As a result a selection object includes all the functions of a group object, see above for their details.
Do note some of them might behave slightly different or do nothing. This is the result of limitations selection groups impose on normal group behaviour.
add
add is used to add items to the currently linked selection. It has a single optional parameter which accepts a ldc.srcLine or ldc.refLine object.
The supplied line object must be contained in the same subfile as the one the linked selection session is managing. If the given line is not part of the same subfile a run time error will terminated the script's execution.
If no parameter is given all lines of the associated subfile will be added/selected.
The function returns a boolean indicating if the selection has been changed or not.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
remove
add is used to remove items from the currently linked selection. It has a single optional parameter which accepts a ldc.srcLine or ldc.refLine object.
The supplied line object must be contained in the same subfile as the one the linked selection session is managing. If the given line is not part of the same subfile a run time error will terminated the script's execution.
If no parameter is given all currently selected lines will be deselected, clearing the selection.
The function returns a boolean indicating if the selection has been changed or not.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
inverse
inverse performs an 'inverse' action on the currently linked selection. This will result in deselecting the current content and add everything that was previously unselected.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
getSession
getSession returns a new session object linked to the LDCad editing session the currently linked selection belongs to.
If the object is unlinked calling this function will cause a runtime error terminating the script's execution.
ldc.animation
The animation submodule is used to create and manipulate LDCad animations.
ldc.animation.getCurrent
getCurrent returns a new animation object linked to the currently playing animation. It will return an unlinked animation object if no animation is playing.
Constructor
an animation object is used to access and or create a specific animation inside LDCad. It can be created using its constructor, 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')
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 its clone function.
It will return a new animation object containing identical data.
This function has no additional parameters.
register
register is used to create (or link to) an (different) 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 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
hasSameLink
hasSameLink takes a single animation object as a parameter and returns a boolean indicating if that object is linked to the same LDCad animation or not.
getName
getName returns the name of the current linked animation, if none is currently linked a empty string will be returned.
This function has no additional parameters.
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.
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.
getFrameNr
getFrameNr returns the currently active frame of the linked animation. Do note contrary to normal lua behaviour 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 "numberOfFrames-1" 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.
getCameraCount
todo
setCameraCount
todo
addCamera
todo
getCamera
todo
setCamera
todo
setOutputCamera
todo
getOutputCamera
todo
getLightCount
todo
setLightCount
todo
addLight
todo
getLight
todo
setLight
todo
isPOVRayExport
todo
isInteractive
todo
newControl
todo
getControlCount
todo
getControl
todo
ldc.camera
The camera submodule is used to create and access camera objects.
Constructor
a camera object is used to access a specific camera. It can be created using its constructor, like for example:
local myCam=ldc.camera()
The myCam variable can then be used to manipulate a single camera. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
myCam:setLookAt(0, 0, 0)
todo
It's also permitted to supply another camera 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 camera object you must use its clone function.
It will return a new camera object containing identical data.
This function has no additional parameters.
isLinked
todo
hasSameLink
hasSameLink takes a single camera object as a parameter and returns a boolean indicating if that object is linked to the same animation camera or not.
setLookAt
todo
getLookAt
todo
setEye
todo
getEye
todo
setPos
todo
getPos
todo
setOri
todo
getOri
todo
setPosOri
todo
getPosOri
todo
setHorFOV
todo
getHorFOV
todo
setDistance
todo
getDistance
todo
setRoll
todo
getRoll
todo
setTilt
todo
getTilt
todo
setYaw
todo
getYaw
todo
setMode
todo
getMode
todo
setFirstPerson
todo
setThirdPerson
todo
setTwoPoint
todo
setAdvanced
todo
isFirstPerson
todo
isThirdPerson
todo
isTwoPoint
todo
isAdvanced
todo
apply
todo
getIndex
todo
ldc.light
The light submodule is used to create and access light objects.
Constructor
a light object is used to access a specific light. It can be created using its constructor, like for example:
local myLight=ldc.light()
The myLight variable can then be used to manipulate a single light. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
myLight:setPos(0, -500, 0)
todo
It's also permitted to supply another light 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 light object you must use its clone function.
It will return a new light object containing identical data.
This function has no additional parameters.
isLinked
todo
hasSameLink
hasSameLink takes a single light object as a parameter and returns a boolean indicating if that object is linked to the same light or not.
getKind
todo
setKind
todo
getEnabled
todo
setEnabled
todo
getCastShadows
todo
setCastShadows
todo
getPos
todo
setPos
todo
getPointAt
todo
setPointAt
todo
getRadius
todo
setRadius
todo
getFalloff
todo
setFalloff
todo
getColor
todo
setColor
todo
setPoint
todo
setSpot
todo
setParallel
todo
ldc.control
The control submodule is used to create and access control objects.
ldc.control.getCurrent
todo
Constructor
A control object is used to create interactive hotspots inside an animation. It can be created using its constructor, like for example:
local myCtrl=ldc.control()
The myCtrl variable can then be used to manipulate a single control. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
myCtrl:setEvent('up', 'myUpEventHandler')
todo
Do note an unlinked control 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 control 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 control object you must use its clone function.
It will return a new control object containing identical data.
This function has no additional parameters.
isLinked
todo
hasSameLink
hasSameLink takes a single control object as a parameter and returns a boolean indicating if that object is linked to the same LDCad animation control or not.
getEnabled
todo
setEnabled
todo
setEvent
todo
addItem
todo
getGroup
todo
getIndex
todo
ldc.event
The event submodule is used to query things like mouse and keyboard states while inside a LDCad callback function.
ldc.event.getCurrent
getCurrent returns a new event object representing the current event state.
Constructor
An event object contains all things related to a single event, it will default to the current event state. It can be created using its constructor, like:
local myEvent=ldc.event()
The myEvent variable can then be used to access variables associated with a single event. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
print(myEvent:isKeyBoardEvent())
It's also permitted to supply another control 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 event object you must use its clone function.
It will return a new event object containing identical data.
This function has no additional parameters.
isMouseEvent
isMouseEvent returns a boolean indicating if the event is related to of a mouse interaction oriented callback or not.
isMouseFocusEvent
isMouseFocusEvent returns a boolean indicating if the event is related control focus change ('enter','leave') callback or not.
isMouseEnterEvent
isMouseEnterEvent returns a boolean indicating if the event is related to a control:setEvent('enter') callback or not.
isMouseLeaveEvent
isMouseLeaveEvent returns a boolean indicating if the event is related to a control:setEvent('leave') callback or not.
isMouseDownEvent
isMouseDownEvent returns a boolean indicating if the event is related to a control:setEvent('down') callback or not.
isMouseUpEvent
isMouseUpEvent returns a boolean indicating if the event is related to a control:setEvent('up') callback or not.
isMouseMoveEvent
isMouseMoveEvent returns a boolean indicating if the event is related to a control:setEvent('move') callback or not.
isKeyBoardEvent
isKeyBoardEvent returns a boolean indicating if the event is related to of a keyboard interaction oriented callback or not.
isKeyEvent
isKeyEvent returns a boolean indicating if the event is related to a input.captureKey callback or not.
isCharEvent
isCharEvent returns a boolean indicating if the event is related to a input.captureChars callback or not.
getControl
getControl returns the control object related to this event.
getMousePos
getMousePos returns a new vector object containing the mouse position at the time this event was fired.
Do note this is a 3D mouse position, not the screen cursor location. It indicates the spot the mouse 'touches' on the related control hotspot in absolute space.
getKeyID
getKeyID returns an integer indicating the keyID related to this event.
getKeyChar
getKeyChar returns a single character string indicating the keyboard character related to this event.
ldc.input
The input submodule is used to setup and manipulate mouse and keyboard related features for use during an interactive animation.
ldc.input.captureKey
todo
ldc.input.captureChars
todo
ldc.input.redirectIsActive
todo
ldc.input.startPlaneRedirect
todo
ldc.input.endRedirect
todo
ldc.dialog
The dialog submodule is used create and show interactive dialogs to the user of the script. These dialogs can then be used to aks the user a question or show them a message.
ldc.dialog.runMessage
todo
ldc.dialog.runInput
todo
ldc.dialog.runConfirm
todo
ldc.dialog.runChoice
todo
Constructor
A dialog object is used to setup a reusable dialog. It's created using a constructor, like so:
local myDlg=ldc.dialog()
The myDlg variable can then be used to manipulate the associated dialog. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
print(myDlg:setCaption('Hello there!'))
todo
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 dialog object you must use its clone function.
It will return a new dialog object containing identical data.
This function has no additional parameters.
setCaption
todo
getCaption
todo
setMessage
todo
getMessage
todo
getValue
todo
setValue
todo
setChoices
todo
getChoices
todo
runMessage
todo
runInput
todo
runConfirm
todo
runChoice
todo
ldc.session
The session submodule is used to access LDCad editing session related things.
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.
Constructor
A session object is used to access a specific LDCad editing session. It's created using a 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())
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 its clone function.
It will return a new session object containing identical data.
This 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
hasSameLink
hasSameLink takes a single session object as a parameter and returns a boolean indicating if that object is linked to the same LDCad editing session or not.
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
getMainSubfile
todo
getInsSubfile
todo
getSelection
todo
getCurStepNr
todo
setCurStepNr
todo
ldc.view
The view submodule is used to access and manipulate a LDCad 3D views.
ldc.view.getCurrent
todo
ldc.view.getCount
todo
Constructor
A view object is used to access a specific view. It's created using a constructor, like for example:
local myView=ldc.view()
The myView variable can then be used to manipulate a specifc view inside LDCad. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
print(myView:())
todo
Do note an unlinked action 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 action 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 view object you must use its clone function.
It will return a new view object containing identical data.
This function has no additional parameters.
link
todo
isLinked
todo
hasSameLink
hasSameLink takes a single view object as a parameter and returns a boolean indicating if that object is linked to the same LDCad editing view or not.
getIndex
todo
getCamera
todo
setCamera
todo
ldc.partBin
The partBin object is used to manipulate the LDCad partBin. There can be multiple windows and views displaying the partBin content but there is only one collection of bin items. As a result this object has no constructor and only static functions.
partBin.getWorkPart
todo
partBin.setWorkPart
todo
ldc.colorBin
The colorBin object is used to manipulate the LDCad colorBin. There can be multiple windows and views displaying the colorBin content but there is only one collection of bin items. As a result this object has no constructor and only static functions.
colorBin.getWorkColor
todo
colorBin.setWorkColor
todo
ldc.action
The action submodule is used to access and use LDCad actions. These are all the things you can assign hotkeys to in the editor itself.
Constructor
An action object is used to access a specific LDCad action. It's created using a constructor, like for example:
local myAction=ldc.action('editSes_selAll')
The myAction variable can then be used to execute and or query the state of the linked action. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
myAction:run()
todo
Do note an unlinked action 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 action 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 action object you must use its clone function.
It will return a new action object containing identical data.
This function has no additional parameters.
link
todo
isLinked
todo
hasSameLink
hasSameLink takes a single action object as a parameter and returns a boolean indicating if that object is linked to the same LDCad action or not.
isEnabled
todo
run
todo
getName
todo
getCaption
todo
getHint
todo
ldc.macro
The macro submodule is used to create and use LDCad macros. Macro's can be used to automate certain tasks and or model manipulations.
ldc.macro.getCurrent
todo
Constructor
A macro object is used to access a specific macro. It's created using a constructor, like for example:
local myMacro=ldc.macro('My macro')
The myMacro variable can then be used to manipulate a specifc macro inside LDCad. This is done through a collection of functions you must always access using the lua short hand ':' method, e.g.
print(myMacro:isLinked())
todo
Do note an unlinked macro 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 macro 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 macro object you must use its clone function.
It will return a new macro object containing identical data.
This function has no additional parameters.
register
todo
link
todo
isLinked
todo
hasSameLink
hasSameLink takes a single macro object as a parameter and returns a boolean indicating if that object is linked to the same LDCad macro or not.
getID
todo
getName
todo
setHint
todo
getHint
todo
setEvent
todo