CinematX.lua

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

The cinematX library is a framework for adding NPC interactions, cutscenes, boss battles, and other dynamic sequences and content to Super Mario Bros X.

Important Notes
cinematX requires the use of custom NPC Unique ID Numbers (UIDs) that it writes into the data of every NPC (not just cinematX actors). Currently, the memory offset used for this is 0x08. It is not recommended to write extra data to NPCs, and instead to use these UIDs to control extra behaviour on a per-NPC basis. Writing data to NPCs that does not already exist in SMBX can be dangerous, and it is not recommended to try it unless you are certain of what you are doing. You can instead store any extra data you need in Lua tables, indexed by cinematX UIDs.

These UIDs can be accessed using the Actor.uid field for cinematX actors, or by using npc:mem(cinematX.ID_MEM,FIELD_WORD) for other NPCs.

Installation
The latest stable version of cinematX is included with LunaLua. You can download the latest unstable version from the Github repository.

To install cinematX manually, simply place cinematX.lua and the folder named cinematX into the LuaScriptsLib folder.

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 line allows cinematX and lunadll.lua to communicate with each other.

You may optionally call the cinematX.config(toggleOverrideMsg, showDebug) function following the loadSharedAPI statement to toggle the following features of cinematX:


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

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 (is mistakenly set to true in v0.0.3)

Filter Function
In some cases you'll want to limit which NPCs have actors generated for them (see the Actors section for more detail). You can do so by adding the actorCriteria function to your 'lunadll.lua' file. actorCriteria must have one parameter -- an SMBX NPC instance -- and return true (the NPC gets an Actor) or false (no Actor is generated). The actual conditions in which a given NPC qualifies are up to you.

Example code:

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

Coroutine Basics
cinematX makes use of special functions called coroutines to make programming cutscenes, boss battles and other dynamic/scripted sequences simpler. 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. It is also possible, though not recommended, to use the changeSceneMode function to manually 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.

Code Documentation
[This section is particularly incomplete at the moment!]

cinematX.defineQuest (questKey, missionName, missionText)

cinematX.displayQuestState (questKey)

cinematX.initQuest (questKey)

cinematX.beginQuest (questKey)

cinematX.finishQuest (questKey)

cinematX.isQuestStarted (questKey)

cinematX.isQuestFinished (questKey)

Performance issues
If your level contains a lot of NPCs, try using the filter function to limit which NPCs have actors generated for them.

NPC's tags aren't working correctly at runtime
If your NPC displays a default SMBX message containing its' tags, check the following:


 * Is cinematX.config set to override SMBX messages?
 * Is the NPC excluded by your filter function?
 * Are the tags formatted correctly?

A cutscene/coroutine stops processing after a certain point
cinematX will abort a coroutine if it cannot recognize the function or its' parameters. Check the following:


 * Did you spell the function correctly?
 * Are all the parameters of the correct type?
 * Are all variables or references to external resources valid?

Some NPCs are showing up as white boxes
This is a hardware-related issue with the OpenGL renderer; your GPU has a set texture limit that can range from 2048 to 16,384 pixels, and if an NPC's sprite sheet exceeds that limit it will fail to display their sprite. A future update to the renderer should fix this problem.

Generators
Unfortunately, cinematX does not currently work well with generators due to the way they manage their NPC references. For the time being, you can use this workaround:


 * Use NPC.spawn to spawn a new NPC and store its' reference in a variable
 * On the following frame, use the NPC's UID (stored in the cinematX.ID_MEM address of the NPC) to access the Actor from the cinematX.indexedActors[uid] array.
 * Set the properties of the Actor accordingly

The player is stuck in place or moving slowly after a cutscene
In older versions of cinematX, using walkToX on the player Actor during the cutscene will cause this behavior and has to be manually reset by using walk(0). This will be fixed in 0.0.8.