cinematX.lua

This is the archived page of the old LunaLua documentation The rest of LunaLua related articles in this wiki contain a lot of outdated documentation preserved for historical purposes and may be used with legacy versions of the LunaLua. Please visit the SMBX2 Documentation Page to access the latest documentation for the LunaLua scripting system of the SMBX2 Project. Adding LunaLua contents into this Wiki is not advised.

WARNING: This library is EXTREMELY deprecated and outdated!! See actorclass and other related SMBX2 Libraries instead. No, like, seriously, don't use it. It's broken and buggy and we're working on better libraries to replace all of its functionality!

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:

    cinematX = loadSharedAPI("cinematX")

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:

cinematX = loadSharedAPI("cinematX")

cinematX.configExt ({"hudBox"=true, "imageUi"=false, "textbloxSub"=false})

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:

cinematX.actorCriteria = function (myNPC)
   if myNPC.id == NPCID.SIGN then
      return false
   else
      return true
   end
end

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:

function scene_example ()
    cinematX.startDialogExt ("Hello!  This is a test!", {"actor" = nil, "name" = "Paul"})
    cinematX.waitForDialog()

    cinematX.waitSeconds (1)
    
    cinematX.startDialogExt ("Test number two.", {"actor" = nil, "name" = "Paul"})
    cinematX.waitForDialog()

    cinematX.endCutscene ()
end

cinematX coroutine functions
Type	Function/Field	Return values/Value type	Description
function	waitSignal (String signal)	nil	Pauses a coroutine until the given signal is sent.
function	signal (String signal)	nil	Sends a signal for stopping a waitSignal.
function	yield ()	nil	Pauses a coroutine for a single frame.
function	waitFrames (int frames)	nil	Pauses a coroutine for the given number of frames.
function	waitSeconds (double seconds)	nil	Pauses a coroutine for the given number of seconds.
function	waitForDialog ()	nil	Pauses a coroutine until the current dialog subtitle has finished.
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	endCutscene ()	nil	Ends the current cutscene.

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

cinematX
Type	Function/Field	Return values/Value type	Description
function	changeSceneMode (cinematX Scene Mode mode)	nil	Switches to the specified scene mode.

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
Type	Function/Field	Return values/Value type	Description
function	changeSceneMode (cinematX Scene Mode mode)	nil	Switches to the specified scene mode.
function	configDialog (boolean skippable, boolean needInput, double textSpeed)	nil	Changes dialogue behavior.
function	startDialog (Actor speakerActor, String name, String text, double textTime, double speakTime, String sound)	nil	Triggers a line of dialogue.
function	getResponse ()	boolean	Returns the response the player gave to a yes/no question.
function	beginBattle (String name, int hits, int barType, function func)	nil	Triggers a boss battle with the given settings.
function	getBattleProgressPercent ()	int	Returns the boss HP as a value between 0 and 1, with 0 being full health and 1 equating to empty health.
function	beginRace (Actor otherActor, float startX, float endX, function raceFunc, function loseFunc, function winFunc)	nil	Triggers a race against another Actor from startX to endX.
variable	playerNameSMBX	String	Returns the name of the current player character ("Mario", "Luigi", "Peach", "Toad" or "Link").
variable	playerNameASXT	String	Returns the name of the current player character for the A2XT devkit ("Demo", "Iris", "Kood", "raocow" or "Sheath").
variable	playerNameASXT2	String	Returns an alternate set of player character names for the A2XT devkit ("Nevada", "Pily", "Alt P3", "Alt P4" or "Broadsword").

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.

Troubleshooting FAQ

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.