top of page
Dungeon Generators XML and Descriptions

   The dungeon generators are a mix of code and a mix of XML defined data.  On the code side, the dungeons are generated via various algorithms, or only data from the user. All dungeon map generation files have to be contained within the directory "Data/Environments/"

​

   To start, the XML file has to have the root child name of "EnvironmentBlueprint" and within that there has to be defined a "size" attribute, which defines the width and height of the map it is to generate. Then within that you can define one of several dungeon generator types.  The children of the "EnvironmentBlueprint node have to be "GenerationProcessData" nodes, and have to define the attribute "generator" which takes one of the dungeon generator names.

​

Example:

<?xml version='1.0' encoding='utf-8'?>

<EnvironmentBlueprint name="" size="64,32">

     <GenerationProcessData generator="DungeonMapGenerator" steps="0" surface="air"/>

</EnvironmentBlueprint>

​

Dungeon Generator types:

  • Cellular Automation Generator

    • XML Title: CellularAutomationGenerator

    • Variables it accepts:

      • "steps" - number of turns in which to run the generator's formula on the generated section of the map.

      • "iterations" - this is so as to define the number of times it should regenerate the base version of the map before actually performing the generator's formula.

      • "rangeMins" - the min x,y coords in which to run this generator on.

      • "rangeMaxs" - the max x,y coords in which to run this generator on.

      • "xRange" - the range across x (xMin, xMax) in which to run this generator on.

      • "yRange" - the range across y (yMin, yMax) in which to run this generator on.

      • "stonePercentage" - takes a value between 0 and 1; used when iterating on the map prior to running Cellular Automata in order to create the base settings in which to run with.

    • Description:

      • This generator runs the formula called Cellular Automata, which involves starting with a bunch of titles of either one type or the other. For our example, we will assume stone tiles and air tiles, where stone is the default tile, and air is the tile that we want to increase.  Each time the formula steps forward one full step, then all stone tiles with two or more air tiles around it would turn into air, while all air tiles with three or more air tiles around it would turn to stone.

      • This generator only uses air and stone tiles.

    • ​

  • Castle Generator

    • XML Title: CastleGenerator

    • Variables it accepts:

      • "rangeMins" - the min x,y coords in which to run this generator on.

      • "rangeMaxs" - the max x,y coords in which to run this generator on.

      • "xRange" - the range across x (xMin, xMax) in which to run this generator on.

      • "yRange" - the range across y (yMin, yMax) in which to run this generator on.

    • Description:

  • Cavern Generator

    • XML Title: CavernGenerator

    • Variables it accepts:

      • "iterations" - this is so as to define the number of times it should regenerate the base version of the map before actually performing the generator's formula.

      • "rangeMins" - the min x,y coords in which to run this generator on.

      • "rangeMaxs" - the max x,y coords in which to run this generator on.

      • "xRange" - the range across x (xMin, xMax) in which to run this generator on.

      • "yRange" - the range across y (yMin, yMax) in which to run this generator on.

      • "surface" - (acceptable variables: "stone", "air", "water", "lava") what type of tile it should fill the caves in with.

      • "quantity" - the number of caves to generate in a given iteration.

    • Description:

      • ​

  • Dungeon Map Generator

    • XML Title: DungeonMapGenerator

    • Variables it accepts:

      • "iterations" - this is so as to define the number of times it should regenerate the base version of the map before actually performing the generator's formula.

      • "rangeMins" - the min x,y coords in which to run this generator on.

      • "rangeMaxs" - the max x,y coords in which to run this generator on.

      • "xRange" - the range across x (xMin, xMax) in which to run this generator on.

      • "yRange" - the range across y (yMin, yMax) in which to run this generator on.

      • "surface" (acceptable variables: "stone", "air", "water", "lava") what type of tile it should fill the rooms, and corresponding tunnels in with.

      • "quantity" - the number of rooms to generate per iteration.

      • "makeDoors" - tells the dungeon generator to try and generate a door feature at the ends of it's tunnels.

    • Description:

      • First it generates the number of rooms defined,

  • From Data Generator

    • XML Title: FromDataGenerator

    • Variables it accepts:

      • "iterations" - this is so as to define the number of times it should regenerate the base version of the map before actually performing the generator's formula.

      • "rangeMins" - the min x,y coords in which to run this generator on.

      • "rangeMaxs" - the max x,y coords in which to run this generator on.

      • "xRange" - the range across x (xMin, xMax) in which to run this generator on.

      • "yRange" - the range across y (yMin, yMax) in which to run this generator on.

    • Acceptable Children:

      • "Tiles"

        • Variables it can use:

          • "tilePosition" - sets the range of tiles in which to set to the x,y coords assigned here.

          • "rangeMins" - the min x,y coords in which to run this generator on.

          • "rangeMaxs" - the max x,y coords in which to run this generator on.

          • "xRange" - the range across x (xMin, xMax) in which to run this generator on.

          • "yRange" - the range across y (yMin, yMax) in which to run this generator on.

          • "tileType" - sets the surface/tile type for this set of data (acceptable vars: "air", "stone", "water", "lava")

    • Description:

      • This takes user defined data and sets the tiles to that particular tile type, provided its in the correct position defined by the user, and also in the correct order as defined by the user.

​

Dungeon Generators XML and Description

CastleGenerator Header File

CastleGenerator CPP File

Item Generation XML and Descriptions

   Item Generation is also handled through XML.  Of the various systems, Item Generation and usage is probably the simplest.

​

To start, here is some example Item XML code:

​

<?xml version='1.0' encoding='utf-8'?>

<ItemBlueprints>

   <ItemBlueprint name='Bronze Sword' glyph='h' color='0.803,0.498,0.196' itemType='weapon' equipSlot='primaryHand damage='8~10'/>

</ItemBlueprints>

​

As you can see, the root name has to be "ItemBlueprints" and it's coresponding children have to be "ItemBlueprint" types.  The only variables necessary to define are on the ItemBlueprint itself.  All Item generation files must be contained with the directory "Data/Items/"

​

There are several attributes to pay attention to as far as items go:

  • "name"

    • Defines the name of this item.

  • "glyph"

    • Defines what letter should this be when it appears on the map.

  • "color"

    • Defines the color that the assigned glyph will be when it appears on the map.

  • "itemType"

    • Defines what type of item this is.

    • "weapon", "armor", "potion"

  • "equipSlot"

    • Defines what slot would this be equipped on.

    • "head", "chest", "legs", "primaryRing", "secondaryRing", "primaryHand", "secondaryHand", "none"

  • "damage"

    • Defines how much damage to hit the player with on the initial turn.

    • Set to a negative value to heal.

    • Counts as defense points if used on armor instead.

  • "damageOverTime"

    • Defines how much damage to apply to the person effected by the status.  Right not this and statusTurns are untested as to what it would do when put on an equipment item (most likely case that this wont matter on equipment items).

  • "statusTurns"

    • Defines the number of turns that damageOverTime will be applied. Right not this and damageOverTime are untested as to what it would do when put on an equipment item (most likely case that this wont matter on equipment items).

  • "customEquipMessage"

    • When the item is equipped, defines a special equip message for that particular item.

  • "grantFlight"

    • Takes a boolean value to define whether, when equipped, the item should grant flight to the user or not, making them immune to damage from lava.

​

   Equipment items are automatically equipped on pick up, and potions are drunk with 'Q'.

Item Generation XML and Descriptions
NPC XML and Definitions

    Now that the various Factions are defined, its time to get into the XML for NPCs.  The root node is "NPCBlueprints", and the child nodes are "NPCBlueprint".  The NPCBlueprints not only require a variety of attributes, but also need children of their own to function.

​

   First lets go over the attributes:

  • "name"

    • This defines the name of the unit type ("Dwarven_Soldier").

  • "defaultName"

    • This defines a normal name for entities of the unit type ("Crossbeard"); basically if no list of names is defined, it will use this name for every unit spawned of this unit type's.

  • "preferredTile"

    • Defines the tile it will be spawned on. (valid inputs: "air", "water", "stone", "lava")

  • "faction"

    • Defines a faction this unit is a part of. If the faction does not already exist, it creates that faction.

  • "maxHealth"

    • Takes an integer range of numbers in order to randomly generate the max health per unit.  The range must be separated by the char '~'.

  • "damage"

    • Takes an integer range of numbers in order to randomly generate the base amount of damage this unit will do, per unit. The range must be separated by the char '~'.

  • "moveSpeed"

    • Takes a float value to define how quickly the unit can move.

  • "lineOfSight"

    • Takes a float value to define how far out from itself the unit can see.

  • "race"

    • Unimplemented feature; don't bother with it.

  • "glyph"

    • Defines what char this unit shows up as. Same restrictions apply as before.

  • "color"

    • Defines what character this unit shows up as.

  • "accuracy"

    • Takes a percentage value between 0.00 and 1.00; determines how likely the entity is to actually land a hit.

​

   Now for the children of NPCBlueprint:

  • Names

    • Contains a variety of children that the names of those children contain the name the unit would take.

    • Ex:

                     <Names>

                            <Crossbeard/>

                     </Names>

  • Titles

    • Contains some titles that the entity will be given at random.  There were plans for this to modify stats, but this presently does not do that. At the same time, Titles can be longer than the Names, and have to follow a different set up than Names.

    • Ex:

                      <Titles>

                             <Title name='the Dwarven Soldier'/>

                      </Titles>

  • Inventory

    • Contains a list of items that the unit potentially could have on them when spawned.  Uses the names to find those off the presently defined item generators and add it to the NPC when spawned.

    • Ex:

                       <Inventory>

                              <Item name="Wooden Club"/>

                       </Inventory>

  • Behaviors

    • This is where we get into the good stuff, as Behaviors are used to define how the given NPC will act.  This takes a variety of children that are named expressly after the Behavior type. Each behavior has their own variables that they accept.

    • List of Behaviors:

      • Patrol

        • Picks a random number of points about the map and has the unit move towards

        • Attributes:

          • "radius" - from spawn point, how far out should patrol points be.

          • "numberOfPatrolPoints" - how many patrol points should be generated, takes a range of numbers, that have to be separated by char '~'

      • Wander

        • Moves the unit about randomly and occasionally has them rest.

        • Attributes:

          • "chanceToRest" - percentageChance to rest if this is run. (between 0 and 1) (use chanceToRest or chanceToWalk)

          • "chanceToWalk" - percentage chance to walk if this is run. (between 0 and 1)(use chanceToRest or chanceToWalk)

      • PickUpItem

        • If an item is in view, and this unit's interest in items is greater than it's other running behaviors, it will go to the item and pick it up.

        • Attributes:

          • "interestInItems" - if an item is in range, how high can my interest be based on it's distance to me.

          • "minInterestInItems" - if an item is in range, how low can my interest in it be.

          • "distanceOutToCare" - how far away an Item can be for this unit to care about whether they exist or not.

      • Chase

        • If an enemy unit is within range, will chase after that unit.

        • Attributes:

          • "maximumDuration" - How many turns this unit would chase an enemy for.

          • "maximumDistanceAwayToStart" - how far away an enemy can be for this behavior to activate.

      • MeleeAttack

        • If an enemy unit is within range, will have them attack that enemy

      • Flee

        • Has the unit run away from the most feared/hated enemy in the room.

        • Attributes:

          • "healthPercentLessThan" - How low does this unit's health need to be in order to run.

          • "multiplier" - Multiplies with the baseChanceToRun, increasing or decreasing it.

          • "percentChanceToScream" - How likely they are to scream while fleeing. (between 0 and 1)

          • "baseChanceToRun" - how likely the unit with this is to use the flee functionallity (value between 0 and 1)

          • "baseHatredToCountAsHostile" - How much does the faction hatred for entities in the other faction have to be for this to occur.

    • MovementProperties

      • Defines what sorts tiles the unit is slowed or blocked by.

      • valid inputs: ("blockedByWalls", "BlockedByAir", "BlockedByFire", "BlockedByWater", "SlowedByWalls", "SlowedByFire", "SlowedByWater", "HurtByFire", "Flying")

Faction XML and Definitions

    Factions are also defined from XML, whats nice about them though is technically you do not have to define them. Only thing is, if you don't define them, then they really won't like or dislike anyone.  As the game progresses, the more another member of a different faction attacks or kills members of a particular faction, that particular faction will start to hate the other faction more and more.  The player has their own faction which is just labeled "player".

​

    XML code for factions has to be placed in "Data/Factions/".  Here is an example:

<?xml version='1.0' encoding='utf-8'?>

<Factions>

    <Faction name='dwarf' likes='player,dwarf' hates='dark_elf'/>

</Factions>

​

   The root node is "Factions" while the actual definition of a faction is wrapped inside of a "Faction" node. All factions have to clarify the "name" property.  Outside of that, there are five different attributes that can be defined.

  •     "loves" - any factions named here this faction really likes.

  •     "likes" - any factions named here this faction generally likes

  •     "neutral" - any factions named here, this faction doesn't care about. (This is default for any unlisted factions; don't worry about this)

  •     "dislikes" - any factions listed here, this faction dislikes, and might would attack.

  •     "hates" - any factions listed here, this faction loathes entirely, and definetly will try to beat down.

​

    If a faction is listed in one of the attributes, but undefined elsewhere, then it will have a default faction data set created for it.  Same goes for when generating a monster of a faction that does not have a preset faction made for it.

Faction XML and Definitions
NPC XML and Definitions

Copyright © 2024 Alexander T. Baird

  • LinkedIn Social Icon
  • gmail
  • GitHub-Mark
bottom of page