CinematX.lua

NOTE: This page is currently under construction. Apologies for the mess!

The cinematX library is an upcoming framework for NPC interactions, cutscenes, boss battles, and other dynamic sequences and content.

Installation

cinematX will be included with LunaLua when it is finished.

If you need to install it manually, however, follow these steps:

• Place cinematX.lua and the folder named cinematX into the LuaScriptsLib folder.

• Open up mainV2.lua and below loadSharedAPI("uservar") (line 154) add the following line:

    cinematX = loadSharedAPI("cinematX");

• (Optional) copy the cinematX_World folder to the worlds directory.

How to Use

Setup

In order to set up a level to work with cinematX, you'll need these two lines of code at top of your lunadll.lua file:

    package.path = package.path .. ";./worlds/NAME OF YOUR WORLD FOLDER/?.lua" .. ";./?.lua"
    cinematX = loadSharedAPI("cinematX")

This allows cinematX and lunadll.lua to communicate with each other.

Configuring cinematX

In the onLoad function of your lunadll.lua script, you may call the cinematX.config(toggleOverrideMsg, showDebug) function to toggle the following features of cinematX:

• toggleOverrideMsg: If true, cinematX will override the default SMBX NPC message system (see Extending NPCs below.) True by default
• showDebug: If true, you can access the cinematX console for entering cheats and stuff. False by default

Actors

An important feature of cinematX is the Actor wrapper class, which makes it easier to access and control NPCs with Lua code.

Message Tags

Using cinematX you can change the icon floating over a friendly NPC's head and define various other attributes about the NPC in its' message text. Note that in order for this to work, cinematX must be configured to override the SMBX NPC message system.

For each NPC that you want to extend, add one or more of the following tags inside curly brackets:

• key=# (a string index that you can use to reference the NPC within your LunaLua code via getNPCFromKey())
• icon=# (the icon that hovers over the NPC's head)
• routine=# (a coroutine to be called when the NPC is spoken to)
• scene=# (a coroutine to be called as a cutscene when the NPC is spoken to)

Example messages:

   {key=goopa1, icon=0, scene=cutscene_TestDialog}
   {key=goopa2, icon=1, scene=cutscene_TestQuest}

If you want to be able to reference an NPC without letting the player interact with them, just define a key and nothing else.

   {key=goopa3}

Coroutine Basics

Cutscenes, boss battles and other dynamic/scripted sequences are defined as special functions called coroutines. These functions can be paused and resumed to control timing and make it seem like you have multiple "threads" of code running simultaneously.

Coroutines in cinematX work like any other Lua functions with a few key differences:

• They cannot have any parameters
• They must be called via runCoroutine() or runCutscene()
• They can be paused until certain conditions are met using the waitFor__() functions

Scene Mode

When calling functions like runCutscene() and beginBattle(), the scene will automatically change to the appropriate state. You may also use the changeSceneMode() function to switch to one of the following states:
cinematX.SCENESTATE_PLAY
cinematX.SCENESTATE_CUTSCENE
cinematX.SCENESTATE_BATTLE

Boss Battles

cinematX has functions for managing boss battles and similar sequences, but the battles themselves are just coroutines like any other sequence.

Documentation

cinematX
Type	Function/Field	Return values/Value type	Description
type	freezePlayerInput ()	nil	Disables controller/keyboard input
type	unfreezePlayerInput ()	nil	Enables controller/keyboard input
function	waitForSeconds (double seconds)	nil	Pauses a coroutine for the given number of seconds.
function	waitForDialog ()	nil	Pauses a coroutine until there are no active dialogue boxes.
function	runCoroutine (function func)	nil	Triggers a coroutine.
function	runCutscene (function func)	nil	Triggers a coroutine as a cutscene (player input is disabled and letterboxing is displayed.)
function	configDialog (boolean skippable, boolean needInput, double textSpeed)	nil	Changes dialogue behavior.
function	startDialog (NPC speaker, String name, String text, double textTime, double textTime, String sound)	nil	Triggers a line of dialogue.
function	getResponse ()	boolean	Returns the response the player gave to a yes/no question.