Chapter 5: Working with entities

Scripts interact with the game world through entity references — creatures, objects, rooms, and prototypes. This chapter covers how to find entities, query their properties, and act on them.

Entity types

Querying entities

Common queries:

[name $actor]         # display name: "Gandalf"
[level $actor]        # level: 42
[class $actor]        # class name: "Mage"
[alignment $actor]    # "good", "evil", or "neutral"
[position $actor]     # "standing", "sleeping", etc.
[vnum $self]          # mob vnum: 1200
[room $self]          # the room entity the mob is in
[gen $actor]          # remort generation

Pronoun builtins:

[he $actor]           # "he", "she", or "it"
[him $actor]          # "him", "her", or "it"
[his $actor]          # "his", "her", or "its"

Finding creatures in a room

people (or its alias creatures) returns all the creatures in a room as an iterable you can loop over or count:

after command (say) {
  require [keyword $args headcount]
  let room [room $self]
  let n [count [people $room]]
  do "say There are $n creatures here."
}

Checking creature properties

after enter {
  require [isplayer $actor]
  if [gt [level $actor] 30] {
    do "say A powerful adventurer approaches."
  }
}

• [isplayer $actor] — true if $actor is a player (not an NPC).
• [ismob $actor] — true if $actor is an NPC.

Working with objects

Getting the objects on a creature:

[objects $actor]      # everything: carried, worn, implanted
[inventory $actor]    # carried items only
[equipment $actor]    # worn/equipped items only
[implants $actor]     # implanted items only

For containers and rooms:

[contents $chest]     # objects inside a container
[contents $room]      # objects on the floor of a room (alias: [objects $room])

Checking what someone carries

isholding checks if an entity has an object of a given vnum:

after command (say) {
  require [keyword $args trade]
  if [isholding $actor 5001] {
    do "say Ah, you have the gem! I will take it."
  } else {
    do "say Bring me the gem (vnum 5001) and we can trade."
  }
}

iswearing checks worn equipment and implants:

if [iswearing $actor 5050] {
  do "say Nice armor!"
}

Selecting from collections

select filters an iterable with a predicate:

after command (say) {
  require [keyword $args players]
  let players [select [people [room $self]] { <c> [isplayer $c] }]
  each $players { <p>
    do "say I see player [name $p]."
  }
}

select returns a new iterable containing only the elements where the block returned true. The block { <c> [isplayer $c] } is the predicate — it receives each creature and returns a boolean.

Picking a random entity

choose picks a random element from an iterable:

after tick {
  let target [choose [people [room $self]]]
  if [exists $target] {
    do "say Hey [name $target], nice day isn't it?"
  }
}

The tick event fires periodically. This mob picks a random creature in the room and talks to them.

Prototypes

Prototypes are the templates that live entities are loaded from. Use them with mob and object:

[mob 1200]            # the mob prototype with vnum 1200
[object 5001]         # the object prototype with vnum 5001

Check if a creature matches a prototype with vnum:

if [eq [vnum $self] 1200] {
  # this mob is vnum 1200
}

Check aliases on a prototype:

[alias [mob 1200]]    # the alias keywords of mob 1200

Loading objects and mobs

Action commands that add entities to the world:

oload 5001                # load object 5001 to the mob's inventory
oload 5001 $actor         # load it into the player's inventory
oload 5001 [room $self]   # load it onto the room floor

mload 1201                # load mob 1201 into this room
mload 1201 [room 3000]    # load mob 1201 into room 3000

Moving entities

trans $actor [room 3001]  # teleport the player to room 3001

Example: a shopkeeper who checks your purse

after command (say) {
  require [keyword $args buy purchase]
  if [not [isholding $actor 5010]] {
    do "say You need a gold coin (5010) to buy from me."
  } else {
    opurge 5010
    oload 5020 $actor
    do "say Here you go, [name $actor]. Enjoy!"
  }
}

opurge 5010 removes one object of vnum 5010 from the mob's inventory (or the actor's, depending on context). oload 5020 $actor loads object 5020 into the player's inventory.

Key points

• Entity queries: name, level, class, vnum, room, alignment, position, he/him/his.
• Creature iterables: people, creatures.
• Object iterables: objects, inventory, equipment, implants, contents.
• Predicates: isplayer, ismob, isholding, iswearing.
• Selection: select iter { <x> [predicate $x] }.
• Random choice: choose.
• Loading: oload vnum, mload vnum.
• Moving: trans entity room.

Next: Chapter 6: Defining functions