Scripting examples

LDCad 1.4 and higher support scripting using lua in order to do some fun dynamic stuff with your LDraw models. The combination of basic lua and the collection of LDCad specific functions you can use through the ldc lua module opens op a very big world of possibilities.

Downside of this all is you need to invest some time and efforts to get started with it. As the best way to learn something is through examples I will try to provide a couple of bare essential examples of common tasks you would want to do using scripting in LDCad.

Creating animations

The main reason for adding scripting to LDCad was its use combined with making animations. Most available functions are therefore aimed at this goal.

Any animation in LDCad must be created through a script in order to be accessible in the GUI at all. To this end you can bind a lua script file to your model using its header dialog or by just drag and dropping the .lua file onto LDCad while the model is the current one.

Below is just about the minimum of things you have to do in such a script to get access to the animation mode for your model.

function register()
  local ani=ldc.animation('test animation')
  ani:setLength(10)
  ani:setEvent('frame', 'onFrame')
end

function onFrame()
  local ani=ldc.animation.getCurrent()
  --do per frame animation stuff
end

register()

The above script creates and register the animation "test animation", which it configures to have a playback time of 10 seconds. It then assigns the "onFrame" function to handle any per frame change dependencies.

Using this script with any model inside LDCad will enable the 'animation' tab in the session panel, which in turn will list 'test animation' as it currently active animation (you can register multiple animations in the same script).

While in animation mode playing the animation will cause the 'onFrame' function in your lua script to be called for every frame in the animation. It's up to the content of that function to position, rotate, color, show/hide all the stuff you want to do something with in your award winning movie.

The current script does absolutely nothing so lets modify the onFrame function so it continuously rotate the first brick in the model around its Y-axis while retaining its global absolute position during playback.

function onFrame()
  local ani=ldc.animation.getCurrent()
  local angle=ani:getFrameTime()/ani:getLength()*360
  local ref=ldc.subfile():getRef(1)
  local ori=ldc.matrix()
  ori:setRotate(angle, 0, 1, 0)
  ref:setOri(ori)
end

The function now calculates the current rotation angle based upon the current frame time (one rotation per playback length). It then builds a rotation matrix using that angle, and applies it to the LDraw reference line using only its orientation part.

Do note the brick will be rotating around it the y axis in its own neutral orientation. This is because the rotation matrix is applied absolutely in this case.

Now what

That's it for now, hopefully the above example will at least clarify the basics for you. In order to really master animation scripts you are best of just trying your self using the API reference and the example models supplied with LDCad who have animation scripts of their own (e.g. 5510.mpd, 5580.mpd or 4248.mpd). I tried to add as much useful comments to them as possible.