Basic Scripting:Custom Variables

While authors can create variables in any scope* through custom code, it's important to note that variables scoped to window or to local methods won't be saved with the game state or respect player undo commands. In order to create variables that can be undone, saved, and restored with the game, authors can use the game.setVar() and game.getVar() methods.

MyGame.setVar("aurora_color", "green");

MyGame.getVar("aurora_color");
// returns "green"

// use hasVar() to test if a var has been set
if(MyGame.hasVar("aurora_color")){
  // do something
}

setVar() | getVar() | hasVar() only work with primitives, which means variables of type string (any "text in quotes"), int (numbers), or boolean (true or false). Passing an array or object, or a value that is null or undefined, will return false. Here are some more examples of valid values.

MyGame.setVar("wants_for_xmas", "a pony");

MyGame.setVar("counter", 10);

MyGame.setVar("pressed_button", true);

Variables saved with setVar() can be also accessed directly at game.world._vars (where it's actually stored) or game.vars (which is a convenience accessor).

Printing variables

Variables saved with setVar() can also be printed via placeholders. In this example, we use a variable to print a different description of a chest depending on its open state. We want the chest to have one description before it's opened, another when it's opened, and a third after it's been opened then re-closed. These examples are getting into slightly more advanced territory, so if you see something that doesn't make sense right now – don't panic! We'll get to it in a later tutorial.

MyGame.createAsset({
  class: "Chest",
  name: "brass chest",
  description: `It's a small but sturdy looking chest bound in brass which is currently {chest_state}. `,
  doOpen: function () { MyGame.setVar("chest_state", "yawning open") },
  doClose: function () { MyGame.setVar("chest_state", "slightly ajar") },
});
MyGame.setVar("chest_state", "tightly shut");

In this example, we use a variable as a counter to keep track of the number of times a player has entered a room.

MyGame.createAsset({
  class: "Room",
  name: "bathroom",
  description: `You've visited this bathroom {visited_bathroom} times. `,
  doMoveThatToThis: {
    "My Hero": function () {
      let count = MyGame.getVar("visited_bathroom");
      count++;
      MyGame.setVar("visited_bathroom", count);
    },
  },
});
MyGame.setVar("visited_bathroom", 0);

Further reference

To learn more about placeholders, see Customize Output: Placeholders.

* If you're new to Javascript or programming in general, the word scope may not mean anything to you. If you're just starting out with AdventureJS, you may not even need to worry about it right now. But, it's a good thing to understand. In short, scope means: who can see this variable? When we say a variable is scoped to window, we mean the browser window, and that's like calling it a global variable, which means that it can be accessed from anywhere in the code. Otherwise, depending on how you define your variables, they may have function scope (visible anywhere in just one function) or block scope (only visible in one particular block of code inside a function). For a more in-depth explanation of scope, we recommend you see this article on scope at MDN.