Builder Documentation

This page contains guidelines and implementation details pertinent to world content builders.

All builders should be familiar with basic builder commands in Evennia. The Builder Docs page from the Evennia wiki and its contents are the best resource for this.

File Locations

Prototype Files

When creating groups of objects with similar characteristics, builders should employ the spawner system. The spawner relies on prototype module files, which are located in the world/content/ directory.

See the Spawner documentation for more details.

Build Scripts

We encourage the use of batchcommand scripts over batchcode scripts to allow all builders to work on world content without needing to know a lot of Python. Build scripts are located in their respective area directories under world/content.

See the Batch Command Processor documentation for more details.

Colors

Builders are encouraged to use color creatively in their content and descriptions. The "bright white" code (|w) can be used to highlight text in place of "bold".

The following color conventions have been established for the certain game elements:

• Archetypes - Cyan ( |c )
• Traits - Dark Cyan / Teal ( |C )
• Skills - Dark Magenta / Purple ( |M )
• Headings - Dark Yellow ( |Y )
• Damage - Red ( |r )
• Toughness - Yellow ( |y )
• Range - Dark Green ( |G )
• Places - Green ( |g )
• Details - White ( |w )

See the Evennia Color documentation for more information on color codes.

Rooms

IDs and Zoning

Zones in Ainneve can be composed of multiple build scripts within the world/content/ directory. Within a given build script, each room should be given a unique ID-alias. Rooms within a script should have a an id made up of a unique string (usually matching the script file's name), a pound sign, and a two-digit number. When using the @dig or @tunnel commands, builders should include one alias with this format, such as scriptname#01.

Zones are larger areas and are represented using Evennias tagging feature, as described in the Evennia Zoning system tutorial.

The example below shows creation of rooms with ID-aliases. The ID-alias is then used in the @tag command.

# example using @dig from a build script named 'rp-square.ev'
#
@dig/tel Town Square;rp-square#01 = riverport,limbo
#
# set zone tag
#
@tag rp-square#01 = riverport : zone
#
# example using @tunnel
#
@tunnel n = Along Main Street;main street;rp-square#02
#
# set zone tag
#
@tag rp-square#02 = riverport : zone
#

Details and Time-Based Descriptions

The base room typeclass in Ainneve inherits from the ExtendedRoom contributed module. This means that all rooms support the creation of room details, as well as descriptions that can vary based on season and time of day.

In general, when creating a room that has details, it is a good idea to highlight the detail's key within the room description using a different color code. The detail's description is then created with the @detail command. Here's a sample batchcommand script:

# create and move into the room
#
@dig/tel Test Room = test; limbo
#
# set the room's description
#
@desc 
  Made up of flat gray planes, this room is an empty cube. The room is 
  illuminated by a single, blindingly bright window in the wall to your
  left. To your right, you see a small |wniche|n in the wall.
#
# set a description for the niche
#
@detail niche =
  Within the niche, you see a small glass vase holding a single purple violet.
#

If you are interested in using seasonal descriptions, see help @desc for more.

Terrain Types

Each room also has a terrain type which affects the movement cost to characters entering the room. The available terrain types are:

.

Terrain Type Code	Description	Movement Cost	Movement Delay
EASY	Indoor and flat urban areas, roads, rolling meadows, and sparse forested areas.	1	0
MODERATE	Moderately steep hills and roadways, and rocky landscapes that require careful footing.	2	1
DIFFICULT	Steep, mountainous areas or dense forests.	3	2
MUD	Sticky, muddy, bog-like areas.	3	2
ICE	Frozen landscapes; tundra.	3	2
QUICKSAND	Quicksand	5	4
SNOW	Snow covered terrain.	4	3
VEGETATION	Heavily overgrown areas.	2	1
THICKET	Dense, thorny brambles.	2	1
DEEPWATER	Water too deep to wade through.	3	3

By default, new rooms are created with the EASY terrain type.

To set the terrain property on the current room, use the @terrain command:

@terrain = VEGETATION

Capacity

The capacity of a room is represented by its max_chars property, where max_chars can be any positive integer or zero, with zero indicating "unlimited."

By default, new rooms are created with their capacity set to 0.

To set a room's max_chars property, use the @capacity command:

@capacity = 5

NPC Creation

NPC creation is handled utilizing the '@spawn' command. Available prototypes (see content/prototypes_mobs.py) will be displayed if no definition is given.

Please see the Character Creation Manual for standard NPC definitions.

Sample NPC

Please see the following example of a sample NPC.

RABBIT = {
    "key":"a rabbit npc",
    "sdesc": "a small rabbit",
    "tag": ["NPC"],
    "typeclass": "typeclasses.characters.NPC",
    "desc": "This is a small, fluffy white rabbit. It is likely harmless",
    "traits": {'STR': 5, 'DEX': 5, 'PER': 5, 'CHA': 5, 'INT': 5, 'VIT': 5,
               'BM': 5, 'WM': 5, 'MAG': 10,
               'REFL': 5, 'FORT': 5, 'WILL': 5, 'ENC': 50,
               'HP': 5, 'MV': 5, 'SP': 5, 'LV': 1, 'ACT': 5,
               'ATKM': 5, 'DEF': 5, 'ATKR': 5, 'PP': 5, 'ATKU': 5},
    "skills": {'escape': 1, 'climb': 1, 'jump': 1,
               'lockpick': 1, 'listen': 1, 'sense': 1,
               'appraise': 1, 'medicine': 1, 'survival': 1,
               'balance': 1, 'sneak': 1, 'throwing': 1,
               'animal': 1, 'barter': 1, 'leadership': 1},
}

Key vs Sdesc

Both the key and the sdesc are important for NPCs. Builders can access the key with admin commands, such as @examine, and in system-wide searches. The sdesc is displayed to users and admins as the NPC's in-game description, so it can appear in say, pose, or emote actions involving the NPC. See the RP System Contrib module's docstring for more information.

Tag

All NPCs should be tagged with "NPC" at a minimum for easy retrieval. As we develop more game systems, it is likely that we'll be adding tags here for other new functionality.

Typeclass

The typeclass for the vast majority of NPCs will always be typeclasses.characters.NPC.