TWiki Home Tharsis . Website . UsingTheAreaEngine Tharsis webs:
Design | Guilds | Combat | Website
Website . { Home | Changes | Index | Search | Go }

The Area Engine

Overview

The Area Engine is a "device" that allows builders to make areas in an easier fashion - at least that is the idea. Down the track it should even have a graphical interface!

Essentially it is a single "controller" that creates the rooms for you based on an area file. As a builder you write the area file and the area generates itself - no more creating rooms. At this time the area file only controls the rooms, their exits and descriptions, and the placement of externally created objects/monsters. It will soon provide the ability to define objects and monsters. After that, I'm open to suggestions.

File Format

The area file is a normal text file - you can edit the file in notepad, under windows, and using ed inside the mud.

The file is broken into a series of sections, each section having a heading and some content. Headings have the form [heading-name], and a section is all the content from its heading until the heading for the next section. Section headings have to be on a single line of their own.

The following shows you the outline of the file. A complete area file will probably include the sections shown here as well as having lots of content inside each section

[general]

[map]
# This section defines the layout of your area

[exits]
# This section defines special exits - doors/blocking/etc

[rooms]
# This section defines what your rooms look like
# and defines the external rooms (links to other areas)

[objects]
# This section manages hand-coded objects like monsters
# and treasures

Comments

You can put comments anywhere in the area file. Comments are notes that are completely ignored by the Area Engine. Comments are lines beginning with a #

# I am a comment
[general]
I am not a comment.

[map]
# I am another comment
# that goes over multiple lines
I am not a comment

The [general] section

This section is used to define some global variables: constants and rules that apply across the whola area.

Supported constants at this time are:

Name Purpose
domain The numeric id for your domain - ask a wiz. This makes all rooms be in this domain
startroom The roomkey for the room which the player will start in by default

Each constant goes on a line of its own and is assigned a value using the = operator.

For example:

[general]
# Define 'domain' to be 123
domain=123

#define 'startroom' to be 'hallway'
startroom=hallway

The [map] section

The map section is used to define all the rooms in the area and the exits between them.

This section does not define the contents of rooms, nor the room descriptions, just the exits/links between rooms.

Each room is defined on a single line. The line has the format:

room_key : exit = destination , exit = destination ....
So each room has a room_key, which is a unique name for this room. It might be a word, as in the following example, or it might just be a number - maybe you just number your rooms from 1 to 100.

After the ":" are the exits for the room, separated with commas. Each exit is a direction, an "=" sign, and the room_key for the destination.

So - the following map is used to describe a 2 story house with several rooms:

[general]
# Make people start in the lounge
startroom=lounge

[map]
# This comment is just describing the layout below, 
#   the area creator ignores it completely
# The ground floor map looks like:

# kitchen   -  dining  
#    |      \     |
# hallway    lounge - outside
#    |
# hallway - bedroom
#    |
# hallway - bedroom
#    <

# The second story looks like

# bedroom - onsuite
#   |
# landing
#   >

# The "outside" room is not in this area, it's the room for entering this area

# Below here are the actual rooms with their exits
kitchen: e=dining,s=hallway1,se=lounge
dining: w=kitchen,s=lounge
lounge: nw=kitchen,n=dining,frontdoor=outside
hallway1: n=kitchen,s=hallway2
hallway2: n=hallway1,s=hallway3,e=bedroom1
hallway3: n=hallway2,e=bedroom2,u=landing
bedroom1: w=hallway1
bedroom2: w=hallway2
landing: d=hallway3,n=masterbedroom
masterbedroom: s=landing,e=onsuite
onsuite:w=masterbedroom

Note that there is no room with a room_key = "outside". This is because the room is specially coded - it is either a hand-coded room which you want to connect with, or it is a room managed by a different area engine.

The [exits] section

The [exits] section is sort of optional.

In this section you define the details of exits. Details include things like

So, for example, in the map above there are exits described as "e", "w" and so on. By default this means the exits in the rooms will be exactly that: "e" and "w", not "east" and "west".

More interestingly the definition for room "lounge" has an exit called "frontdoor", which leads to the outside. It seems unlikely that we want the player to see that - rather we want them to see an "east" exit, and for it to be a wooden door.

The following shows the configuration for the "frontdoor" exit

[exits]
# define the frontdoor as a normal east exit.  In the
# future we might define this as an actual door which opens
# and closes.  See the 'door' exit module for help on how to do this.
exit: frontdoor
direction: east

The [rooms] section

The [rooms] section defines the appearance of rooms - the description, items, light levels, etc. This section DOES NOT define the exits/connections between rooms - that is done in the [map] section.

The [rooms] section is broken up into a series of individual room descriptions. Each room description can apply to one or more of the rooms which are defined in the [map] section. This is deliberately done to allow you to use a generic room description for multiple rooms in your area.

The [rooms] section also identifies rooms that are outside your area, or have been specially hand-coded by a wizard. You need to identify these rooms and tell the Area Engine how to find them so that your rooms can link to the rest of the mud.

Rooms that are part of your area

Each such room description starts with a line that begins with room: All subsequent lines until the next room: (or external ) are considered to be part of the room description.

[rooms]
room:
# this is the first room description
# and so is this

room:
# this is the description for the next room

Rooms that are outside your area or are hand coded

In our example map above the "outside" room is such an example. It is not to be created by the area engine, but we want the "lounge" to be able to connect to it.

Each external room description starts with a line that begins with external: . All subsequent lines until the next room: or external are considered to be part of identification of the external room.

[rooms]
room:
# this is the first room description
# and so is this

external: outside
# this is the 'outside' room and is a room that is probably a room in an adjoining area.
# The Area Engine will expect to be told where to find the file/map for the external room.

room:
# this is the description for the next room

Understanding how room descriptions are allocated

The Area Engine uses room descriptions whenever it needs to create a room - it does not use this process when linking to external rooms.

Putting a room in the [rooms] section doesn't cause the room to be created, the actual rooms that get created are controlled by the [map] section. The Area Engine examines the [map] section to work out which rooms should exist.

When a room is to be created the Area Engine will:

  1. check to see if there is an external definition in the [rooms] and if so then use that external room.
  2. assuming no external room can be found then it will get the entire set of room descriptions from the [rooms],
  3. determine the subset of the descriptions that are possibilities for this room, and
  4. randomly choose one of these.

The important thing to understand is how the Area Engine performs the third step - the process of working out which room descriptions can apply to a given room. It is possible for you to create an area with a single room description which can apply to all rooms, it is also possible to create an area in which each room has only a single applicable room description (in which case you have as many room descriptions as you do rooms in your [map]), and anywhere in-between.

The Area Engine works out which room descriptions can be applied to a room using the room: line.

The room: line has the form:

room: room_key_pattern,room_key_pattern,room_key_pattern,etc

The room_key_pattern is a string which indicates which of the room_keys from the [map] the room description can apply to. The pattern can include an "*" to match any characters. As shown it is possible to specify multiple patterns by separating them with commas.

A special circumstance applies if you specify NO room_key_patterns. Rooms descriptions with no room_key_patterns may be used for rooms which match no other room descriptions.

For example, presuming we have the map of the house from above we can use the following descriptions:

[rooms]
# This description applies to only the kitchen
room: kitchen
short: The kitchen
long: This is the kitchen, it is full of cooking stuff.

# This description can apply to any bedroom.
# Note that there are other descriptions below which have the 
# room_key_patterns that match the bedrooms, and thus the
# Area Engine will randomly choose one of these when assigning
# a description to each bedroom
room: *bedroom*
short: A bedroom
long: A room with a messy bed in it, someone has slept here recently.

# This description can apply to any bedroom, but is specified
# using commas instead of a * wildcard.
room: bedroom1, bedroom2, masterbedroom
short: A bedroom
long: A room with a very neat and tidy bed in it.

# This description will apply to any room that does not match
# any of the other descriptions (IE all non-bedrooms and non-kitchens)
room:
short: A room
long: This room is completely bare.

# This description can also apply to any room that does not
# match the other definitions with room_key_patterns.  
# Thus the Area Engine will randomly choose either this description 
# or the one immediately above when describing all non-bedroom
# and non-kitchen rooms.
room:
short: A room
long: This room is tastefully furnished.

# This tells the Area Engine where to find the 'outside' room.
# It tells it that it is the 'street1' room in the 'town' domain.
external: outside
domain: DOM_TOWN
file: street1

What can go in a room description block

Format is "itemname":description. You can have the itemname several times and the user will get a randomly chosen one of the descriptions You can have a description of ##otheritemname, then the item is considered to be using the description of the "otheritem"

What can go into an external room identification block

An external room block is used to tell the area engine about a room which exists outside the current area.

Examples include rooms that have been hand-coded by a wizard and rooms within other areas controlled by the area engine.

When linking to a room which has been hand coded by a wizard (or builder) you must specify:

When linking to a room which is part of another area-engine controlled area you must specify:

The [objects] section

The [objects] section is used to manage the placement of objects that are not defined within the area file; like hand-coded, or specially-coded monsters and treasures, perhaps created with the Blob.

The [objects] section is is broken up into a series of individual objectdefinitions. Each description starts with a line that begins with object:

All subsequent lines until the next object: are considered to be part of the same object definition.

[objects]
object: rabbit
# this is the definition for the 'rabbit' monster
# and so is this

object: table
# this is the definition for the 'table' treasure

Each object: line has the format:

object: object_key

The object_key is a unique keyword used to identify the object in other parts of the area file. You can use any keyword you like.

What can go in a object description block

Each object description block is a series of lines which have the form
keyword: value

Possible keywords, and their meanings are:

KeywordRequiredMeaning
file yes This is the name of the hand-coded file for the object

For example: file: monsters/big_bag_guy

placement yes This controls the placement of the object within the area - which room or rooms the object can be placed in.

At least one room_key must be specified. The room_key can include wildcards. Multiple keys can be specified by separating them with commas. If the specified room_keys match more than one room then the object will be randomly placed.

For example: placement: kitchen,bedroom*

count no This controls how many of the object are placed in the area. It defaults to 1.
repop no This controls whether the object will repopulate.

Valid values are "default" and "none".

A value of "default" will cause the object to be recreated (if it is destroyed) following the normal mud rules. A value of "none" will mean the object is never recreated after it is destroyed. This defaults to "default".

Advanced stuff

Sometimes, or probably reguarly, you want to do more than just make a map and put some monsters and objects in it.

For example you might want exits to only be traversable if a certain monster is dead, or you might want a weapon to have a certain special attack, or ability when wielded.

This advanced functionality is provided through the use of extension modules .

Extension modules are things that you can use on almost anything facet in the Area Engine to make it behave in new and exciting ways.

Possible "targets" for extension modules are:

Modules are applied to a target using a common syntax. Within the target you write

   module: MODULE_NAME {
      KEY: VALUE
      KEY: VALUE
   }

or more simply:

   MODULE_NAME {
      KEY: VALUE
      KEY: VALUE
   }

The specified MODULE_NAME is the most important bit - it determines which module you are using, and thus what advanced effect you are applying. The next most important things is the pair of braces {}. The opening brace MUST appear on the end of the line containing the MODULE_NAME, and the closing brace MUST appear on a line of its own.

The KEY/VALUE pairs are used to configure the module. For example in the "exit" module called "guild_block", there is a keys which indicate which guild you have to be in to be able to use the exit, and in the "exit" module called "door" there is a key to indicate whether the door is lockable.

Available Modules

The actual modules available will grow over time, and this page is likely to fall out of date. But at the time of writing the following modules exist.

Monster Modules

Module: appearance
Desc: Allows you to configure the appearance of the monster.
Keys:
  • clear_ids: if given then clears all aliases and adjectives. Dangerous to use after other modules
  • race: sets the race of the being
  • long: sets the long desc
  • first_alias: adds this as the first alias, and thus the one that drives the short desc
  • alias: adds this an alias
  • first_adj: adds this as the first adjective and thus the one that drives the short desc
  • adj: adds this as an adjective
  • unique: if given then flags the item as 'appearing unique', thus stopping the short being prefixed with a/an/the/etc
  • no_prefix: if given then flags the item as not wanting a prefix. not certain of the diff with unique

Module: stats
Desc: Used to alter the stats/skills/level/abilities of the monster.
Each key takes a value from 1 to 5, with 1 being the least amount of change and 5 being the most.
  • unskilled: decreases level and thus all skills and stats, happens first
  • skilled: increases level and thus all skills and stats, happens first
  • old: increases wis, decreases all other stats,
  • young: decreases all stats
  • slow: decreases dex and co.de.dodge
  • agile: increases dex and co.de.dodge
  • smart: increases int and wis
  • stupid: decreases int and wis
  • pretty: increases cha
  • ugly: decreases cha
  • monk: increases unarmed skills
  • warrior: increases combat skills
  • thief: increases stealth skills
  • mage: increases magic skills
  • priest: increases faith skills
  • healthy: increases ot.st & thus hp
  • large: increases str, block, ot.st. decreases dodge.
  • small: decreases str, block, ot.st. increases dodge.
  • aggressive: increases auto-attack chance
  • hoarder: sets likelihood of collecting items
  • rich: increases money
  • poor: decreases money

Exit Modules

Module: appearance
Desc: Allows you to configure the appearance of the exit.
Be very careful in using this with doors. You should probably define the module AFTER the door module. You should also be careful altering the messages.
Keys:
  • hidden : (optional) If given then the exit will be hidden.
  • exit_msg : (optional) Sets the message the person will see, before leaving the room.
  • exit_others_msg : (optional) Sets the message the message others will see as the person leaves the room. Defaults to the exit_msg.
  • enter_msg : (optional) Sets the message the message the person will see upon arriving at the next room.
  • enter_others_msg : (optional) Sets the message others will see as the person arrives in the next room. Defaults to the enter_msg.

Module: guild_block
Desc: Blocks the exit unless the user is a member of the correct guild.
Keys:
  • guild : (mandatory) The id of the guild to let through. Eg: WarriorGuildId?, ThiefGuildId?.
  • message : (optional) A message to show to players who are not in the guild.

Module: door
Desc: Makes the exit a door. You must make BOTH sides of the exit a door for it to work properly.
Keys:
  • id : (mandatory) The id the door, which must be the same on both sides of the exit. It is used to keep the two sides in sync.
  • type : (optional) By default you have a wooden_door. Other types include wooden_gate, steel_door,steel_gate,iron_gate and trapdoor
  • auto_close : (optional) If set to 0 then the door will not automatically shut.
  • key : (optional) If given the door becomes lockable and requires a key with the given id
  • locked : (optional) By default lockable doors are locked, if set to 0 the door will not be initially locked.

Module example

The following is an example of using the "guild_block" module to stop non-thieves from using the exit going "east" from "room1" to "room2", and the "door" module to make the exit a steel gate.

[map]
# Just two rooms, and we give the exit from room1 to 2 a special name.
room1: blockedExit=room2
room2: west=room1

[exits]
# configure the exit called 'blockedExit'
exit: blockedExit
# make it go east
direction: east
# use 'door' module to add a gate
door {
   id: mydoor
   type: steel_gate
}
# use 'guild_block' module to stop non-thieves.  Note the use of the optional 'module:' prefix
module: guild_block {
   guild: ThiefGuildId
   message: You have to be a thief to go east!
}

Topic UsingTheAreaEngine . { Edit | Attach | Ref-By | Printable | Diffs | r1.18 | > | r1.17 | > | r1.16 | More }
Revision r1.18 - 04 Feb 2008 - 03:08 GMT - FantoM
Parents: WebHome > BuilderPages
Copyright © 2001 by the contributing authors. All material on this collaboration tool is the property of the contributing authors.
Ideas, requests, problems regarding Tharsis? Send feedback.