Difference between revisions of "Script:Persist.js"

Revision as of 22:56, 3 June 2013

persist.js lets you store variables in persons and maps, and use them in event scripts.

At its simplest, you can store simple quest information, e.g. if you've talked to an NPC, or collected an item. Power users can take full advantage of JavaScript, and write templates for common person patterns, e.g. one-line townsfolk, store keepers, inn keepers, save points, chests, items, door switches, bosses blocking passages, and warps.

It helps you to organise your game data. If you ever got sick of making global variables and confusing data structures to hold your game info, this is your answer.

Download

• persist.js (17.9 KB JavaScript file)
• persist.js demo game (15.6 KB ZIP archive, requires Sphere)

The code (embedded Gist)

<gist>5702052</gist>

Quick start

1. Download persist.js into your scripts/ folder.
2. Put this in your game function:

   RequireScript("persist.js");
   function game()
   {
     persist.init();
     // ...
   }

3. Create a maps/ folder in your scripts folder, so it looks like scripts/maps/
4. For each some_map.rmp, make a new script file scripts/maps/some_map.js
5. Start writing in scripts/maps/some_map.js:

   ({
     visited: false,
    
     enter: function (self) {
       if (!self.visited) {
         Say("Welcome to " + GetCurrentMap() + "!");
         self.visited = true;
       }
     },
    
     Billy: {
       times: 0,
    
       talk: function (self) {
         self.times += 1;
         Say("Hi! We've spoken " + self.times + " before.");
       }
     }
   })

   This will greet the player when they enter the map, and let the person named "Billy" say how many times the player has spoken to them.

Reference

API

• persist.init() - start using the persist.js framework. Hooks into events and activates automatic script loading.
• persist.stop() - stop using the persist.js framework.

• persist.map([mapname]) - get the state of mapname to get/set their state variables, e.g.

  if (persist.map("bleh.rmp").visited) {
    // actions to do if player has visited bleh.rmp
  }

• persist.person([personname[, mapname]]) - get the state of personname in mapname. Use like it like persist.map().

• persist.getWorldState() - get an object containing the variables of all maps and persons. Useful for saving games.
• persist.setWorldState(newstate) - set newstate as the set of variables for all maps and persons. Useful for loading games.

• persist.getScriptPath() - get the path where map scripts are to be loaded from, relative to other/. Defaults to "../scripts/maps/".
• persist.setScriptPath(newpath) - set the path where map scripts are to be loaded from to newpath, relative to other/.

• persist.setLog(log) - set the Sphere log object to record persist.js execution. Useful for debugging.
• persist.startLogging([takenotes, [log]]) - begin logging of persist.js. If takenotes is true, notes will be recorded as well as warnings and errors. log is accepted for convenience.
• persist.stopLogging() - stop logging execution of persist.js.

Map events

There are 6 map events:

• enter - SCRIPT_ON_ENTER_MAP
• leave - SCRIPT_ON_LEAVE_MAP
• leaveNorth - SCRIPT_ON_LEAVE_MAP_NORTH
• leaveSouth - SCRIPT_ON_LEAVE_MAP_SOUTH
• leaveEast - SCRIPT_ON_LEAVE_MAP_EAST
• leaveWest - SCRIPT_ON_LEAVE_MAP_WEST

They accept 2 parameters, both optional:

• 1st - the map state. Usually named map.
• 2nd - the world state. Usually named world.

Example:

({
  leaveNorth: function (map, world) {
    // your map event code here
  }
})

Person events

There are 5 person events:

• create - SCRIPT_ON_CREATE
• destroy - SCRIPT_ON_DESTROY
• touch - SCRIPT_ON_ACTIVATE_TOUCH
• talk - SCRIPT_ON_ACTIVATE_TALK
• generator - SCRIPT_COMMAND_GENERATOR

They accept 3 parameters, all optional:

• 1st - the person state. Usually named self.
• 2nd - the map state. Usually named map.
• 3rd - the world state. Usually named world.

Example:

({
  Bob: {
    talk: function (self, map, world) {
      // your person event code here
    }
  }
})

How to…