Basic Scripting:Intervals

Intervals offer a way for specific assets to call one or more custom functions with every turn. The classic example is a sink: turn it on and set an interval that prints a "water pours from the sink" message every turn, but only if the player is in the same room as the sink. Interval functions can return text, or run custom code. If an interval function returns text, that text will be printed on its own line as part of the turn's output. Alternately, author can use intervals to run custom code that does anything, including overriding the turn.

The primary benefit of intervals is that their state is subject to undo / save / restore commands. So, going back to our sink example, if the player turns on the sink, enabling its interval, then inputs > undo, the undo command will disable the interval. Similarly, if the player turns on the sink and saves the game, restoring that saved game will turn on the sink.

startInterval({ id, callback, times = null, frequency = 1 });

• id: the id or name of the asset which owns the interval function
• callback: the function to call on each turn
• times: optionally set a number of times for the interval to repeat. If unset, will repeat indefinitely.
• frequency: set how often to trigger the callback function. If frequency is an integer of 1 or more, it will repeat every x turns. If frequency is a fraction of 1, the fraction is used as a random seed every turn. For example, frequency: 0.5 sets a 50/50 chance of printing every turn.

Examples

In the following example we create a gem and use an interval function to change its color on every turn.

MyGame.createAsset({
  class: "Thing",
  name: "rainbow gem",
  synonyms: ["gem"],
  adjectives: ["red","orange","yellow","green","blue","indigo","violet"],
  place: { in: "Crystalline Cave" },
  changeColor: function () {
    const colors = [
      "red",
      "orange",
      "yellow",
      "green",
      "blue",
      "indigo",
      "violet",
    ];
    const random_color = colors[Math.floor(Math.random() * colors.length)];
    MyGame.setVar("gem_color", random_color);
  },
  description: `The gem glows with a rich, glossy {gem_color}. `,
});
MyGame.setVar("gem_color", "blue");
MyGame.startInterval({ id: "rainbow gem", callback: "changeColor" });

In the next example, we create a radio and use an interval function to play audio every turn. If the player is in the room with the radio, a random audio clip is printed; if not, a distant static message is printed.

MyGame.createAsset({
  class: "Radio",
  name: "old fashioned radio",
  indefinite_article: "an",
  place: { on: "worn secretary" },
  descriptions: {
    look: function () {
      return `The old fashioned radio is finished in polished mahogany with a herringbone patterned grill cloth. The on/off button seems to be broken but {we} can plug it in to turn it on. Currently it is {old fashioned radio [is] pluggedIn [then] plugged in and playing[else]unplugged and silent}. `;
    },
  },
  dov: {
    plugIn: {
      with_nothing: true,
      on_success: function () {
        // startInterval when the radio is plugged in
        this.game.startInterval({ id: this.id, callback: "emit" });
        return "The radio emits a crackle of static. ";
      },
    },
    unplug: {
      with_nothing: true,
      on_success: function () {
        // stopInterval when the radio is unplugged
        this.game.stopInterval(this.id, "emit_clips");
        return "The radio shuts off with a clipped burst of static. ";
      },
    },
  },

  // It's our common convention to use emit() as our
  // as our interval function but that is arbitrary. 
  // You can use any function name you prefer.
  emit: function () {
    let msg = "";

    // Is the radio in the same room as the player?
    if(this.$is("present")) {
      // If so grab a random string from this.emit_clips.
      msg +=
        this.emit_clips[Math.floor(Math.random() * this.emit_clips.length)];
    } else {
      // Otherwise print a "distant sound" message.
      msg += "A muffled radio broadcast emanates from some other room. ";
    }
    this.game.print(msg);
  },

  // emit_clips is our array of messages to print randomly
  emit_clips: [
    "A tinny voice from the radio announces an upcoming Cubs game. ",
    "The radio's speaker vibrates with an attenuated tuba solo.",
    "A pitchman hawks Sudzo Soap on the radio. ",
    "The radio plays that big band sound complete with oomphas. ",
    "The radio broadcast is interrupted by an announcer breaking in to warn of a Martian attack. ",
    "The radio emits a brassy jazz number punctuated by staccato bursts of tap. ",
    "Judy Garland warbles on the radio. ",
    "The radio announcer promises that justice will be served on an upcoming episode of The Shadow. ",
  ],
});