⚙ Swift Mazes - Config file

 Select entry:

Introduction

⚙ Swift Mazes is a framework to generate 3D dungeons from textual (UTF-8 or ASCII encoded) floorplans. It reads a config file, some prefabs, and then generates a fully working 3D dungeon map for The Dark Mod, dmaps it (via TDM), and packages it together as a playable .PK4 file - all automatic!

This manual describes the config file format and syntax.

The same format is used for defining strings, prefabs, options, and the map itself. Each config file consists of various sections and can include other files.

Config File Format

Sections in the config file have the format [SECTION] or [SECTION NAME]. The first is used for sections that appear only once, while the latter is used for sections that appear multiple times and define different blocks.

Most sections in a config file can define parameters (options) in the form of name=value. The format follows these rules:

It is possible to include other files with the #include filename.cfg directive. This way you can split up your config file into different sections, or even use default files with some common definitions.

Here are some examples:

[Config]
;This is a comment and ignored
name=MyName
; use string template number for I18N, instead of a hard-coded string
name = 20000
; Lists can have spaces or commas, or combinations
player_light = 0.1 0.1 0.1
ambient_light = 0.1, 0.1, 0.1

Numbers (int, float)

Variables of the type int are integer, float defines non-integer values. If unsigned, the value must be >= 0. Examples: random_seed = 12

Booleans

Boolean values are either true, false, 0, 1, on or off. Example: show_name = off

Strings

String values run until the end of the line, or, if they start with ", then until the last unquoted ". Example: name = "The Maze"

Colors

Variables of type color consist of three values for red,green and blue. All three go from 0.0 to 1.0, where 0 0 0 means black and 1 1 1 white. For ambient lights, values should be under 0.1. Example: ambient_light = 0.1 0.1 0.05

Vectors

Variables of the type vector3d consist of 3 values between 0.0 to 1.0, giving the direction in the X, Y and Z axis. Example: offset = 0 -2 8

Angles

Variables of the type angle consist of 3 values between 0 to 360, giving the rotation in the X, Y and Z axis. Example: angle = 0 0 90

Extends

Variables of the type vector3d consist of 6 values between 0.0 to 1.0, giving the distance in -X, -Y, -Z, X, Y and Z. Example: extends = -16 -16 -16 +16 +26 +32

Directions

In many cases, a direction can be added, either as part of a name, or in list of directions. The following directions are recognized:

Combinations can be done by combining the first letter, starting with always with north or south, or with west or east in case there is no north/south in the combination. A few examples:

Config File Structure

Each input file for Swift Mazes consists of several sections. The first section is usually the [Config] section. The following sections can be in any order you want, but usually are defined as below. The last part of the config file then consists of multiple [Location] sections:

[Config]
; global config here

[Prefabs]

[Charmap]

[Strings English]
[Strings German]
...

[Action 0]
[Action 1]
...

[Event 0]
[Event 1]
...

[Inventory]

[Loction 0]
; location config here

  [Event 0]
  [Event 1]

  [Links]
 
  [Connects]

  [Level 0]
  ; level map directly

  [Level 1]
  ; Optional:
  [Level Config]
  [Level Events]

  ; the "[Level Map]" line is optional
  [Level Map]
  ; Can also be replaced by [Blocklist]

[Location 1]
; like Location 0:
  ...

[Config] section

This section contains global settings for the generated map:

NameTypeDescriptionDefault value
ambient_lightcolorThe global color of the ambient light.0.02 0.02 0.04
authorstringYour name and copyright. Will appear in the generated darkmod.txt file.(c) Tels 2014
base_mapfileIf set, this map file will be used as a basis. If not set, an empty .map file will be generated.''
block_sizevector3dSize of one block in units.192 192 192
commentstringAn optional comment. Will appear in the generated darkmod.txt file.''
descriptionstringA short description of the map or mission. Will appear in the generated darkmod.txt file.A Swift Project
fogcolorThe color of the fog, used as fallback when a location does not have its own fog.0 0 0
fog_radiusunsigned intFallback radius of the fog. 0 means no fog, used as fallback when a location does not have its own fog.0
fog_strengthfloatStrength of the fog, between 0 and 1.0, 0 means no fog. Used as fallback when a location does not have its own fog.0.0
map_offsetvector3dThe generated map will be auto-centered around the origin (0,0,0) in DR, then this optional offset will be added.0 0 0
min_swift_versionunsigned floatThe generated map will require at least this version of the Swift Mazes assets to run.1
min_tdm_versionunsigned floatThe generated map will require at least this version of TDM to run.2.02
player_lightcolorThe default light around the player.0.1 0.1 0.2
player_light_radiusvector3dThe default radius of the light bound to the player.350 350 350
prefab_dirpathDirectory where the prefab files are stored.projects/default/prefabs/
random_seedunsigned intIf not set, choosen randomly. If set, the random sequence of the entire map will always be the same.Not set.
titlestringThe title of the map or mission. Will appear in the generated darkmod.txt file.Untitled

[Strings] section

The Strings section defines the mapping between string templates and the actual strings in this language. Your string templates should use numbers between 20000 and 79999. Everywhere you would normally place a string, like in Location names, in the Action section and so on, use the string template number instead.
Here is an example, defining a few strings and using them:

[Strings English]
; Format: ID="string content"
; If nec, escape " with \" like so: 80000="The \"Quote\"."
20000="You found the lost crown!"
20001="Deep Temple"

[Strings German]
; Format: ID="string content"
20000="Du hast die verlorene Krone gefunden!"
20001="Tempel der Tiefe"

[Location 1]
name=20001

There is a default strings.cfg file included with Swift Mazes, defining the strings used by the system. These use numbers from 80000 onwards.

[Prefab X] section

This section defined the various prefabs and their properties. The actual prefab files need to be generated in Dark Radiant first.

NameTypeDescriptionDefault value
auto_offsetvector3dAutomatically generated entities in this block need to use this offset to avoid being placed in solids.0 0 0
blocksdirectionsA list of diretions like south, up, down, se etc. where this prefab blocks the connection to. These directions will not be considered for visportaling, either.Empty.
connectsdirectionsThe opposite of blocks. If connects is defined, it will overide blocks.Empty.
extendsextendsSet the min and max extends of this prefab (relative to center) to adjust the size.Not set.
includesstringlistA list of prefab names to include at blocks where this prefab is added. Can appear multiple times.Empty.
inhibitsstringlistA list of prefab names to remove from the block where this prefab is added, because this prefab replaces these. Can appear multiple times.Empty.
offsetvector3dThe offset for this prefab to be applied when loading it.0 0 0
rotationangleRotate the contents of this prefab on the x, y and z axis.0 0 0
sizesizeThe size of the prefab in blocks as width (X), length (Y) and height (Z)1 1 1
virtualboolIf true, this prefab is empty itself, and only includes other prefabs.false
visportalsdirectionsA list of diretions like south, up, down, se etc. where this prefab already includes a visportal.Empty.

[Inventory] section

This section describes the inventory items for the player. The format of each line is Difficulty level = inventory item. The difficulty level can be one of easy, medium or hard, or a combination of them. all is an alias for easy, medium, hard.

You can use either the entity class name like atdm:ammo_broadhead or one of the following alias names:

AliasName
breath_potionatdm:playertools_breath_potion
broadheadatdm:ammo_broadhead
compassatdm:playertools_compass
firearrowatdm:ammo_firearrow
flashbombatdm:playertools_flashbomb
flashmineatdm:playertools_flashmine
gasarrowatdm:ammo_gasarrow
health_potionatdm:playertools_health_potion
holywateratdm:playertools_holywater
lanternatdm:playertools_lantern
lockpick_setatdm:playertools_lockpick_set
lockpick_snakeatdm:playertools_lockpick_snake
lockpick_triangleatdm:playertools_lockpick_triangle
mineatdm:playertools_mine
slow_matchatdm:playertools_slow_match
spyglassatdm:playertools_spyglass
waterarrowatdm:ammo_waterarrow

Here is an example:

[Inventory]
all=Spyglass
easy, medium=health_potion
; on easy, add another health potion
easy=health_potion
all=5 x atdm:ammo_broadhead
; 3 additional ones
medium=3 x broadhead
; 5 additional ones
easy=5 x broadhead

[Action X] sections

These sections defines the various actions that can be triggered by global or location-specific events. The events are later defined in the [Events] section. Here are some examples:

[Action 1]
; this action is triggered when the player is in a certain block (spot)
disabled=false
comment=A message telling the player to go to the portcullis
message=80500
; -1 => infinite (until disabled), 0 => disabled, > 0 : so many times
count=-1
sound=sounds/swift/message

[Action 2]
; This action is triggered when the player is in a certain block (spot)
comment=A message telling the player to pull the chain
message=80501
; -1 => infinite (until disabled), 0 => disabled, > 0 : so many times
count=-1
; When triggered, disables action 1 (so it does not appear again)
disables=1

[Action 3]
; This action is triggered when the player is in a certain block (spot)
comment=Disable messages if player progressed far enough
; only once
count=1
; When triggered, disables action 1 and 2 (so they do not appear again)
disables=1 2
NameTypeDescriptionDefault value
commentstringAn optional comment for this action''
countintHow often does the action occur when triggered. -1 => infinite (until disabled), 0 => disabled, > 0 => so many times.-1
disablesintlistSpecifies an event ID to disable. The other event's count will stay unmodified. Can appear multiple times.Empty.
enablesintlistSpecifies an event ID to enable. If the other event's count is 0, it will be set to 1, otherwise it will stay unmodified. Can appear multiple times.Empty.
messageintIf set to a number >= 20000 and < 90000, this message (string ID) will appear.0
particlestringIf set, play this particle effect.''
soundstringIf set, play this sound shader.''

[Event X] section

These sections specify global events that trigger actions.

NameTypeDescriptionDefault value
delayunsigned floatTime in seconds to delay the start of the action(s).0
disabledboolIf true, this event is disabled at map start. Some action needs to enable it first.false
on_endboolIf true, this event fires when the map ends (Mission acomplished)false
on_startboolIf true, this event fires when the map starts.false
startsintlistThe actions to start when this event is triggered.Empty.

Location events

If the [Events X] section appears inside a [Location] section, it defines events that are only valid inside this location. These events have slightly different options:

NameTypeDescriptionDefault value
delayunsigned floatTime in seconds to delay the start of the action(s).0
disabledboolIf true, this event is disabled at map start. Some action needs to enable it first.false
on_entryboolIf true, the event triggers when the player enters this location. -1 to disable.true
on_exitboolIf true, the event triggers when the player leaves this location. -1 to disable.false
startsintlistThe actions to start when this event is triggered.Empty.

[Location X] section

Each map consists of one or more locations, which are linked together. This section defines a new location, and contains various sub sections:

NameTypeDescriptionDefault value
ambient_lightcolorThe color of the ambient light in this location.0.02 0.02 0.04
ambient_light_dynamiccolorThe factor for the dynamic part of the ambient light.0.01 0.01 0.01
ambient_light_dynamic_capcolorThe cap for the dynamic part of the ambient light.0.01 0.01 0.01
ambient_musicstringName of the ambient music (sound shader) to play when the player is in this location.''
commentstringAn optional comment.''
descriptionstringAn optional description of this location.No description.
fogcolorThe color of the fog, use -1 -1 -1 to fallback to the global fog color.-1 -1 -1
fog_radiusintThe radius of the fog in this location. Use -1 to fallback to the global fog color.-1
fog_strengthfloatStrength of the fog, between 0 and 1.0. -1 to fallback to global fog strength.-1
ignoreboolIf set to true, this location definition is ignored.false
namestringThe name of the locationUnknown location
offsetvector3dOffset for this location in units.0 0 0
player_lightcolorThe color of the light around the player.0.1 0.1 0.2
player_light_radiusvector3dThe radius of the light bound to the player.350 350 350
prefabsstringDirectory where the prefab files are stored.''
random_seedunsigned intIf not set, choosen randomly. If set, the random sequence of this location will always be the same.Not set.
show_nameboolIf set to true, the name will be displayed on the HUD when entering the location.true

[Connects] section

The section defines the connection points between this location and other locations. If two locations are connected, both must have a matching [Connects] section.

[Link] section

This section describes links between entities

Here is an example:

[Links]
chain ↧ opens gate ↧ once
chain ↧ lights torch ▾ once delayed by 3.5 seconds

[Level X] section

Each [Level] section describes one floor level of the current location. The levels are stacked on top of each other. Typically the first floor is 1, but the ordering and numbering is arbitrary. If you use prefabs spanning more than one floor, not all levels have to be used.

Each [Level] section consists of:

The [Level Config] section can contain these settings:

NameTypeDescriptionDefault value
aliasintIf set to a number, this level will be at exactly the same position than the other level. Can be used to create two maps for the same level to have more choices in putting things into blocks.Not set.
commentstringOptional comment for this level.''
descriptionstringAn optional description for this level.No description.
ignorestringA list of symbols to ignore when parsing this level.''
offsetvector3dThe offset for this level in units, relatively to its original position.0 0 0

[Blocklist] section

The [Blocklist] section section contains a list of prefabs with their block positions. It replaces the [Level Map]m section. If the [Blocklist] section appears inside a [Level X] section, then the z-coordinate for each block is optional, it will be set to X from the level.
Each block can contain an optional names, so events can refer to it. The name comes before the coordinates with a : at the end. Here is the full format description:

Name:x,y[,z]=Prefab list

And here is an example. It is already a fully working map, consisting of only two blocks with a player start (facing east), a lit wall torch and the map exit:

[Level 0]

[Blocklist]
Start:0,0=empty,wall_south,wall_north,wall_west,pstart_east
1,0=empty,wall_south,wall_north,wall_east,exit,wtorch_north

The example above is equivalent to the following example:

[Level 0]
···▾··
·┌──┐·
·│SX│·
·└──┘·
······

Special Prefabs

To make common tasks easier, the ⚙ Swift Mazes generator recognizes some special prefab names. These names result in automatically inserted entities or actions, and need no .pfb file.

There are three difficulty levels:

The special prefabs can include the difficulty infront of there name, as any combination of e, m or h. all is an alias for emh. If not specified, all is assumed. Some examples:

air

The air prefab is ignored. It is mainly there for places where a prefab must be used, but no content should be added.

pstart_DIRECTION

pstart_DIRECTION results in a player start position with the specified direction. Examples: pstart_north or pstart_sw. If multiple player start positions are present, one is choosen at random everytime the map is started.

exit

Adds an exit point, where the map ends (and the next map is loaded, if there is a next map). If there are multiple points, the player can use any of them.

secret

Adds a secret room. When the player enters the block where the secret is located, the secret room count is increased. When at least one secret room is present in the map, an objective to find all of them is automatically generated and updated.

event_x

When the player enters the block where this prefab is present, the event x is triggered.

More info

The following manual sections contain more information: