Scripting

Item, NPC, and Room scripting comes in the form of event scripting, see the Event section for a general overview of how that works before reading on.

Creating a script

Scripts are defined for an area in the scripts/ folder underneath the area's folder. For each entity type there is a subfolder. For example:

bundles/my-area/areas/limbo/
  scripts/
    npcs/
      1-rat.js
    items/
      1-shiv.js
    rooms/
      1-test.js

As a matter of convention scripts are named, <entity id>-<whatever you want>. It's not required but it will help a lot when trying to figure out what script goes to what entity.

See the relevant entity's guide section on how to add the script to the entity.

Behaviors

Behaviors are scripts that you can reuse for the same entity types across multiple areas/bundles. For example maybe you want to have many different NPCs wander around or immediately attack players upon entering the room (aggro mobs) you can use behaviors for that.

Behaviors are defined exactly the same as normal scripts but are created inside the behaviors/ directory inside your bundle but outside of your area definition.

bundles/my-area/
  areas/
    limbo/
    ...
  behaviors/
    npcs/
      aggro.js
    items/
    rooms/

Again, see the relevant entity's guide section on how to add behaviors to the entity.

Tip: Behaviors can be used as flags. For example, if you say behaviors: ['combat'] on an NPC you don't need to actually create a combat.js behavior file, npc.hasBehavior('combat') will still return true. This is used, as an example, in the kill command in core-combat to differentiate pacifist NPCs from NPCs that can enter combat

Default events

This is a list of events that are emitted by default in Ranvier.

Engine - Events that come from the engine itself (from src/) and will always be available.

Core Bundles - Events that come from one of the core-* example bundles and may not be available if you have disabled the core bundles.

Events are shown as:
eventName (arguments)
Details of event

NPCs

Engine

combatEnd
Combat has ended, specifically NPC's list of combatants is now empty
combatStart (Character target)
Combat has started against target, specifically NPC was not in combat and now is. Event is not fired if the NPC was already in combat when new combatants are added
damaged (Damage damage)
Something has decreased one of the NPC's attributes, not just health, applies to any attribute. See src/Damage.js for details of information available from damage argument.
heal (Heal heal, Character target)
Same as hit but increased instead of decreased
healed (Heal heal)
Same as damaged but increased instead of decreased
hit (Damage damage, Character target)
This NPC caused damage to the target. Target may be itself.
spawn
NPC is initially created, fires immediately after NPC is placed in its target room.
updateTick
This event is special in that it automatically fires every half second on Rooms, NPCs, and Players. This event should be used for any event that is based on time, i.e., NPC should wander around every N seconds or something.

Core Bundles

deathblow (Character target)
NPC just killed target
killed
NPC died
playerDropItem (Player player, Item item)
player just dropped item in the room with the NPC
playerEnter (Player player)
player just entered the room with the NPC
playerLeave(Player player)
player just left the room. NOTE: playerLeave is actually fired before the player is removed from the room.

Items

Engine

There are no events emitted by the engine for items

Core Bundles

drop (Player player)
player just dropped this item
equip (Player player)
player just equipped this item
get (Player player)
player just picked up this item
put (Player player, Item container)
player just put this item into container

Rooms

Engine

updateTick
This event is special in that it automatically fires every half second on Rooms, NPCs, and Players. This event should be used for any event that is based on time, i.e., NPC should wander around every N seconds or something.

Core Bundles

playerEnter (Player player)
player just entered this room
playerLeave(Player player)
player just left this room. NOTE: playerLeave is actually fired before the player is removed from the room.