CinematX Actor (class)

OUTDATED: This is an outdated class! actorclass is the successor! You can help Moondust Wiki by updating this page.

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 has 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}

Constructors/Reference

Actor class
Type	Function/Field	Return values/Value type	Description
Constructor	myActor = Actor.create(NPC or Player smbxObjRef, String smbxClass)	Actor	Construct a new Actor object. Use this constructor with extreme caution! Use the constant cinematX.playerActor and cinematX.getActorName_Key() instead.
function	cinematX.getActorFromKey(String key)	Actor	Returns the actor indexed under the given key (as specified by the "key" tag in the NPC's message, see "Message Tags" above.)
Field	Actor.smbxObjRef	NPC or Player	Returns the Actor's wrapped NPC or Player object.
Field	Actor.smbxClass	String	Returns "Player" or "NPC".

Movement

Actor class
Type	Function/Field	Return values/Value type	Description
function	Actor:getDirection()	DIR_LEFT or DIR_RIGHT	Returns the direction the NPC/Player is facing.
function	Actor:setDirection(int newDir)	nil	Change the direction the Actor is facing.
function	Actor:getX()	float	The X coordinate of the Actor.
function	Actor:setX(float newX)	nil	Change the X coordinate of the Actor.
function	Actor:getY()	float	The Y coordinate of the Actor.
function	Actor:setSpawnX(float newX)	nil	Change the X coordinate of the Actor's spawn point.
function	Actor:setSpawnY(float newY)	nil	Change the Y coordinate of the Actor's spawn point.
function	Actor:setSpawnToCurrent()	nil	Set the Actor's spawn point to its' current coordinates.
function	Actor:getY()	float	The Y coordinate of the Actor.
function	Actor:setY(float newY)	nil	Change the Y coordinate of the Actor.
function	Actor:getSpeedX()	float	The X-speed of the Actor.
function	Actor:setSpeedX(float newSpd)	nil	Change the X-speed of the Actor.
function	Actor:getSpeedY()	float	The Y-speed of the Actor.
function	Actor:setSpeedY(float newSpd)	nil	Change the Y-speed of the Actor.
function	Actor:follow(Actor/NPC/Block targetObj, float speed, float howClose, boolean shouldTeleport)	nil	Makes the actor begin following targetObj, walking at a max speed of speed until they are howClose pixels away from targetObj's x coordinate. If shouldTeleport is true, the Actor will teleport to targetObj if it gets too far away. (v0.0.8+)
function	Actor:followActor(Actor targetActor, float speed, float howClose, boolean shouldTeleport)	nil	Makes the actor begin following targetActor, walking at a max speed of speed until they are howClose pixels away from targetActor's x coordinate. If shouldTeleport is true, the Actor will teleport to targetActor if it gets too far away.
function	Actor:followNPC(NPC targetNPC, float speed, float howClose, boolean shouldTeleport)	nil	Makes the actor begin following targetNPC, walking at a max speed of speed until they are howClose pixels away from targetActor's x coordinate. If shouldTeleport is true, the Actor will teleport to targetActor if it gets too far away. (v0.0.8+)
function	Actor:followBlock(Block targetBlock, float speed, float howClose, boolean shouldTeleport)	nil	Makes the actor begin following targetActor, walking at a max speed of speed until they are howClose pixels away from targetActor's x coordinate. If shouldTeleport is true, the Actor will teleport to targetActor if it gets too far away. (v0.0.8+)
function	Actor:stopFollowing()	nil	Cancels the Actor's following behavior.
function	Actor:lookAtPlayer()	nil	Makes the Actor change direction to face the player.
function	Actor:lookAwayFromPlayer()	nil	Makes the Actor change direction to face away from the player.
function	Actor:turnAround()	nil	Flips the actor's facing direction.
function	Actor:walk(float speed)	nil	Makes the Actor start walking with the given speed; negative speeds make the Actor walk left, positive speeds make the Actor walk right.
function	Actor:walkForward(float speed)	nil	Makes the Actor start walking with the given speed in the direction they are currently facing.
function	Actor:walkToX(float destX, float speed)	nil	Makes the Actor walk to the given x coordinate with the given speed.
function	Actor:positionToTalk(Actor otherActor, float distance, bool shouldWait, float forcedDelay)	nil	Makes the Actor actor position themselves a given distance from otherActor and face them. (v0.0.8+)
function	Actor:jump(float strength)	nil	Makes the Actor jump with the given strength.
Field	Actor.isUnderwater	boolean	Returns whether the actor is underwater
Field	Actor.isResurfacing	boolean	Returns whether the actor is jumping out of the water
Field	Actor.shouldFacePlayer	boolean	If true, will always face in the direction of the player
Field	Actor.shouldDespawn	boolean	If false, prevents the Actor from despawning when outside of the viewport
Field	Actor.isDespawned	boolean	Returns true if the Actor has been despawned
Field	Actor.isDead	boolean	Returns true if the Actor's NPC has been killed
Field	Actor.actorToFollow	Actor	The target Actor to follow (Change this variable with caution; use followActor() and stopFollowing() instead.)
Field	Actor.shouldTeleportToTarget	boolean	If true, this Actor will teleport to the Actor stored in actorToFollow if it gets too far away.
Field	Actor.distanceToFollow	float	If following another Actor, the maximum distance to the target Actor at which this Actor stops moving.
Field	Actor.destWalkSpeed	float	The speed at which an Actor will follow another actor or move to a target destination.
Field	Actor.walkSpeed	float	The horizontal movement speed of the Actor (overrides the NPC's horizontal speed.)
Field	Actor.walkDestX	float	The target X coordinate that the Actor is set to move to.
Field	Actor.shouldWalktoDest	boolean	If true, the Actor will walk to the X position stored in walkDestX.

Combat

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

Actor class
Type	Function/Field	Return values/Value type	Description

Grabbing and Carrying

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

Actor class
Type	Function/Field	Return values/Value type	Description
Field	Actor.isCarrying	boolean	Returns true if the Actor is currently carrying an NPC.
Field	Actor.carryStyle	int	Determines whether the grabbed NPC/block is held in front of the Actor (0) or above the Actor's head (1).
Field	Actor.carriedNPC	boolean	Returns the NPC currently being carried by the Actor (nil if none).
function	Actor:grabNPC(NPC npcRef, int priority)	nil	Makes the Actor attempt to grab npcRef. If the player or another Actor is currently holding npcRef, the attempt to grab only succeeds if priority is equal or greater than the other's carryPriority (the player's priority is 10)
function	Actor:dropCarried()	nil	Makes the Actor drop any NPC is currently carrying.
function	Actor:throwCarried(float forwardSpeed, float upSpeed)	nil	Makes the Actor throw its' carried NPC with the given forward and upward speeds.

Relational Functions

Actor class
Type	Function/Field	Return values/Value type	Description
function	Actor:getScreenX()	float	Returns the Actor's X coordinate relative to the viewport.
function	Actor:getScreenY()	float	Returns the Actor's Y coordinate relative to the viewport.
function	Actor:isOnScreen()	boolean	Returns whether the Actor is inside the viewport.
function	Actor:relativeX(float posX)	float	Returns the Actor's X coordinate relative to another X coordinate.
function	Actor:relativeY(float posY)	float	Returns the Actor's Y coordinate relative to another Y coordinate.
function	Actor:distanceX(float posX)	float	Returns the horizontal distance between the Actor's X coordinate and another X coordinate.
function	Actor:distanceY(float posY)	float	Returns the vertical distance between the Actor's Y coordinate and another Y coordinate.
function	Actor:distanceDestX(float posY)	float	Returns the difference between the Actor's X coordinate and the X coordinate they are walking to.
function	Actor:relativeActorX(Actor targetActor)	float	Returns the Actor's X coordinate relative to another actor.
function	Actor:relativeActorY(Actor targetActor)	float	Returns the Actor's Y coordinate relative to another actor.
function	Actor:distanceActorX(Actor targetActor)	float	Returns the horizontal distance between the two actors.
function	Actor:distanceActorY(Actor targetActor)	float	Returns the vertical distance between the two actors.
function	Actor:distancePos(float xPos, float yPos)	float	Returns the diagonal distance between the Actor and the given point.
function	Actor:distanceActor(Actor targetActor)	float	Returns the diagonal distance between the two actors.
function	Actor:dirToX(float xPos)	int	Returns either DIR_LEFT or DIR_RIGHT.
function	Actor:dirToActorX(Actor targetActor)	int	Returns either DIR_LEFT or DIR_RIGHT.

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 the following indexes contain the first and last frames of a given state, stored as a string with a dash between the two values.

    animData_Example = {}
    animData_Example[cinematX.ANIMSTATE_NUMFRAMES] = 32
    animData_Example[cinematX.ANIMSTATE_IDLE] = "0-0"
    animData_Example[cinematX.ANIMSTATE_TALK] = "1-2"
    animData_Example[cinematX.ANIMSTATE_WALK] = "4-5"
    animData_Example[cinematX.ANIMSTATE_RUN] = "4-5"
    animData_Example[cinematX.ANIMSTATE_JUMP] = "7-7"
    animData_Example[cinematX.ANIMSTATE_FALL] = "9-9"
    animData_Example[cinematX.ANIMSTATE_DEFEAT] = "21-21"
    animData_Example[cinematX.ANIMSTATE_ATTACK] = "11-11"

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.

frames=40
idle=4-9
talk=15-15
walk=16-17
run=20-23
jump=26-26
fall=32-32
grab=15-15
grabwalk=16-17
grabrun=20-23
grabjump=26-26
grabfall=32-32

The readAnimData(path) function imports the specified file and returns 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.

Functions and variables

Actor class
Type	Function/Field	Return values/Value type	Description
function	Actor:getAnimState()	int	Returns the Actor's current animation state.
function	Actor:setAnimState(int state)	nil	Sets the Actor's current animation state to the specified state.
function	Actor:getAnimFrame()	int	Returns the Actor's current animation frame.
function	Actor:setAnimFrame(int state)	nil	Sets the Actor's current animation frame.
Field	Actor.animState	int	Returns the Actor's current animation state.
Field	Actor.shouldFacePlayer	boolean	If true, the Actor will change direction to always face the player.
Field	Actor.closeIdleAnim	int	Specifies the Actor's idle animation state when the player is nearby.
Field	Actor.farIdleAnim	int	Specifies the Actor's idle animation state when the player is distant.
Field	Actor.talkAnim	int	Specifies the Actor's talking animation state during dialogue.
Field	Actor.walkAnim	int	Specifies the Actor's walking animation state.
Field	Actor.runAnim	int	Specifies the Actor's running animation state.

Interaction

Actor class
Type	Function/Field	Return values/Value type	Description

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

Miscellaneous

Actor class
Type	Function/Field	Return values/Value type	Description

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

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