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
cinematX will be included with LunaLua when it is finished. Until then, the latest version of cinematX can be downloaded 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. 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.

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

cinematX.playerNameASXT

cinematX.playerNameASXT2

cinematX.playerNameSMBX

cinematX.beginRace (otherActor, startX, endX, raceFunc, loseFunc, winFunc)

cinematX.beginBattle (name, hits, barType, func)

cinematX.getBattleProgress

cinematX.getBattleProgressPercent

cinematX.setBattleProgress (amount)

cinematX.winBattle

cinematX.loseBattle

cinematX.defineQuest (questKey, missionName, missionText)

cinematX.displayQuestState (questKey)

cinematX.initQuest (questKey)

cinematX.beginQuest (questKey)

cinematX.finishQuest (questKey)

cinematX.isQuestStarted (questKey)

cinematX.isQuestFinished (questKey)

cinematX.endCutscene

cinematX.changeSceneMode (sceneModeType)

Troubleshooting FAQ
[This section is particularly incomplete at the moment!]

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
A coroutine may stop at a function if one or more of the parameters is of the wrong type. Check to make sure you don't have a string where a number or Actor reference should be.