Reference

Defining things

The following functions are automatically available to all files in the world directory. Simply call a function to define a room, item, character, command, or event handler:

room(name, options)

Creates a room in the game world. Returns a reference to a Room object. Example:

room('aRoom', {
  description: "You are standing in a room.",
  image: "http://example.com/room.jpg",
  exits: { west: 'anotherRoom', east: 'yetAnotherRoom' }
});

Arguments:

• name - Each room must have a unique string name. This lets you refer to the room in the definitions of other rooms and items (see below).

• options - An object containing options for the room definition:

  • description - A string description. Nodeventure prints this when the player enters the room.

  • exits - An object literal describing the exits from this room and the rooms they connect to. Keys are the names of the exits and values are the string IDs of the connecting rooms. For example:

      { north: "castle", down: "cellar", "skywards": "sky" }
    

item(roomName, itemName, options)

Creates an item in a room. Returns a reference to an Item object. Example:

item('secretLab', 'jetpack', {
  image: 'http://example.com/cat.jpg',
  respawnTime: 120,
  short: 'a jetpack',
  description: 'An awesome jetpack for flying around.'
});

Arguments:

• roomName - The name of the room to which to add the items.

• itemName - A string name for the item that differentiates it from other items in the room.

• options - An object containing the following options:

  • image - An optional image displayed when the player enters the room in which the item is located.

  • width - An optional image width (default 50%).

  • height - An optional image height (default 50%).

  • top - An optional image top position (default random).

  • left - An optional image left position (default random).

  • respawnTime - If an item is taken by a player, Nodeventure eventually spawns a replacement for other people to pick up. This is the number of seconds to wait until a new item is created.

  • short - A short (few word) description of the item. This is typically inserted into the middle of a sentence that refers to the item.

  • description - A longer (whole sentence) description of the item. This is typically used when a separate paragraph of description is required.

command(name, [helpText], callback)

Creates a new command that the player can type in.

• name - The first word in the command, e.g. "look". Nodeventure will execute your callback if the player types in a command starting with this word.

• helpText (optional) - Help text to include in the output of the "help" command.

• callback - A function that is executed when the player types in the command, arguments as follows:

  callback(rest, player, game)

  • rest - The remainder of the command as a string. For example, if the player types "look at the room", rest will be the string "at the room".

  • player - A reference to the Player that typed in the command. Through this object you can access the player's inventory and the room they are standing in, and send text, images and commands back to the browser.

  • game - A reference to the global Game object. Through this object you can access all of the rooms, players, and commands in the game.

itemCommand(name, itemName, [helpText], callback)

A variation of the command() function that defines a command relating to a particular item in the game. Returns void.

• name - The first word in the command, e.g. "use". Nodeventure will execute your callback if the player types in a command starting with name and itemName.

• itemName - The second word in the command, e.g. "skis". Nodeventure will execute your callback if the player types in a command starting with name and itemName.

• helpText (optional) - Help text to include in the output of the "help" command.

• callback - A callback function that is executed when the player types in the command. Arguments are as follows:

  callback(rest, player, item, game)

  • rest - The remainder of the command as a string.

  • player - A reference to the Player that typed in the command.

  • item - A reference to the item used.

  • game - A reference to the global Game object.

character(name, options)

Create a character. For example, a yeti. Returns a reference to a Character object.

• name - A globally unique string name for the character.

• options - An options object containing the following fields:

  • location - The name of the room that the character starts in.

  • description - A description of the character.

Use the handler() function and the tick event to give the character behaviour.

handler(eventName, callback)

Register a handler for an event. Returns void.

• eventName - The name of the event to listen for. Passing "all" allows you to listen to all events.

• callback - A function to be executed whenever the event fires. The arguments depend on the specific event.

Predefined Events

The following event types are built in to Nodeventure. Use the handler function to listen for events and the game.emit method to fire them.

joinPlayer

Arguments: [ player, game ]

An event fired whenever a player joins the game.

partPlayer

Arguments: [ player, game ]

An event fired whenever a player leaves the game (by closing their browser or navigating away form the page).

playerTalk

Arguments: [ player, message ]

An event fired whenever a player uses the "say" command to say something.

tick

Arguments: []

A general purpose event that fires every second. No arguments.

enterRoom

Arguments: [ player, room, game ]

An event fired whenever a player enters a room.

leaveRoom

Arguments: [ player, room, game ]

An event fired whenever a player leaves a room.

command:

Arguments: [ rest, player, game ]

An event fired whenever a play types in the corresponding commandName.

Object Types

Rooms, items, and players are represented as objects. You are passed references to these objects via arguments to the callbacks to the functions described above. Wherever you have a reference to an object, you can use it to call the methods described below.

Room

Wherever you are passed a reference to a room object, you can use it to call the following methods:

room.broadcast(message)

Broadcast a message to all players in the room. For example:

room.broadcast("Hey everybody!")

Players

Wherever you are passed a reference to a player object, you can use it to call the following methods:

player.write(message)

Write a message to the player's browser. For example:

player.write("Hey player!")

player.broadcast(message)

Broadcast a message to all players in the same room as player. For example:

player.broadcast("Hey everybody!")

player.execute(command)

Execute a command on behalf of the player.

player.getCurrentRoom()

Returns the room that the player is currently inhabiting.

player.getItem(itemName)

Returns an item from the player's inventory, or null if the item is not present.

The Game Object

If you are passed a reference to the singleton game object, you can use it to call the following methods:

game.broadcast(message)

Broadcast a message to all players. For example:

game.error("Hey everybody!")

game.warn(message)

Broadcast a warning message to all players. For example:

game.warn("Something almost went wrong.")

game.error(message)

Broadcast an error message to all players. For example:

game.error("Something actually went wrong.")

game.execute(playerName, command)

Execute a command on behalf of a player. For example:

game.execute("dave", "say hi")

game.emit(name, arguments...)

Emit an event with the supplied name and arguments.