Template ‐ TAKEABLE

Use this template to allow the player to pick something up and drop it. Both use the moveToFrom function to do the work, which will call afterMove(options) if it exists and the move is successful.

createItem("old_newspaper", TAKEABLE(), {
  examine:'A newspaper from the eighties; yellow with age.',
  read:'You spend a few minutes reading about what happens on the day 14th June 1987 (or perhaps the day before).',
  loc:'basement',
  afterMove:function(options) {
    if (options.toLoc === game.player.name) msg("Great, now you are carrying an old newspaper...")
  },
})

createItem("postit_note", TAKEABLE(), {
  alias:'post-it note',
  examine:"The sticky yellow note has something written on it; the number 17.",
  loc:'office',
  scenery:true,
})

NOTE: Several other templates (such as WEARABLE and EDIBLE) include this one, so there is no need to use both.

Events

When an object is moved from a source location to a destination location (in fact any time "moveToFrom" is used):

• the source location's afterTakeFrom(item) function is run
• the destination location's afterDropIn(item) function is run
• the item's afterMove(toLoc, fromLoc) function is run

Other attributes

The attribute "takeable" will be true.

The function takeFromLoc(char) can be used to change when an item is taken from. This can be useful for weird objects, such as ropes, where you need to consider which end of the rope is picked up.

Use "testDrop" and "testTake" to control whether the item can be dropped or picked up in the current situation. Each take a dictionary parameter, which will include "char", the character doing it, and "multiple", a Boolean that will be true if this is one of several items the player is trying to drop or take. The example shows how the "multiple" value can be used. The function should return true if the item can be picked up, or give a message saying why and return false otherwise.

  testTake:function(options) {
    if (this.nailed_down) {
      msg(prefix(this, options) + "It is nailed down!")
      return false
    }
    return true
  }

For custom take and drop messages, use "msgTake" and "msgDrop", strings that can use "char" and "item" as text processor parameters. For example:

  msgTake:"{nv:char:take:true} {nm:item:the}.",

Not takeable

As an aside, if you have an item that cannot be picked up, but there is a chance the player will try to do so, you can just give the item a "take" attribute.

createItem("old_newspaper", {
  examine:'A newspaper from the eighties; yellow with age.',
  read:'You spend a few minutes reading about what happens on the day 14th June 1987 (or perhaps the day before).',
  loc:'basement',
  take:'It seems to be glued down.'
})

Handling Location

This is only relevant to items that are both TAKEABLE and can be more than one location at a time (as is the case for the ROPE and COUNTABLE templates). It is included for completeness, but authors will very rarely have to worry about it.

The standard TAKE and DROP commands use the "moveToFrom" function attribute, which uses the "loc" attribute. Similarly, when working out what a character is carrying, Quest uses an item's "isUltimatelyHeldBy" function attribute. If your item handles its location another way, then you will need a custom "moveToFrom" and "isUltimatelyHeldBy" attributes. This is typically because an item can be in

For "isUltimatelyHeldBy", there is a util.multiIsUltimatelyHeldBy which handles multiple locations. The COUNTABLE template assembles an array of location names, and passes this to util.multiIsUltimatelyHeldBy to do the work.

  res.isUltimatelyHeldBy = function(obj) {
    const locs = []
    for (const key in this.countableLocs) {
      if (this.countableLocs[key]) locs.push(key)
    }
    return util.multiIsUltimatelyHeldBy(obj, locs) 
  },