CinematX.lua

'NOTE: This page is currently under construction. Apologies for any messiness and incomplete/outdated information!'

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:


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

Setup
In order to set up a level to work with cinematX, you'll need to add this line at top of your lunadll.lua file:

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.