CinematX.lua

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). Prior to v0.0.8 the memory offset used for this was 0x08, now 0x76 is used instead. 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 development version from the Github repository.

To install cinematX manually, merge the package into your LuaScriptsLib folder.

As of v0.0.8, cinematX has the following dependencies:


 * textblox.lua
 * GraphX.lua
 * Eventu.lua
 * Colliders.lua
 * Npcconfig.lua
 * Inputs.lua

All of these libraries are included in the repository; textblox and graphX are guaranteed to be fully up-to-date as they are officially part of the cinematX suite, but it is recommended that you install the latest versions of the other libraries manually.

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.configExt function following the loadSharedAPI statement to toggle different features of cinematX (see Configuring and customizing cinematX for more information)

Configuring and customizing cinematX
Various aspects of cinematX can be configured and customized to suit the needs of a level or episode.

Config function
After loading cinematX, you may toggle various features of cinematX through a config function. Previously, this was cinematX.config (toggleOverrideMsg, showDebug, useHUDBox, useTransitions, oglUI, sceneFreeze), but as of v0.0.8i cinematX.config is deprecated in favor of cinematX.configExt (settings), where settings is a table of named arguments. For example:

The following settings are available:


 * "overrideNpcText": If true, cinematX will override the default SMBX NPC message system (see Extending NPCs below.) True by default
 * "debug": If true, you can view debug information and access the cinematX console for entering cheats and stuff. False by default (is mistakenly set to true in v0.0.3)
 * "hudBox": If true, a graphic is displayed behind the player's HUD. False by default
 * "sectionTransitions": If true, cinematX automatically fades the screen in and out when the player warps between sections (via door or pipe only). True by default
 * "imageUi": If true, cinematX defaults to image-based UI elements (see Images below for more info).  If false, cinematX will draw its' UI elements via graphX if your computer can use openGL. False by default
 * "cutsceneFreeze": If true, player object movement is disabled during cutscenes. True by default
 * "noActors": If true, the entire Actor system is disabled.  False by default
 * "textbloxSub": If true, cinematX uses textblox for its' dialogue subtitles; if false, cinematX reverts to the original implementation. True by default

config is still usable for backwards compatibility. The arguments for that function and their corresponding configExt settings are as follows:
 * toggleOverrideMsg: equivalent of "overrideNpcText"
 * showDebug: equivalent of "debug"
 * useHUDBox: equivalent of "hudBox"
 * useTransitions: equivalent of "sectionTransitions"
 * oglUI: the inverse of "imageUi"
 * sceneFreeze: the equivalent of "cutsceneFreeze"

Images
The images used by cinematX's GUI elements can be overridden on a per-episode or per-level basis like other SMBX graphics (though the replacements must be PNG files). They are located in the cinematX folder in LuaScriptsLib. The images and their respective uses are as follows:


 * blankimage.png: MODIFY/OVERRIDE THIS IMAGE AT YOUR OWN RISK. A leftover from earlier versions of cinematX based on deprecated rendering functions that is still used internally. Will be removed entirely in future versions.
 * bossHP_bg.png: The menu box used to display the boss' name and health bar during a battle.
 * bossHP_left.png: Currently unused.
 * bossHP_midE.png: Currently unused.
 * bossHP_midF.png: Currently unused.
 * bossHP_right.png: Currently unused.
 * font_subtitle.png: The sprite font used by cinematX's dialogue subtitles when "textbloxSub" = true.
 * fullScreenOverlay.png: ...Probably unused, will be removed in future versions.
 * hudBox.png: The infamous graphic displayed behind the HUD when "hudBox" = true.
 * letterBox.png: The screen overlay used when cinematX is in cutscene mode.
 * noglFade.png: MODIFY/OVERRIDE THIS IMAGE AT YOUR OWN RISK. The graphic used for fading transitions when "imageUi" = true.
 * npcIcon_*.png: The icons displayed over cinematX actors to convey the manner they can be interacted with to the player.
 * questBox.png: The menu box used to display quest information.
 * raceBg.png: The menu box used to display race progress.
 * raceFlag_*.png: The start and end flags on the race progress bar.
 * raceOpponent.png: The icon representing the opponent on the race progress bar.
 * raceOpponent.png: The icon representing the player on the race progress bar.

Filter Function
In some cases you may 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 Player characters and NPCs with Lua code.

Coroutines
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

Example code:

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.

Additional 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)

Tutorials
Any text or video tutorials for cinematX should be included here.

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.