World

┗> Object > Class


The World Object manages everything relating to the overworld in Kristal.
A globally available instance of World is stored in Game.world.


Constructor


World(map: string?)

@param map — The optional name of a map to initially load with the world

Arguments:

map: string?

The optional name of a map to initially load with the world





Methods


World:afterMenuClosed()

Runs whenever the menu is closed



World:attachFollowers(return_speed: number?)

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

Arguments:

return_speed: number?

The walking speed of the followers while they return to the player



World:attachFollowersImmediate()

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





World:checkCollision(collider: Collider, enemy_check: boolean?)

Checks whether the input collider is colliding with anything in the world

Arguments:

collider: Collider

The collider to check collision for

enemy_check: boolean?

Whether to include the enemy collision map in the check

Returns:

collided: boolean

Whether a collision was found

with: Object?

The object that was collided with



World:closeMenu()

Closes the menu



World:createMenu()

Creates the main overworld menu if it does not exist
The event createMenu is called by this function, which can return a custom menu to use instead of the default Light/Dark menu

Returns:

1: DarkMenu|LightMenu


World:detachFollowers()

Disables following for all of the player's current followers





World:fadeInto(callback: fun())

Fades the world out and into another piece of content

Arguments:

callback: fun()

The callback that is run in the middle of the fade (fully faded out) to load the next piece of content



World:getActionBox(party_member: string|PartyMember)

Gets the action box instance for a member of the party

Arguments:

party_member: string|PartyMember

The PartyMember class is a type of data class that stores information about a member of the party.
PartyMembers are stored in scripts/data/party, and extend this class. Their filepath starting from here becomes their id, unless an id is specified as an argument to Class().

Returns:

1: OverworldActionBox?


World:getCameraTarget()

Gets the object that the camera is currently targetting

Returns:

1: Object|nil


World:getCellFlag(name: string, default: integer?)

Gets the value of a cell flag (a special flag which normally starts at -1 and increments by 1 at the start of every call, named after the call cutscene)

Arguments:

name: string
default: integer?

Returns:

1: integer


World:getCharacter(id: string, index: number?)

Gets a specific character currently present in the world

Arguments:

id: string

The actor id of the character to search for

index: number?

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

Returns:

chara: Character|nil

The character instance, or nil if it was not found



World:getCollision(enemy_check: boolean?)

Gets the collision map for the world

Arguments:

enemy_check: boolean?

Whether to include the enemy collision map (defaults to false)

Returns:

1: Collider[]


World:getEvent(id: string|number)

Gets a specific event present in the current map

Arguments:

id: string|number

The unique numerical id of an event OR the text id of an event type to get the first instance of

Returns:

event: Event

The event instnace, or nil if it was not found



World:getEvents(name: string?)

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

Arguments:

name: string?

The text id of the event to search for, fetches every event if nil

Returns:

events: Event[]

A table containing every instance of the event in the current map



World:getPartyCharacter(party: string|PartyMember)

Gets the Character in the world of a party member

Arguments:

party: string|PartyMember

The party member to get the character for

Returns:

1: Character?


World:getPartyCharacterInParty(party: string|PartyMember)

Gets the Follower or Player of a character currently in the party

Arguments:

party: string|PartyMember

The party member to get the character for

Returns:

1: (Follower|Player)?


World:getPlayerAndFollowers()

Gets the Player and Follower characters

Returns:

1: T


World:getSoulPartyCharacter()

Gets the Follower or Player of a character that's currently the soul party member

Returns:

1: (Follower|Player)?


World:hasCutscene()

Whether the world has a currently active cutscene

Returns:

1: boolean?


World:heal(target: string|PartyMember, amount: number, text: string?)

Heals a member of the party

Arguments:

target: string|PartyMember

The party member to heal

amount: number

The amount of HP to restore

text: string?

An optional text to display when HP is resotred in the Light World, before the HP restoration message



World:hideHealthBars()

Hides party member health bars



World:hurtParty(battler: string|Character, amount: number)

Hurts the party member battler by amount, or hurts the whole party for amount

Arguments:

battler: string|Character

The Character to hurt

amount: number

The amount of damage to deal

Returns:

killed: boolean

Whether all targetted characters were knocked out by this damage



World:inBattle()

Whether the player is currently in a world battle

Returns:

1: boolean


World:isTextboxOpen()

Checks whether there is currently a textbox open

Returns:

1: boolean


World:loadMap(: unknown)

Loads into a new map file.

Arguments:

: unknown

Additional arguments that will be passed forward into Map:onEnter()



World:mapTransition(: any)

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


See: World - World:loadMap()

Arguments:

: any

Additional arguments that will be passed into World:loadMap()



World:onKeyPressed(key: string)

Arguments:

key: string


World:onRemove(parent: Object)

Arguments:

parent: Object

The base class of all objects in Kristal.
When added to the stage, an object will be updated and rendered.



World:onStateChange(old: string, new: string)

Called whenever the state of the world changes

Arguments:

old: string
new: string


World:openMenu(menu: Object?, layer: number?)

Opens the main overworld menu

Arguments:

menu: Object?

An optional menu instance to open

layer: number?

The layer to create the menu on (defaults to WORLD_LAYERS["ui"] or 600)

Returns:

1: Object?


World:parseLayer(layer: (string|number)?)

Parses a variable-type layer specification into a recognised layer

Arguments:

layer: (string|number)?

Returns:

1: number


World:partyReact(party_member: string|PartyMember, text: string, display_time: number?)

Creates a reaction text on a party member's healthbar (usually used for equipment and items)

Arguments:

party_member: string|PartyMember

The party member who will react

text: string

The text to display for the reaction

display_time: number?

The display time, in seconds, of the reaction (defaults to 5/3 seconds)



World:registerCall(name: string, scene: string)

Registers a phone call in the Light World CELL menu

Arguments:

name: string

The name of the call as it will show in the CELL menu

scene: string

The cutscene to play when the call is selected



World:removeFollower(chara: string|Follower)

Removes a follower

Arguments:

chara: string|Follower

The Follower or the follower's actor id to remove

Returns:

follower: Follower?

The follower that was removed



World:replaceCall(name: string, index: integer, scene: string)

Replaces a phone call in the Light World CELL menu with another

Arguments:

name: string

The name of the call as it will show in the CELL menu

index: integer

The index of the call to replace

scene: string

The cutscene to play when the call is selected



World:setBattle(value: boolean)

Sets whether the player is currently in battle - cannot override being inside a battle area

Arguments:

value: boolean


World:setCameraAttached(attached_x: boolean?, attached_y: boolean?)

Sets whether the camera should be attached to its target for each axis

Arguments:

attached_x: boolean?

Whether the camera's x-axis position should follow its target

attached_y: boolean?

Whether the camera's y-axis position should follow its target



World:setCameraAttachedX(attached: boolean?)

Sets whether the camera should follow its target on the x-axis

Arguments:

attached: boolean?


World:setCameraAttachedY(attached: boolean?)

Sets whether the camera should follow its target on the y-axis

Arguments:

attached: boolean?


World:setCameraTarget(target: Object?)

Sets the object the camera should target

Arguments:

target: Object?

The base class of all objects in Kristal.
When added to the stage, an object will be updated and rendered.



World:setCellFlag(name: string, value: integer)

Sets the value of a cell flag (a special flag which normally starts at -1 and increments by 1 at the start of every call, named after the call cutscene)

Arguments:

name: string

The name of the flag to set

value: integer

The value to set the flag to



World:setState(state: string)

Changes the state of the world

Arguments:

state: string


World:setupMap(map: (string|table|Map)?, : unknown)

Sets up several variables for a new map

Arguments:

map: (string|table|Map)?

The Map object, name, or data to load

: unknown

Additional arguments that will be passed forward into Map:onEnter()



World:shakeCamera(x: number?, y: number?, friction: number?)

Arguments:

x: number?
y: number?
friction: number?


World:shopTransition(shop: string|Shop, options: table?)

Transitions from the world into a shop

Arguments:

shop: string|Shop

The shop to enter

options: table?

An optional table of leave_options for exiting the shop



World:showHealthBars()

Shows party member health bars



World:showText(text: string|string[]|string[][], after: fun( WorldCutscene, ...any)?)

Shows a textbox with the input text

Arguments:

text: string|string[]|string[][]
after: fun( WorldCutscene, ...any)?

A callback to run when the textbox is closed, receiving the cutscene instance used to display the text





World:spawnBullet(bullet: string?, : any)

Spawns a new WorldBullet to the world

Arguments:

bullet: string?

The bullet to add to the world, if left unspecified, spawns the basic WorldBullet

: any

Additional arguments to pass to the bullet's init() function

Returns:

bullet: WorldBullet

The newly created bullet



World:spawnFollower(chara: string|Actor|Follower, options: (table|"index"|"party"|"temp"|"x"...(+1))?)

Spawns a follower into the world

options:
    | "x" -- The position of the follower
    | "y" -- The position of the follower
    | "index" -- The index of the follower in the list of followers
    | "temp" -- Whether the follower is temporary and disappears when the current map is exited (defaults to `true`)
    | "party" -- The id of the party member associated with this follower

Arguments:

chara: string|Actor|Follower

The character to spawn as a follower

options: (table|"index"|"party"|"temp"|"x"...(+1))?

A table defining additional properties to control the new follower

Returns:

1: Follower


World:spawnNPC(actor: string|Actor, x: number, y: number, properties: table?)

Spawns a new NPC object in the world

Arguments:

actor: string|Actor

The actor to use for the new NPC, either an id string or an actor object

x: number

The x-coordinate to place the NPC at

y: number

The y-coordinate to place the NPC at

properties: table?

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

Returns:

npc: NPC

The newly created npc.



World:spawnObject(obj: Object, layer: (string|number)?)

Spawns an object to the world

Arguments:

obj: Object

The object to add to the world

layer: (string|number)?

The layer to place the object on

Returns:

1: Object


World:spawnParty(marker: (string| number, y)?, party: (string|PartyMember)[]?, extra: (string|Actor|Follower|[string|Actor|Follower, integer])[]?, facing: ("down"|"left"|"right"|"up")?)

Spawns characters in the world for the current party

facing:
    | "right"
    | "down"
    | "left"
    | "up"

Arguments:

marker: (string| number, y)?

The marker or coordinates to spawn the player at

party: (string|PartyMember)[]?

A table of party members to spawn (Defaults to Game.party)

extra: (string|Actor|Follower|[string|Actor|Follower, integer])[]?

Additional followers to add that are not in the party (defaults to Game.temp_followers)

facing: ("down"|"left"|"right"|"up")?

The direction the party should be facing when they spawn



World:spawnPlayer(: "marker, chara"|"x, y, chara"|unknown)

Spawns the player into the world


...(param):
    | "x, y, chara" -- The coordinates of the player spawn and the Actor (instance or id) to use for the player
    | "marker, chara" -- The marker name to spawn the player at and the Actor (instance or id) to use for the player

Arguments:

: "marker, chara"|"x, y, chara"|unknown

Arguments detailing how the player spawns



World:startCutscene(group: string, id: string, : any)

Starts a cutscene in the world

Arguments:

group: string

The name of the group the cutscene is a part of

id: string

The id of the cutscene

: any

Additional arguments that will be passed to the cutscene function

Returns:

The: WorldCutscene?

cutscene object that was created



World:stopCutscene()

Stops the current cutscene
An error will be thrown when trying to stop a cutscene if none are active



World:transitionMusic(next: string, volume, fade_out: boolean?)

Transitions the music from the current track to the next

Arguments:

next: string, volume

The filename, volume, and pitch of the next track

fade_out: boolean?

Whether to fade out the currently playing track before playing the next track






Fields


World.battle_alpha: number

The current alpha value of world battle content



World.bullets: WorldBullet[]

A table of currently active bullets


World.calls:

A list of calls available on the cell phone in the Light World CELL menu


World.camera: Camera

The camera object used to display the world


World.can_open_menu: boolean

Whether the player can open their menu


World.conroller_parent: Object

The object that all controllers are parented to



World.cutscene: WorldCutscene?

The WorldCutscene object of the currently active cutscene, if present


World.door_delay: number

(Used internally) Timer variable for door transition sounds




World.followers: Follower[]

A table of all followers currently present in the world



World.in_battle: boolean

Whether the player is currently in a world battle set through `World:setBattle() (affects the visibility of world battle content)


World.in_battle_area: boolean

Whether the player is currently standing inside a battlearea of the map (affects the visibility of world battle content)


World.map: Map

The currently loaded map instance



World.music: Music

The Music instance that controls audio playback for this World


World.player: Player

The player character


World.soul: OverworldSoul

The soul of the player


World.state: string

The current state that this World is in - should never be set manually, see World:setState() instead


World.state_manager: StateManager

An object that manages the state of this World





Undocumented





World.controller_parent: Object

The base class of all objects in Kristal.
When added to the stage, an object will be updated and rendered.