Castle Library Reference

Actor Functions

castle.createActor("Blueprint name", x, y)

Creates a new actor using a name of a blueprint and the initial x and y position. This returns an actor variable that you can use to access actor properties or pass into other functions.

-- There must be a blueprint named Wall for this to work
local newActor = castle.createActor("Wall", 0, 0)
newActor.layout.rotation = 45

castle.destroyActor(Actor)

Destroys an actor.

-- destroy the current actor
castle.destroyActor(my)

-- create an actor and then destroy it
local newActor = castle.createActor("Wall", 0, 0)

...

castle.destroyActor(newActor)

castle.closestActorWithTag("tag")

Returns the closest actor with the tag, or nil.

local otherActor = castle.closestActorWithTag("wall")
otherActor.layout.rotation = 45

castle.actorsWithTag("tag")

Returns a table of all actors with the tag.

local otherActors = castle.actorsWithTag("wall")
for _, otherActor in ipairs(otherActors) do
    otherActor.layout.rotation = 45
end

castle.numActorsWithTag("tag")

Returns the number of actors with the tag.

castle.createTextBox("Message", action)

Creates a text box at the bottom of the screen. When the user taps the text box it disappears. action is optional and can be used to change the tap action -- currently the only supported value for action is "none" which causes the text box to not disappear on tap.

castle.getTouches()

Returns a table of currently active touches. Each element of the table is a table with the following fields:

• id: A number that is unique to this touch and is never used again, even after this touch ends.
• x: The x coordinate of the touch position in the scene.
• y: The x coordinate of the touch position in the scene.
• deltaX: The change in the x coordinate of the touch position in the last update.
• deltaY: The change in the x coordinate of the touch position in the last update.
• initialX: The x coordinate of the position of the touch when it began.
• initialY: The x coordinate of the position of the touch when it began.
• pressed: A boolean -- whether the touch began this update. This is true only for one update.
• released: A boolean -- whether the touch was released this update. This is true only for one update. After that update, the touch is no longer returned by castle.getTouches().
• duration: Time since the touch began in seconds.

The results are in order of oldest to latest touch.

For example, the following code prints to the log when a touch begins. This also works for all the touches in a multi-touch interaction.

local touches = castle.getTouches()
for _, touch in ipairs(touches) do
    if touch.pressed then
        print('touch: ' .. touch.x .. ', ' .. touch.y)
    end
end

castle.getTouch(touchId)

Returns a table with the same fields as each element of castle.getTouches(). The touchId parameter is optional -- if it is given, it returns the currently active touch with that id, or nil if no such touch is active. If touchId is not given the oldest active touch is returned.

For example, the following code prints to the log when a touch begins. This only handles the first touch in a multi-touch interaction.

local touch = castle.getTouch()
if touch.pressed then
    print('touch: ' .. touch.x .. ', ' .. touch.y)
end

castle.getActorsAtTouch(touchId)

Returns a table of all the actors overlap with the given touch.

castle.getDeviceTilt

Returns two values -- the x and y tilt of the device. These values change with the angle at which the user is holding the device.

For example, the following code lets the user control the actor by tilting the device. The actor is assumed to have dynamic motion.

function onUpdate(dt)
    local tiltX, tiltY = castle.getDeviceTilt()
    my.dynamicMotion.vx = tiltX
    my.dynamicMotion.vy = tiltY
end

castle.getDeviceTiltX

Returns the x tilt of the device.

castle.getDeviceTiltY

Returns the y tilt of the device.

Rule Functions

castle.sendTriggerMessage("Message string")

Triggers a rule that is listening for the script message event.

Select this in the triggers list:

Listen for a specific message

-- This will trigger the rule
castle.sendTriggerMessage("TestMessage")

Variable Functions

castle.updateTicker("ticker name", diff)

Update a ticker with a diff. Tickers might behave inconsistently if you set them with absolute values. If you try to reset the ticker to 1 like this:

castle.updateTicker("ticker", 1 - castle.getVariable("ticker"))

it might work in some cases but will probably fail if a lot of people join your deck at the same time.

Time Functions

castle.getTime()

Returns the time elapsed since the card started, in seconds.

castle.runAfterDelay(delay in seconds, function)

Runs the function after a delay.

castle.runAfterDelay(3.0, function()
  -- this will run after 3 seconds
  my.layout.x = 1
end)

See this tutorial for more examples.

castle.repeatAtInterval(interval in seconds, function)

Runs the function after a delay repeatedly.

castle.repeatAtInterval(3.0, function()
  -- this will run after 3 seconds, after 6 seconds, after 9 seconds, etc...
  my.layout.rotation = my.layout.rotation + 10
end)

See this tutorial for more examples.

castle.stopRepeat(handle from repeatAtInterval)

Stops a repeat created by castle.repeatAtInterval.

local repeatHandle = castle.repeatAtInterval(3.0, function()
  my.layout.rotation = my.layout.rotation + 10
end)

...

-- my.layout.rotation will stop updating once this is called
castle.stopRepeat(repeatHandle)

See this tutorial for more examples.

castle.sleep(seconds)

warning

We recommend not using this. It will prevent the rest of your script (including onUpdate and onMessage) from running until it returns. You can almost always perform the same logic with a combination of the other time functions.

Pauses the entire script for the number of seconds.

Card functions

castle.restartCard()

Restart the card.