Traits

Adding certain tags to an entity applies extra behaviour to that entity. These are traits.

Carryable

An entities with the carryable tag can be picked up and moved around by the player. They can be manipulated with the following verbs get, drop, put

item: ball
name: bouncy ball
description: A small rubber super bouncy ball
tags: [carryable]

Containers

An entity with the container tag is considered a container. By default a container support putting items inside it, but can also be configured to allow items to be on top of it.

Containers may be carryable, openable, and transparent

An openable container must first be opened before items can be placed in, or retrieved from the container. A contents of a transparent container will always be visible, even if the container is closed.

item: backpack
name: backpack
description: An old tattered canvas backpack.
tags: [carryable, container]

placement / Relative Location

The placement field defines how items are placed within the container. A shelf might have items placed on it, whereas a chest would have items placed in it. This is defined using the placement property. Supported values are in and on. Containers use in by default.

(Tip: YAML treats on as a boolean value, so be sure to put the value inside quotation marks)

Closable/Openable containers

Containers can also be given the closable/openable traits. If a container is closed, then items can not be added to or removed.

item: table
name: table
description: A large wooden table.
placement: "on"
tags: [container]

contentsVisibleWhen

By default, a container's contents are visible according to the open/closed/transparent rules above. A container can instead define its own contentsVisibleWhen() function to fully control when its contents can be seen - for example a high shelf that's only visible while standing on something tall enough to see onto it:

item: trunk
name: trunk
location: storageCloset
tags: [pushable]
isStoodOn(): getPlayer().standing_on == 'trunk'
---
item: shelf
name: shelf
location: storageCloset
placement: "on"
tags: [container]
contentsVisibleWhen(): trunk.isStoodOn()
---
item: candle
name: candle
location: shelf
tags: [carryable]

The candle here is only visible/reachable while standing on the trunk - and, since the predicate lives on the shelf rather than the candle, this applies to anything placed on the shelf, and stops applying the moment an item is picked up (moved out of the shelf). Defining contentsVisibleWhen on a container replaces the default open/closed/transparent check entirely, so if the container is also openable, include is_open in your own expression if you still want that behaviour.

Carryable

Items tagged with carryable or carried can be picked up, dropped and put in containers. They have get, drop, and put verbs.

If an item is tagged with carried then it starts off in the player's inventory.

examples

item: ball
description: A small ball
location: northRoom
tags: 
  - carryable

Wearable

Items tagged with wearable or worn are items that can be worn. The have the wear and remove verbs.

If an item is tagged with worn then it starts off being worn by the player.

item: cloak
tags: ["carryable", "wearable"],
location : "northRoom",

Openable/Closable

Items tagged with openable/closable implicitly have open and close verbs, and an is_open property.

openable indicates that the item is closed. closable indicates the item start open.

item: greenDoor
location: northRoom
description: The green door
tags:  ["openable"],
before: 
  examine(this): 
    if: "this.is_open",
    then: "print('The door is open')",
    else: "print('The door is closed')"

Lockable/Locked

Items with the lockable tag can be locked. lockable items gain the lock and unlock verbs. They are also have is_locked, and key properties.

The key property can by used to specify an item that can be used to unlock this item.

If lockable is combined with openable then the item cannot be opened until it is unlocked.

item: "door"
location: northRoom
description: The green door
key: brass_key
tags: 
  - openable
  - lockable
  - locked
before:
    examine(this): 
        if: this.is_open
        then: print('The door is open')
        else: print('The door is closed')
---
item: brass_key
location: northRoom,
verbs: 
  - unlock.with
  - lock.with
tags: 
  - carryable

Pushable

Items tagged with pushable can be pushed. They are given the push verb. Pushable items can be pushed into adjacent rooms without being picked up.

item: box
location: northRoom
tags: 
  - pushable

Light Sources

Items with the lightSource tag are considered light sources.

item: torch,
tags: 
  - carryable
  - lightSource

Hidden

An item with the hidden tag cannot be seen.

The reveal function can be used to unhide it.

item: diamond
location: rubbishHeap
tags: 
  - carryable, 
  - hidden
---
item: rubbishHeap
description: A pile of stinking rubbish
location : northRoom
after:
  examine(this): 
    if: hasTag(diamond,'hidden')
    then: 
      - reveal(diamond)
      - print('You find a diamond')

onlyVisibleInDark

Items tagged with onlyVisibleInDark are only visible while their room is dark - they are hidden in the light (eg glow-in-the-dark items that would otherwise blend in).

room: northRoom
description: >
  A small square room
tags:
  - start
  - dark
---
item: stickers
description: >
  glow in the dark stickers
location: northRoom
tags: 
  - carryable
  - onlyVisibleInDark

NPC

Items tagged with npc have and implicit onMove function added to them. This automatically prints a message when the npc item moves between locations.