RPG Library ‐ Effects

An effect is a temporary condition on a character or item, such as the character being on fire or having a spell active on him.

Go here for the introduction to RPG.

Note that effects are stored in the rpg object, and not as part of the normal world system. An important side-effect of that is that the effect itself is not saved when the user saves the game. Quest does save details about who or what the effect is on and how long for, so generally this works fine, but you should consider the effect itself to be immutable.

Testing for an effect

Characters and equippable items (weapons and shields) will all have a "hasEffect" function attribute that you can use to determine if the character or item has a specific effect on it.

  if (obj.hasEffect("On fire")) {
    // ...

For other items - or if you are not sure what the thing is - use rpg.hasEffect, passing it the object and the effect.

  if (rpg.hasEffect(obj, "On fire")) {
    // ...

Creating new effects

An effect can get used in a number of ways; usually just one is applicable, but any combination is allowed. You can:

• have it do something when applied and undo it when removed
• if it is purely combat-based you can have it react whilst there
• you can have the world react to it
• have it do something at the end of the turn
• set a situation flag

This example uses the first approach.

new Effect("Light giver", {
  start:function(target) {
    target.isLight = true
    return "{nv:target:be:true} shines brightly."
  },
  finish:function(target) {
    target.isLight = false
    return "{nv:target:stop:true} shining."
  },
}

Two example effects using the second approach are below. Weapons with limited ammo are handled by giving them an effect, as seen in the first example, the second was used in the "defensive attack" skill from here.

new Effect("Ammo tracker", {
  modifyOutgoingAttack:function(attack, source) {
    if (!source.equipped) return
    if (attack.weapon.ammo === 0) {
      attack.msg("Out of ammo!", 1)
      attack.abort = true
    }
    else {
      attack.weapon.ammo--
    }
  },
})

// Give a defensive bonus
new Effect("Defensive", {
  modifyIncomingAttack:function(attack) {
    attack.offensiveBonus -= 3
  },
  suppressFinishMsg:true,
})

This is an example of the third approach. All the work is done elsewhere - all this is is flag up that the effect is active.

new Effect("Lore", {
})

This example causes the afflicted character to lose 2 health every round.

new Effect("On fire", {
  endOfTurn:function(o) {
    o.health -= 2
    return processText("{nv:char:take:true} 2 points of damage due to being on fire.", {char:o})
  },
})

This effect sets a situation flag on the target. It also uses "start" and "finish" to tell the user about it.

new Effect("Muted", {
  flags:['mute'],
  start:function(target) {
    return "{nv:target:can:true} no longer talk."
  },
  finish:function(target) {
    return "{nv:target:can:true} talk again."
  },
})

Text processor support

You can use the "effect" directive, which will test if an effect is on the player. This is useful if the effect will cause the player to see the world differently. The second parameter is the name of the effect, and must match exactly, including capitalisation. The third is the special text to use if the effect is on the player, while the fourth - which is optional - is used when the effect is not on the player.

"You see a {effect:Lore:Kalrish sovereign, probably about 300 years old:grubby coin}."

In fact there are some built-in shortcuts for more common effects, "lore" for "Lore", "darkV" for "Dark vision", "trueV" for "True vision" and "befuddled" for "Befuddled". The above could therefore be written:

"You see a {lore:Kalrish sovereign, probably about 300 years old:grubby coin}."

The names of these effects are set in rpg/lang-en.js, so can be modified if necessary.

Attributes for Effects

The "source" is the character, item, or whatever that the effect is on.

name: The skill is identified in code using this._

alias: The user sees this name. Defaults to the name, and mostly for people translating to another language.

css: In the side pane, display using this CSS class.

doNotList: In the side pane, do not display.

tooltip: Used in the side pane.

modifyOutgoingAttack(attack, source): This function is run when this effect is active, before the attack is assigned to a target. For example, an on-going effect might add a bonus to hit. You can use it to add output text by appending comments to attack.report.

modifyIncomingAttack(attack, source): This function is run when a character, the target, receives an attack, and this effect is on-going. For example, a spell might give a reduction to damage received. You can use it to add output text by appending comments to attack.report.

start(target): Run when the effect starts, this should not print anything, but can return a string.

finish(target): Run when the effect ends, this should not print anything, but can return a string. If it does not return a string, a default message will be printed (unless suppressFinishMsg is true).

endOfTurn(target): Run when the turn ends.

suppressFinishMsg: When the effect finishes, Quest will inform the user unless this is set to true.

category: A string - a character can only have one effect of any specific category at a time. If a new effect is applied, an effect already there will be terminated. For example, casting Stoneskin will cancel Steelskin.