Tharsis . Website . UsingTheAreaEngine (r1.5)	Tharsis webs: Design | Guilds | Combat | Website
	Website . { Home | Changes | Index | Search | Go }

The Area Engine

• The Area Engine
  • Overview
  • File Format
    • Comments
    • The [general] section
    • The [map] section
    • The [exitnames] section
    • The [specialrooms] section
    • The [rooms] section
      • Understanding how room descriptions are allocated
      • What can go in a room description block
    • The [specialmonsters] section

Overview

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 and their exits, but it will soon provide the ability to place monsters, and then to define monsters. After that, I'm open to suggestions.

File Format

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

[exitnames]
# This section defines exit names/doors/etc

[specialrooms]
# This section manages links to hand-coded rooms

[rooms]
# This section defines what your rooms look like

[specialmonsters]
# This section manages hand-coded monsters

[monsters]
# This section defines monsters for your area

Comments

# 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

Supported constants at this time are:

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

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:

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 [exitnames] section

The [exitnames] section is sort of optional.

In this section you define the details of exits. At this time you can only define the "full name" for an exit.

So, for example, in the map above there are exits described as "e", "w" and so on. In this section you can define the full detail of "east" and "west".

More interestingly the definition for room "lounge" has an exit called "frontdoor", which leads to the outside. For simplicity we could add an entry into the [exitnames] which says "frontdoor" is "east". The player would then never see an exit called "frontdoor", and the lounge would contain an "east" exit.

[exitnames]
# define normal directions
e=east
w=west
n=north
s=south
u=up
d=down

# define the frontdoor as a normal east exit.  In the
# future we might define this as an actual door which opens
# and closes
frontdoor=east

The [specialrooms] section

The [specialrooms] section is used to define rooms that are not to be controlled by the area engine, but are linked to by the rest of the map.

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.

At this time it is only possible to link to hand-coded rooms such as those created by the blob. It is not possible to link to rooms in a different map controlled by the area engine.

To link the lounge to a hand-coded room called "thestreet.c" would require the following:

[specialrooms]
outside=thestreet.c

For this to work the "thestreet.c" file would have to be in the same directory as the area engine map configuration file. In most builder-managed domains this is not the case, the "thestreet.c" file is in the rooms directory:

[specialrooms]
outside=rooms/thestreet.c

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.

Each room description starts with a line that begins with room: All subsequent lines until the next room: 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

Understanding how room descriptions are allocated

The rooms that get created are totally controlled by the [map] section.

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

1. get the entire set of room descriptions,
2. determine the subset of the descriptions that are possibilities for this room, and
3. randomly choose one of these.

The important thing to understand is how the Area Engine performs the second 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.

What can go in a room description block

The [specialmonsters] section

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