CinematX Actor (class)

This class provides fields/functions for managing Actors with the CinematX.lua API.

Actors extend NPCs and make it easier to access individual NPCs and give them unique behavior. By default, an actor is created for every NPC as well as the player (accessible via the cinematX.playerActor constant).

Message Tags


Each NPC's Actor is assigned unique traits and behaviors based on tags specified in the NPC's message text. Note that in order for this to work, cinematX must be configured to override the SMBX NPC message system.

Add one or more of the following tags inside curly brackets:


 * key=# (a string index that you can use to reference the Actor within your LunaLua code via getActorFromKey)
 * name=#  (the name displayed in the interaction prompt when approaching the NPC)
 * verb=#  (the term used for interacting with the NPC in the interaction prompt -- i.e. talk, read, push, etc.)
 * 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, name=Paul, verb=annoy, routine=cutscene_TestQuest}

If you want to be able to reference an NPC Actor without letting the player interact with them, just define the key and nothing else.

{key=goopa3}

Combat
NOTE: All of this functionality is only available in 0.0.8 and up!

Grabbing and Carrying
NOTE: All of this functionality is only available in 0.0.8 and up!

Relational Functions
Actor:forwardOffsetX (float amount) Actor:topOffsetY (float amount) Actor:bottomOffsetY (float amount) Actor:getCenterX Actor:getCenterY Actor:closestNPC (int id) Actor:closestBlock (int id)

Animation
cinematX can override the animation behavior of an NPC to allow for more expressive and nuanced animations. To do so, you'll need to do the following:


 * Extend the NPC's sprite sheet accordingly, including frames for multiple different animations
 * Create an animation data table for the NPC or a .anim file
 * Assign the data table to one or more actors using Actor:overrideAnimation in the onLoop function of your lunadll.lua file

cinematX Sprite Sheets
To truly take advantage of cinematX's animation system, you should include the frames of every animation your NPC will use. However, this can result in extremely tall images that can be cumbersome to work with. In addition, a minor quirk in the way cinematX limits an NPC's animation may cause visual oddities if not accounted for. As such, here are some tips for organizing and formatting your sprite sheet:


 * cinematX cannot flip images manually and thus requires separate frames for left- and right-facing animations. Because of this, you should expect the final image to be double the combined height of all animations.
 * If image size or the total number of frames isn't a concern, it may help to separate different animations with a blank frame. On the other hand, you can overlap animations or use the same animation for multiple states to minimize your frame count (i.e. walking and running both use frames 4-7, and idle uses frames 8-12 while talk consists of 10-16).
 * As mentioned above, a quirk of cinematX's animation system is that it sometimes displays one frame over the upper bound for a split second. To compensate for this, you should add a duplicate of the first frame in the animation after the last frame (i.e. an animation that goes 4-5-6 should be included in the sheet as 4-5-6-7 where 7 is a copy of 4).

Animation Tables
Animation tables are simple Lua arrays that specify which frames of the NPC's sprite sheet belong to which animation states. The first index stores the total number of frames in the animation for each direction and following indexes contain the first and last frames of a given state, stored as a string with a dash between the two values.

Here's a list of all existing animation state constants. (*) indicates constants unique to 0.0.8 and above.


 * cinematX.ANIMSTATE_IDLE
 * cinematX.ANIMSTATE_TALK
 * cinematX.ANIMSTATE_TALK1 through TALK7
 * cinematX.ANIMSTATE_WALK
 * cinematX.ANIMSTATE_RUN
 * cinematX.ANIMSTATE_JUMP
 * cinematX.ANIMSTATE_FALL
 * cinematX.ANIMSTATE_HURT (*)
 * cinematX.ANIMSTATE_STUN (*)
 * cinematX.ANIMSTATE_DEFEAT
 * cinematX.ANIMSTATE_ATTACK
 * cinematX.ANIMSTATE_ATTACK1 through ATTACK7
 * cinematX.ANIMSTATE_GRAB (*)
 * cinematX.ANIMSTATE_GRABWALK (*)
 * cinematX.ANIMSTATE_GRABRUN (*)
 * cinematX.ANIMSTATE_GRABJUMP (*)
 * cinematX.ANIMSTATE_GRABFALL (*)

Animation Files
As of version 0.0.8d, you may now import .anim files in place of using hard-coded animation tables. These can be written in any basic text editor, such as notepad, and use a format similar to NPC config files. The keywords are the same as the suffixes of the animation state constants, but in lowercase.

The readAnimData(path) function imports the specified file and return a properly-formatted table.

Required States
A number of states must be specified in an animation data table as these states are automatically applied to overridden NPCs by cinematX. All other constants are for convenience, and any states defined using those constants must be applied manually with Actor:setAnimState. Because these states correlate to numbers, numbers above the predefined constants can be used for additional states.

In earlier versions of cinematX, the required states were limited to Idle, Talk, Walk, Run, Jump and Fall. New functionality in version 0.0.8, however, required additional states, so the .anim parser automatically derives unspecified states from related ones (Fall from Jump, Run from Walk, etc). Because of this, only the Idle state is strictly needed in 0.0.8, but it is recommended that you specify frame bounds for every state except the Talk# and Attack# states.

Interaction
Actor.isInteractive = false Actor.sceneString = "" Actor.routineString = "" Actor.messagePointer = "" Actor.messageString = "" Actor.nameString = "" Actor.wordBubbleIcon = nil Actor.messageIsNew = true

Miscellaneous
Actor:saveState (slot) Actor:loadState (slot)

Actor.helloVoice = "" Actor.goodbyeVoice = ""