Lua instance reference

Table of Contents Terminology Lua Design beginInstance playerDeath playerDisconnect timerEnd mobDeath mobSpawn friendlyHit changeMap partyDisband partyRemoveMember

Terminology

"Instances" are what Vana uses to refer to exclusive collections of events and data. In game terms, these are all instances:

• Minidungeons
• Party quests
• Competitive quests (e.g. Monster Carnival)
• Major bosses
• Boat rides, elevators, etc.
• Major boss signups
• GM events
• Weddings
• Sometimes quests

The important thing to note here is the word "exclusive." Instances are designed entirely around the idea that only a few players have access to the maps/resources at a time. This has implications for where you would use the instancing system, e.g. you wouldn't normally want to use it for a map that anyone can go to at any time.

Lua Design

The Lua design is very different from other kinds of scripts (such as NPC or portal scripts) because instances are event-driven. Instances allow you to execute some code when an event occurs. There are a few pre-defined events. You only need to implement functions that apply to your instance. If, for example, you don't use playerDisconnect for anything, you can leave that out and the system is fine.

A full list of events can be found at any time in /scripts/instances/_reference_script_read_first.lua.

beginInstance

Arguments: N/A

Notes: Occurs the instant that createInstance is called

playerDeath

Arguments:

• playerId: The ID of the player that died

Notes: Occurs every time a player registered with the instance dies

playerDisconnect

Arguments:

• playerId: The ID of the player that disconnected
• isPartyLeader: A boolean indicating whether or not the player was a party leader

Notes: Occurs every time a player registered with the instance disconnects. This event occurs after the disconnecting player is removed from the map. As such, getNumPlayers(mapId) will be 0 if this was the last player on the map.

timerEnd

Arguments:

• name: A string indicating the identifier of the timer
• fromTimer: A boolean indicating whether or not the timer ended normally

Notes: Occurs after a timer started by either startInstanceFutureTimer or startInstanceSecondOfHourTimer ends. All instances that have an instance time have an implicit timer called "instance". This event will not be triggered for the instance timer in the case where you restart or stop the instance timer manually.

mobDeath

• mobId: The mob template ID (e.g. Snail is 100100)
• mapMobId: The map-specific ID for a particular instance of the mob
• mapId: The ID of the map where the mob died

Notes: Occurs every time a mob dies on a map registered to the instance

mobSpawn

Arguments:

• mobId: The mob template ID (e.g. Snail is 100100)
• mapMobId: The map-specific ID for a particular instance of the mob
• mapId: The ID of the map where the mob spawned

Notes: Occurs every time a mob spawns on a map registered to the instance

friendlyHit

Arguments:

• mobId: The mob template ID (e.g. Snail is 100100)
• mapMobId: The map-specific ID for a particular instance of the mob
• mapId: The ID of the map where the friendly mob was hit
• hp: The current HP level of the friendly mob
• maxHp: The maximum HP level of the friendly mob

Notes: Occurs every time a friendly mob is damaged on a map registered to the instance (e.g. Tylus in El Nath PQ)

changeMap

Arguments:

• playerId: The ID of the player that switched maps either to or from a map that is registered with the instance
• newMap: The ID of the destination map
• oldMap: The ID of the source map
• isPartyLeader: A boolean indicating whether or not the player is a party leader

Notes: Occurs every time a player switches to or from a map that is registered with the instance. Players that are not registered to the instance will trigger this as well.

Note that this occurs before the player is removed from the old map, so assuming the player is the only one on either map, the following invariants will hold:

 getNumPlayers(newMap) == 0
 getNumPlayers(oldMap) == 1

partyDisband

Arguments:

• partyId: The ID of the party that disbanded

Notes: Occurs when a party added to an instance disbands. This occurs prior to any removal of players/etc., so all party-related Lua exports should work as expected.

partyRemoveMember

Arguments:

• playerId: The ID of the player that was removed
• partyId: The ID of the party that the member was a part of

Notes: Occurs when a party added to an instance kicks a member or a member leaves. This occurs prior to any removal of players, so all party-related Lua exports should work as expected.