Lua Cutscenes Recipe Book

This is a recipe-book intended to provide an overview of everything you might want to do with Lua Cutscenes, in approximate order of complexity. All code snippets here are free to use in your cutscenes and are released into the public domain.

This page is currently a work-in-progress!

Warm-up: Cutscene structure

A cutscene is a .lua file placed within your packaged mod; its path should usually be Assets/yournickname/yourmodname/cutscenename.lua, for which you would enter Assets/yournickname/yourmodname/cutscenename into an entity's parameters.

When something happens (like the player talking to a Lua Talker or entering a Lua Cutscene Trigger), one of the functions in that lua file with be run (provided it exists). All cutscenes can define the following functions:

function onBegin()
  -- cutscene code goes here, and will be run when the cutscene begins
  -- this one gets to do things that take time (more on that later!)
end

function onEnd(room, wasSkipped)
  -- cutscene code goes here, and will be run when the cutscene ends
  -- `room` is the current room, and `wasSkipped` is `true` if the cutscene was skipped
  -- this one can't do things that take time
end

Additionally, triggers can define these (none of them can do things that take time):

function onEnter(player)
  -- code here is run when the player enters the trigger
end

function onLeave(player)
  -- code here is run when the player leaves the trigger
end

function onStay(player)
  -- code here is run every frame while the player is touching the trigger
end

You can define functions other than these, and call them whenever you want, in order to decrease repetition in your code.

Helper functions

Lua Cutscenes provides many helper functions that let you do things in your cutscenes; a full list is available here, and the lua code those functions are written in is here.

To call a function, for example setCameraOffset, you write the name of the function (you don't need to put helpers), followed by the list of arguments you want to give it, like this:

function onBegin()
  -- set the camera offset to 0.5 in the x direction
  setCameraOffset(0.5)

  -- wait for 1 second
  wait(1)

  -- set the camera offset to 0.2 in the x direction, and -0.3 in the y direction
  setCameraOffset(0.2, -0.3)

  -- wait again, for 1.5 seconds this time
  wait(1.5)

  -- make some variables to use (generally, pick an alphanumeric name without spaces, and starting with a letter):
  offset_x = -1
  offset_y = 0.1
  -- then use them:
  setCameraOffset(offset_x, offset_y)
end

Note that in the documentation this function is written as helpers.setCameraOffset(x[, y]); the square brackets mean that that argument is optional.

Accessing and using C# objects

require

You can get a C# class like this:

local calc = require("#monocle.calc")

It's good practice to have all your require statements at the top of your cutscene file, outside of any functions. Some of these classes are already imported by the helper functions (see here)

Once you've done that, you can then call methods on the class:

local calc = require("#monocle.calc")

function onBegin()
  -- output into the log the size of this angle, in radians:
  --            . (1, 1)
  --           /
  --          /
  --         /      <-- here
  -- (0, 0) .----
  log(calc.Angle(vector2(1, 1))
end

You can also get static fields on classes:

local calc = require("#monocle.calc")

function onBegin()
  -- how many radians are in a circle?
  log(calc.Circle)
end

You can find a list of all the methods and fields of a class by decompiling it or looking at its metadata in an IDE.

Static vs. Instance methods / fields

When getting values or calling methods on C# objects, it's important to know about the differences between static and instance methods. A static method or field exists on the class, like calc.Circle or csharpVector2.Lerp(start_pos, end_pos, amount), while an instance method or field exists on some instance of that class, like player.Position or level:GetSpawnPoint(pos). In Lua, an instance method is called with instance:methodname() rather than instance.methodname().

Coroutines: What does it mean to take time to do something?

await

Zooming the camera

Delegates

Doing multiple things at once

Adding entities to the level