WorldCutscene

Creates an alert bubble above a character.

@param chara — The character or character id to trigger an alert bubble for.

@param ... — Arguments to be passed to Character:alert().

@return alert_icon — The result alert icon created above the character's head.

@return finished — A function that returns true once the alert icon has disappeared.
See: Character.alert for details on the arguments to pass to this function.

Aligns the player's followers' directions and positions.

@param facing — The direction every character should face (Defaults to player's direction)

@param x — The x-coordinate of the 'front' of the line. (Defaults to player's x-position)

@param y — The y-coordinate of the 'front' of the line. (Defaults to player's y-position)

@param dist — The distance between each follower.

Smoothly pans the camera to the player and then attaches it.

@param time — The time, in seconds, that the camera will spend panning to the player's position. (Defaults to 0.8)

@return finished — A function that returns true once the camera panning is complete.

Attaches the camera to the player instantly.

Enables following for all of the player's current followers and causes them to walk to their following positions.

@param return_speed — The walking speed of the followers while they return to the player.

@return finished — A function that returns true once all followers have finished returning.

Enables following for all of the player's current followers, and immediately teleports them to their positions.

@return finished — A function that returns true once all followers have finished returning.

Creates a choicer with the choices specified in choices for the player to select from.

@param choices — A table of strings specifying the choices the player can select. Maximum of four.

@param options — A table defining additional properties to control the choicer.

@return selected — The index of the selected item if the cutscene has been set to wait for the choicer, otherwise a boolean that states whether the player has made their choice.

@return choicer — The choicebox object for this choicer. Only returned if wait is false.

options:
    | "top" -- Override for the default textbox position, defining whether the choicer should appear at the top of the screen.
    | "color" -- The main color to set all the choices to, or a table of main colors to set for different choices. (Defaults to `COLORS.white`)
    | "highlight" -- The color to highlight the selected choice in, or a table of colors to highlight different choices in when selected. (Defaults to `COLORS.yellow`)
    | "wait" -- Whether the cutscene should automatically suspend itself until the player makes their choice. (Defaults to `true`)

Closes the currently active textboxes, choicers and textchoicers, if they are open.

Detaches the camera from the player character.

Disables following for all of the player's current followers.

Locks the player's movement.
Happens automatically at the start of cutscenes.

Unlocks the player's movement.
Happens automatically at the end of cutscenes.

Fades the screen and music back in after a fade out.

@param speed — The speed to fade in at, in seconds (Defaults to last fadeOut's speed.)

@param options — A table defining additional properties to control the fade.

@return finished — A function that returns true once the fade has finished.

options:
    | "global" -- Whether to use the global Game fader, instead of a fader specifically assigned to the current world. (Defaults to `false`)
    | "color" -- The color that should be faded to (Defaults to last fadeOut's color)
    | "alpha" -- The alpha to start at (Defaults to `1`)
    | "blocky" -- Whether to do a rough, 'blocky' fade. (Defaults to `false`)
    | "music" -- The speed to fade the music at, or whether to fade it at all (Defaults to fade speed)

Fades the screen and music out.

@param speed — The speed to fade out at, in seconds. (Defaults to 0.25)

@param options — A table defining additional properties to control the fade.

@return finished — A function that returns true once the fade has finished.

options:
    | "global" -- Whether to use the global Game fader, instead of a fader specifically assigned to the current world. (Defaults to `false`)
    | "color" -- The color that should be faded to (Defaults to `COLORS.black`)
    | "alpha" -- The alpha to start at (Defaults to `0`)
    | "blocky" -- Whether to do a rough, 'blocky' fade. (Defaults to `false`)
    | "music" -- The speed to fade the music at, or whether to fade it at all (Defaults to fade speed)

Gets a specific character currently present in the world.

@param id — The actor id of the character to search for.

@param index — The character's index, if they have multiple instances in the world. (Defaults to 1)

@return chara — The character instance, or nil if it was not found.

Gets a specific event present in the current map.

@param id — The unique numerical id of an event OR the text id of an event type to get the first instance of.

@return event — The event instnace, or nil if it was not found.

Gets a list of all instances of one type of event in the current maps

@param name — The text id of the event to search for, fetches every event if nil

@return events — A table containing every instance of the event in the current map

Gets a specific marker from the current map.

@param name — The name of the marker to search for.

@return x — The x-coordinate of the marker's center.

@return y — The y-coordinate of the marker's center.

Hides the mini shop UI.

Adds all followers' current positions to their movement history.
If followers are added or moved by the cutscene, call this at the end to prevent them from warping.

Moves a character to a new position with a jumping arc motion.

@param chara — The Character instance or id to make jump.

@param ... — Additional arguments to pass to chara:jumpTo().

@return finished — A function that returns `true once the character has completed their jump. See: Character.jumpTo for the arguments to set up a jump.

Loads into a new map file.

@param map — The name of the map file to load.

@param x — The x-coordinate the player will spawn at in the new map.

@param y — The y-coordinate the player will spawn at in the new map.

@param marker — The name of the marker the player will spawn at in the new map. Defaults to "spawn"

@param facing — The direction the party should be facing when they spawn in the new map.

@param callback — A callback to run once the map has finished loading (Post Map:onEnter())

@param ... — Additional arguments that will be passed forward into Map:onEnter().

Makes a character look in a specific direction.

@param chara — The Character or id of the character that should face down. (Defaults to the player)

@param dir — The direction the character should face. Must be either "up", "dowm", "left", or "right". (Defaults to "down")

Loads a new map and starts the transition effects for world music, borders, and the screen as a whole.

@param ... — Additional arguments that will be passed into World:loadMap()

@return finished — A function that returns true once the map transition has finished.
See: World.loadMap for the arguments to pass into World:loadMap().

Pans tha camera to a new position over a given time.

@param x — The x-coordinate to pan the camera to.

@param y — The y-coordinate to pan the camera to.

@param marker — The name of a marker in the current map to pan the camera to.

@param chara — A Character instance in the current map to pan the camera to. (Does not attach the camera)

@param time — The time, in seconds, that the camera should spend panning to the target. Defaults to 1 second.

@param ease — The easing to use for the panning.

@param after — A function that is run once the camera reaches its panning target.

@return finished — A function that returns true once the camera panning is complete.

ease:
    | "linear"
    | "in-quad"
    | "in-cubic"
    | "in-quart"
    | "in-quint"
    | "in-sine"
    | "in-expo"
    | "in-circ"
    | "in-back"
    | "in-bounce"
    | "in-elastic"
    | "out-quad"
    | "out-cubic"
    | "out-quart"
    | "out-quint"
    | "out-sine"
    | "out-expo"
    | "out-circ"
    | "out-back"
    | "out-bounce"
    | "out-elastic"
    | "in-out-quad"
    | "in-out-cubic"
    | "in-out-quart"
    | "in-out-quint"
    | "in-out-sine"
    | "in-out-expo"
    | "in-out-circ"
    | "in-out-back"
    | "in-out-bounce"
    | "in-out-elastic"
    | "inQuad"
    | "outQuad"
    | "inOutQuad"
    | "outInQuad"
    | "inCubic"
    | "outCubic"
    | "inOutCubic"
    | "outInCubic"
    | "inQuart"
    | "outQuart"
    | "inOutQuart"
    | "outInQuart"
    | "inQuint"
    | "outQuint"
    | "inOutQuint"
    | "outInQuint"
    | "inSine"
    | "outSine"
    | "inOutSine"
    | "outInSine"
    | "inExpo"
    | "outExpo"
    | "inOutExpo"
    | "outInExpo"
    | "inCirc"
    | "outCirc"
    | "inOutCirc"
    | "outInCirc"
    | "inElastic"
    | "outElastic"
    | "inOutElastic"
    | "outInElastic"
    | "inBack"
    | "outBack"
    | "inOutBack"
    | "outInBack"
    | "inBounce"
    | "outBounce"
    | "inOutBounce"
    | "outInBounce"

Pans the camer to a new position at a given speed.

@param x — The x-coordinate to pan the camera to.

@param y — The y-coordinate to pan the camera to.

@param marker — The name of a marker in the current map to pan the camera to.

@param chara — A Character instance in the current map to pan the camera to. (Does not attach the camera)

@param speed — The speed, in pixels per frame at 30FPS, that the camera should move towards its target. Defaults to 4.

@param after — A function that is run once the camera reaches its panning target.

Resets the sprite of a specific character to its default.

@param chara — The Character or character id to reset the sprite of.

Resets the sprites of the player and all their followers to their defaults.

Sets the animation of a particular character.

@param chara — The Character or character id to change the animation of.

@param anim — The name of the animation to be set.

@return finished — A function that returns true once the animation has finished.

Sets the current speaker for dialogue boxes in this cutscene.

@param actor — The Character instance or character id to set as the speaker.

@param talk — If false, the actor of the textbox will be set, but not the speaking character in the world for talking animations.

Sets the sprite of a particular character.

@param chara — The Character or character id to change the sprite of.

@param sprite — The name of the sprite to be set.

@param speed — The time, in seconds, between frames for the sprite, if it has multiple frames. (Defaults to 1/30)

Sets whether the textbox should appear at the top of the screen or the bottom.

@param top — Whether the textbox should appear at the top of the screen.

Shakes the camera by the specified x, y.

@param x — The amount of shake in the x direction. (Defaults to 4)

@param y — The amount of shake in the y direction. (Defaults to 4)

@param friction — The amount that the shake should decrease by, per frame at 30FPS. (Defaults to 1)

@return finished — A function that returns true once the shake value has returned to 0.

Shakes a character by the specified x, y.

@param chara — The character being shaken. Accepts either a Character instance or the id of a character.

@param x — The amount of shake in the x direction. (Defaults to 4)

@param y — The amount of shake in the y direction. (Defaults to 0)

@param friction — The amount that the shake should decrease by, per frame at 30FPS. (Defaults to 1)

@param delay — The time it takes for the object to invert its shake direction, in seconds. (Defaults to 1/30)

@return finished — A function that returns true once the shake value has returned to 0.

Shows the mini shop UI.

Slides an object along a path.

@param obj — The object instance or id of a character to slide.

@param path — The name of a path in the current map file, or a table defining several points (as additional tables) that constitute a path.

@param options — A table defining additional properties that the slide should use.

@return finished — Returns true when the object has reached the end of the path.

options:
    | "time" -- The amount of time, in seconds, that the object should take to travel along the full path.
    | "speed" -- The speed at which the object should travel along the path, in pixels per frame at 30FPS.
    | "ease" -- The ease type to use when travelling along the path. Unused if `speed` is specified instead of `time`. (Defaults to "linear")
    | "after" -- A function that will be called when the end of the path is reached. Receives no arguments.
    | "move_func" -- A function called every frame while the object is travelling along the path. Receives `self` and the `x` and `y` offset from the previous frame as arguments.
    | "relative" -- Whether the path should be relative to the object's current position, or simply set its position directly.
    | "loop" -- Whether the path should loop back to the first point when reaching the end, or if it should stop.
    | "reverse" -- If true, reverse all of the points on the path.
    | "skip" -- A number defining how many points of the path to skip.
    | "snap" -- Whether the object's position should immediately "snap" to the first point, or if its initial position should be counted as a point on the path.

Moves the object's x and y values to the new specified position over time seconds.

@param obj — The object instance or id of a character to slide.

@param x — The new x value to approach.

@param y — The new y value to approach.

@param marker — A map marker whose position the object should approach.

@param time — The amount of time, in seconds, that the slide should take. (Defaults to 1 second)

@param ease — The ease type to use when moving to the new position. (Defaults to "linear")

@return finished — A function that returns true once the object has reached its destination.

ease:
    | "linear"
    | "in-quad"
    | "in-cubic"
    | "in-quart"
    | "in-quint"
    | "in-sine"
    | "in-expo"
    | "in-circ"
    | "in-back"
    | "in-bounce"
    | "in-elastic"
    | "out-quad"
    | "out-cubic"
    | "out-quart"
    | "out-quint"
    | "out-sine"
    | "out-expo"
    | "out-circ"
    | "out-back"
    | "out-bounce"
    | "out-elastic"
    | "in-out-quad"
    | "in-out-cubic"
    | "in-out-quart"
    | "in-out-quint"
    | "in-out-sine"
    | "in-out-expo"
    | "in-out-circ"
    | "in-out-back"
    | "in-out-bounce"
    | "in-out-elastic"
    | "inQuad"
    | "outQuad"
    | "inOutQuad"
    | "outInQuad"
    | "inCubic"
    | "outCubic"
    | "inOutCubic"
    | "outInCubic"
    | "inQuart"
    | "outQuart"
    | "inOutQuart"
    | "outInQuart"
    | "inQuint"
    | "outQuint"
    | "inOutQuint"
    | "outInQuint"
    | "inSine"
    | "outSine"
    | "inOutSine"
    | "outInSine"
    | "inExpo"
    | "outExpo"
    | "inOutExpo"
    | "outInExpo"
    | "inCirc"
    | "outCirc"
    | "inOutCirc"
    | "outInCirc"
    | "inElastic"
    | "outElastic"
    | "inOutElastic"
    | "outInElastic"
    | "inBack"
    | "outBack"
    | "inOutBack"
    | "outInBack"
    | "inBounce"
    | "outBounce"
    | "inOutBounce"
    | "outInBounce"

Moves the object's x and y values to the new specified position at a speed of speed pixels per frame.

@param obj — The object instance or id of a character to slide.

@param x — The new x value to approach.

@param y — The new y value to approach.

@param marker — A map marker whose position the object should approach.

@param speed — The amount that the object's x and y should approach the specified position, in pixels per frame at 30FPS. (Defaults to 4)

@return finished — A function that returns true once the object has reached its destination.

Spawns a new NPC object in the world.

@param actor — The actor to use for the new NPC, either an id string or an actor object.

@param x — The x-coordinate to place the NPC at.

@param y — The y-coordinate to place the NPC at.

@param properties — A table of additional properties for the new NPC. Supports all the same values as an npc map event.

@return npc — The newly created npc.

Causes a specific character to start spinning.

@param chara — The Character of character id to spin.

@param speed — The spin speed to set on the character. Negative numbers = anticlockwise, positive numbers = clockwise. Higher value = slower spin.

Starts an encounter within the current cutscene.
The cutscene will resume at the end of the encounter, once the transition out from battle is complete.

@param encounter — The encounter id or instance to use for this battle.

@param transition — Whether to start in the transition state (Defaults to true). As a string, represents the state to start the battle in.

@param enemy — An enemy instance or list of enemies as Characters in the world that will transition into the battle.

@param options — A table defining additional properties to control the encounter.

@return finished — A function that returns true when the encounter has finished. (Only use if options.wait is set to false)

@return encounter — The Encounter instance for the battle started by this function call. (Only use if options.wait is set to false)

options:
    | "on_start" -- A callback that is run when the battle starts (Exits the `"TRANSITION"` state). Runs immediately if the transition is skipped.
    | "wait" -- Whether the cutscene should be suspended until the encounter is complete. (Deftualts to `true`)

Creates a new textbox and starts typing the given text into it.
Will pause the cutscene until the textbox is closed, unless otherwise specified via options.

@param text — The text to be typed.

@param portrait — The name of the character portrait to use for this textbox.

@param actor — The Character/Actor to be used for voice bytes and portraits, overriding the active cutscene speaker.

@param options — A table definining additional properties to control the textbox.

@return finished — A function that returns true once the textbox has closed. (Only use if options["wait"] is set to false.)

@return textbox — The Textbox object that has been created. (Only use if options["wait"] is set to false.)

options:
    | "talk" -- If a `Character` instance is attached to the textbox, whether they should use their talk sprite in world. 
    | "top" -- Override for the default textbox position, defining whether the textbox should appear at the top of the screen.
    | "x" -- The x-offset of the dialgoue portrait.
    | "y" -- The y-offset of the dialogue portrait.
    | "reactions" -- A table of tables that define "reaction" dialogues. Each table defines the dialogue, x and y position of the face, actor and face sprite, in that order. x and y can be strings as well, referring to existing positions; x can be left, leftmid, mid, middle, rightmid, or right, and y can be top, mid, middle, bottommid, and bottom. Must be used in combination with a react text command.
    | "functions" -- A table defining additional functions that can be used in the text with the `func` text command. Each key, value pair will form the id to use with `func` and the function to be called, respectively.
    | "font" -- The font to be used for this text. Can optionally be defined as a table {font, size} to also set the text size.
    | "align" -- Sets the alignment of the text.
    | "skip" -- If false, the player will be unable to skip the textbox with the cancel key.
    | "advance" -- When `false`, the player cannot advance the textbox, and the cutscene will no longer suspend itself on the dialogue by default.
    | "auto" -- When `true`, the text will auto-advance after the last character has been typed.
    | "wait" -- Whether the cutscene should automatically suspend itself until the textbox advances. (Defaults to `true`, unless `advance` is false.)

Creates a Text Choicer - A textbox that includes both dialogue and a choicer.

@param text — The text to be typed.

@param choices — A table of strings specifying the choices the player can select.

@param portrait — The name of the character portrait to use for this textbox.

@param actor — The Character/Actor to be used for voice bytes and portraits, overriding the active cutscene speaker.

@param options — A table definining additional properties to control the textbox.

@return finished — A function that returns true once the textbox has closed. (Only use if options["wait"] is set to false.)

@return textbox — The TextboxChoicer object that has been created. (Only use if options["wait"] is set to false.)

options:
    | "talk" -- If a `Character` instance is attached to the textbox, whether they should use their talk sprite in world. 
    | "top" -- Override for the default textbox position, defining whether the textbox should appear at the top of the screen.
    | "x" -- The x-offset of the dialgoue portrait.
    | "y" -- The y-offset of the dialogue portrait.
    | "reactions" -- A table of tables that define "reaction" dialogues. Each table defines the dialogue, x and y position of the face, actor and face sprite, in that order. x and y can be strings as well, referring to existing positions; x can be left, leftmid, mid, middle, rightmid, or right, and y can be top, mid, middle, bottommid, and bottom. Must be used in combination with a react text command.
    | "functions" -- A table defining additional functions that can be used in the text with the `func` text command. Each key, value pair will form the id to use with `func` and the function to be called, respectively.
    | "font" -- The font to be used for this text. Can optionally be defined as a table {font, size} to also set the text size.
    | "align" -- Sets the alignment of the text.
    | "skip" -- If false, the player will be unable to skip the textbox with the cancel key.
    | "wait" -- Whether the cutscene should automatically suspend itself until the player selects a choice. (Defaults to `true`)

Walks a character along a path.

@param chara — The Character instance or id to make walk.

@param path — The name of a path in the current map file, or a table defining several points (as additional tables) that constitute a path.

@param options — A table defining additional properties to control the walk.

@return finished — Returns true when the character has reached the end of the path.

options:
    | "facing" -- The direction the character should face when they finish their walk. If `keep_facing` is `true`, they will instead face way immediately.
    | "keep_facing" -- If `true`, the facing direction of the character will be preserved. Otherwise, they will face the direction they are walking. (Defaults to `false`)
    | "time" -- The amount of time, in seconds, that the object should take to travel along the full path.
    | "speed" -- The speed at which the object should travel along the path, in pixels per frame at 30FPS.
    | "ease" -- The ease type to use when travelling along the path. Unused if `speed` is specified instead of `time`. (Defaults to "linear")
    | "after" -- A function that will be called when the end of the path is reached. Receives no arguments.
    | "relative" -- Whether the path should be relative to the object's current position, or simply set its position directly.
    | "loop" -- Whether the path should loop back to the first point when reaching the end, or if it should stop.
    | "reverse" -- If true, reverse all of the points on the path.
    | "skip" -- A number defining how many points of the path to skip.
    | "snap" -- Whether the object's position should immediately "snap" to the first point, or if its initial position should be counted as a point on the path.

Walks a character to a new x and y over time seconds.

@param chara — The Character instance or id to make walk.

@param x — The new x value to approach.

@param y — The new y value to approach.

@param marker — A map marker whose position the character should approach.

@param time — The amount of time, in seconds, that the walk should take. (Defaults to 1 second)

@param facing — The direction the character should face when they finish their walk. If keep_facing is true, they will instead face way immediately.

@param keep_facing — If true, the facing direction of the character will be preserved. Otherwise, they will face the direction they are walking. (Defaults to false)

@param ease — The easing to use for the character's walk motion.

@param after — A callback function that is run after the character has finished walking.

@return finished — A function that returns true once the character has finished walking.

ease:
    | "linear"
    | "in-quad"
    | "in-cubic"
    | "in-quart"
    | "in-quint"
    | "in-sine"
    | "in-expo"
    | "in-circ"
    | "in-back"
    | "in-bounce"
    | "in-elastic"
    | "out-quad"
    | "out-cubic"
    | "out-quart"
    | "out-quint"
    | "out-sine"
    | "out-expo"
    | "out-circ"
    | "out-back"
    | "out-bounce"
    | "out-elastic"
    | "in-out-quad"
    | "in-out-cubic"
    | "in-out-quart"
    | "in-out-quint"
    | "in-out-sine"
    | "in-out-expo"
    | "in-out-circ"
    | "in-out-back"
    | "in-out-bounce"
    | "in-out-elastic"
    | "inQuad"
    | "outQuad"
    | "inOutQuad"
    | "outInQuad"
    | "inCubic"
    | "outCubic"
    | "inOutCubic"
    | "outInCubic"
    | "inQuart"
    | "outQuart"
    | "inOutQuart"
    | "outInQuart"
    | "inQuint"
    | "outQuint"
    | "inOutQuint"
    | "outInQuint"
    | "inSine"
    | "outSine"
    | "inOutSine"
    | "outInSine"
    | "inExpo"
    | "outExpo"
    | "inOutExpo"
    | "outInExpo"
    | "inCirc"
    | "outCirc"
    | "inOutCirc"
    | "outInCirc"
    | "inElastic"
    | "outElastic"
    | "inOutElastic"
    | "outInElastic"
    | "inBack"
    | "outBack"
    | "inOutBack"
    | "outInBack"
    | "inBounce"
    | "outBounce"
    | "inOutBounce"
    | "outInBounce"

Walks a character to a new x and y at speed pixels per frame.

@param chara — The Character instance or id to make walk.

@param x — The new x value to approach.

@param y — The new y value to approach.

@param marker — A map marker whose position the character should approach.

@param speed — The amount that the character's x and y should approach the specified position, in pixels per frame at 30FPS. (Defaults to 4)

@param facing — The direction the character should face when they finish their walk. If keep_facing is true, they will instead face way immediately.

@param keep_facing — If true, the facing direction of the character will be preserved. Otherwise, they will face the direction they are walking. (Defaults to false)

@param after — A callback function that is run after the character has finished walking.

@return finished — A function that returns true once the character has finished walking.

The index of the player's last selected choice.

The current choicer object, if it is active.

The current mini shop UI object, if it is active.

The current Textbox object, if it is active.

The current speaker in the cutscene.

The ActorSprite of the current speaker.

Whether the textbox should display at the top of the screen instead of the bottom.

The current text choicer (choicer with additional text prompt) object, if it is active.

Reference to Game.world