Encounter Configuration

The encounter configuration file is a JSON text file that ties all of the pieces together and sets the rules on how they will operate. The main object in this file is the encounters array:

{"encounters":[]}

This array contains the various encounters and their definitions.

Encounter

A single encounter contains the structure (if any), what biomes is the encounter allowed to spawn, the probability of checks, what treasure to use to fill the structure, what mobs to include, what resource collection rules to use, what expansions are available, and how expansions take place. The format of an encounter JSON object is:

{
    "name":         "String",
    "structure":    "String",
    "enabled":      "Boolean",
    "probability":  "Double",
    "validBiomes":  ["String"...],
    "invalidBiomes":["String"...],
    "validWorlds":  ["String"...],
    "invalidWorlds":["String"...],
    "treasures":    ["String"...],
    "mobs":         ["String"...],
    "expansions":   [{Expansion Rule}...],
    "collections":  [{Collection Rule}...]
}

name:
^v0.1 REQUIRED
The name field is a string which uniquely identifies the encounter. Whenever an encounter is referenced, this name is used.

    "name": "castle3"

structure:
^v0.1 OPTIONAL (default: null)
The structure field is a string which must exactly match a name identified in the structure configuration file. This defines what schematic file is associated with the encounter. If no structure is associated (ex: a mob only encounter) mobs will attempted to be placed in any available space within the chunk. It is advisable to keep the probability low for encounters with no structure, as all terrain checks will succeed.

    "structure": "Castle3"

enabled:
^v0.1 OPTIONAL (default: true)
The enabled field is a boolean value (true | false) that determines if this encounter should be included in checks. When set to false, any new chunk generation will not check the probability to place this encounter, any expansion definitions referencing this encounter will also not perform checks. This is used to keep the definition of a pre-existing saved encounter, but to no longer generate new encounters from this rule.

    "enabled": true

probability:
^v0.1 OPTIONAL (default: 0)
The probability is a decimal number between 0 and 1, where 0 (or less) will never be checked from new chunk generation, and 1 (or above) will always be checked from new chunk generation. It is important to remember, this number only determines the probability that a new chunk will be checked to see if the structure (if there is one) will fit on a block within this chunk. The larger the structure, the more difficult to find suitable terrain to fit the structure in normal (non-flat) world generation. It is this number that allows the control over how common the encounter is.

    "probability": 0.05

validBiomes:
^v0.1 OPTIONAL (default: null)
The valid biomes array contains the names of the biomes where the encounter is allowed to be generated. If this field is not present, or set to null, all biomes (except those identified in the invalidBiome directive) are allowed. This is used for new chunks, as well as expansion. An example of this directive is:

    "validBiomes": ["SWAMPLAND","FOREST"]

List of Biomes

invalidBiomes:
^v0.1 OPTIONAL (default: null)
The invalid biomes, like the valid biomes, is an array of biome names. This list defines biomes in which the encounter is not allowed to exist. If the field is not present, or set to null, no biome is considered invalid. This means only biomes from the validBiomes list will be used. If both the validBiomes, and invalidBiomes fields are null, the encounter may be placed in any biome. It is important to note that an encounter may extend somewhat from a valid biome into an invalid biome depending on the size of the structure. The list of available biomes is the same as the validBiome directive. An example of the invalidBiome directive is:

    "invalidBiomes": ["OCEAN","RIVER"]

validWorlds:
^v0.4.2 OPTIONAL (default: null)
The valid worlds array contains the names of the worlds where the encounter is allowed to be generated. If this field is not present, or set to null, all worlds (except those identified in the invalidWorlds directive) are allowed. This is used for new chunks, as well as expansion. An example of this directive is:

    "validWorlds": ["world","world_end"]

invalidWorlds:
^v0.4.2 OPTIONAL (default: null)
The invalid worlds, like the valid worlds, is an array of world names. This list defines worlds in which the encounter is not allowed to exist. If the field is not present, or set to null, no world is considered invalid. This means only worlds from the validWorlds list will be used. If both the validWorlds, and invalidWorlds fields are null, the encounter may be placed in any world. An example of the invalidWorlds directive is:

    "invalidWorlds": ["world_nether","world_end"]

treasures:
^v0.1 OPTIONAL (default: null)
The treasures field is an array of treasure configuration names which will be used to fill chests within the structure. If no structure is defined, treasures will not be placed anywhere. If a structure is defined, but contains no chests, no treasure will be placed. The names in this list must exactly match the name of a treasure configuration. An example of the treasure directive is:

    "treasures": ["GeordianKingCoins","GeordianCoins"]

The system will run through the defined treasure configuration for every chest found in the structure. It is important to remember that double chests are considered two chests, and the configurations will be run on each side of the double chest. If the treasure array is empty or null, no treasures will be checked for the encounter.

mobs:
^v0.1 OPTIONAL (default: null)
The mobs field is an array of mob configuration names which will be used to place creatures within the encounter. The names in this list must exactly match the defined name in the mobs configuration. The system will go through the entire structure and find any spaces which have a solid block with two air blocks above it to find suitable spawning locations. Then for each creature generated through the mob configuration will pick a random space from that list to place the creature. For encounters with no structure, the entire chunk is used to determine suitable spawning locations. An example of the mobs directive is:

    "mobs": ["GeordianPigs","GeordianWarrior"]

Expansions

^v0.1 OPTIONAL (default: null)
The expansion directive defines how the encounter grows over time. This is an array of configurations that will be checked once per minute. This expansion, when created, will be a child of the main encounter which is referenced as the parent. If the expansion expands, the base encounter is referenced as root (this is used in collection and requirement logic). The format of an expansion configuration is as follows:

    {
        "encounter":    "String",
        "probability"   "Double",
        "duration":     "Integer",
        "max":          "Integer",
        "maxDistance":  "Integer",
        "minDistance":  "Integer",
        "pattern":      "Integer",
        "vault":        "Boolean",
        "requirements": {Requirement Configuration},
        "proximities":  [{Proximity Configuration}]
    }

encounter:
^v0.1 REQUIRED
The encounter field of an expansion is the string name of a defined encounter. It must exactly match the name of an encounter configuration. This tells the system what encounter rules are used for this expansion: what structure, mobs, treasures, etc.. An example of the encounter field is:

    "encounter": "tower3"

probability:
^v0.1 OPTIONAL (default: 0)
The probability field is a decimal number between 0 and 1 where 0 (or less) never occurs, and 1 (or more) always occurs. This directive, in combination with requirements and duration is used to help control how often the encounter will expand. An example of the probability field is:

    "probability": 0.25

duration:
^v0.1 OPTIONAL (default: 2⁶³-1)
The duration is an integer between 1 and 2⁶³-1 (a very large number). It represents the number of minutes between checks against the probability. Any number less than 1 will be considered every minute. This directive, in combination with requirements and probability is used to help control how often the encounter will expand. An example of the duration field is:

    "duration": 60

max:
^v0.1 OPTIONAL (default: 0)
The max field is an integer between 0 and 2⁶³-1 which defines the maximum number of times the parent encounter can expand using this rule. If the max is 0 (or less) this expansion will never occur. It is important to keep in mind an encounter may not be able to reach the maximum number of expansions for various reasons: lack of suitable space, lack of resources, etc.. An example of the max field is:

    "max": 6

maxDistance:
^v0.4 OPTIONAL (default: 1)
The maxDistance field is an integer between 1 and 2⁶³-1 which defines the maximum distance in chunks the expansion may be placed from the parent encounter. This is a radius from the chunk containing the center of the encounter. It is important not to set this too high, as it could easily end up beyond the bounds of the world. When the requirements and probability are met, depending on the pattern used, the system will begin checking chunks within this radius and the minDistance for suitable locations to place the child encounter. An example of the maxDistance field is:

    "maxDistance": 6

Note: This along with minDistance replaced the distance directive of v0.1 - v0.3.x and breaks backward compatability.

minDistance:
^v0.4 OPTIONAL (default: 1)
The minDistance field is an integer between 1 and 2⁶³-1 which defines the minimum distance in chunks the expansion may be placed from the parent encounter. This is a radius from the chunk containing the center of the encounter. It is important not to set this above the maxDistance as doing so will not allow the expansion to find any suitable locations. When the requirements and probability are met, depending on the pattern used, the system will begin checking chunks within this radius and the maxDistance radius for suitable locations to place the child encounter. An example of the minDistance field is:

    "minDistance": 4

Note: This along with maxDistance replaced the distance directive of v0.1 - v0.3.x and breaks backward compatability.

pattern:
^v0.4 OPTIONAL (default: -1)
The pattern field is an integer of -1 or 1. It is used to determine in which direction chunks are checked for suitable locations. A negative number starts with a radius of maxDistance and gradually moves toward minDistance in a spiral until a suitable location is found. A positive number starts with a radius of minDistance and gradually moves toward maxDistance in a spiral until a suitable location is found. For expansions that are a direct descendant of a root encounter, the initial angle with which to start checking is random. For expansions that have come from another expansion (not direct descendant of a root encounter), the initial angle which which to start is determined by the angle between the expansion's parent encounter and the root encounter. This logic exists so that recursive expansions are more likely to spiral out rather than collapse toward the root encounter. An example of the pattern field is:

    "pattern": 1

vault:
^v0.4.1 OPTIONAL (default: false)
The vault directive is a boolean value (true | false) which tells the system if this expansion should be considered a vault for the parent encounter. A vault is a location where collected resources are deposited and from where resources are withdrawn when spending resources for expansions. A vault can be any encounter, and should contain enough chests to store resources for expansion. Each encounter considers itself as a vault and will use those chests to store resources as well as any vault expansions that have been generated. A special rule is in place for vaults in that additional vault expansions will not be checked for placement until all vault space is full. An example of the vault directive is:

    "vault": true

Requirements

^v0.4.1 OPTIONAL (default: null)
The requirements configuration is a definition of what is necessary for the parent encounter to spawn this expansion. There are currently only to main options for requirements: parent and root. These options determine where the requirements should be checked. The parent option checks the requirements against this encounter definition, where as the root option checks against the parent's root encounter. It is important to note that these may be one in the same. For example, an encounter placed from new chunk generation is considered a root, any expansions that spawn from that encounter have the same root and parent. In the event that both a parent and root requirement configuration are present, both sets of requirements must be met. If the requirements directive is omitted or null, no requirements are necessary. The format for the requirements configuration is as follows:

    "requirements": {
        "parent": {
            "resources": {
                "Material": "Integer",
                ...
            }
        },
        "root": {
            "resources": {
                "Material": "Integer",
                ...
            }
        }
    }

parent:
^v0.4.1 OPTIONAL (default: null)
The parent configuration defines what requirements are necessary from this expansion's direct parent (The current encounter). If the parent directive is omitted or null, no requirements are necessary from the parent encounter.

root:
^v0.4.1 OPTIONAL (default: null)
The root configuration defines what requirements are necessary from this expansion's parent's root encounter (The encounter that was originally spawned from new chunk generation). If the root directive is omitted or null, no requirements are necessary from the root encounter.

resources:
^v0.4.1 OPTIONAL (default: null)
The resources directive uses the same format for both the parent and root directives. It is a key value pair using the Material name as the key, and a number between 0 and 2³¹-1 which represents how many of which material must be spent to create this expansion. It is important to keep in mind what resources are collected using the collection configuration or what may be generated through the treasures. Collected resources are converted to drops. For example: collected stone is stored as cobblestone, and collected iron ore is stored as iron ore. The expansion will not be created until the parent / root encounter's vaults contain the respective required resources. When the resource requirement is met, they will be withdrawn from the appropriate vaults. An example of a resource requirement configuration is:

    "requirements":	{
      "parent": {
        "resources": {
          "COAL":	  20,
          "IRON_ORE": 5,
          "LOG":	  25
        }
      },
      "root": {
        "resources": {
          "GOLD_ORE": 2,
        }
      }
    }

In this example, the parent encounter must provide 20 pieces of coal, 5 iron ore blocks, and 25 logs (of any type) and the root encounter must provide 2 blocks of gold ore before the expansion can be created. It is important to remember, the collection rules will only collect blocks and items dropped from blocks (such as coal from coal ore). Any non-blocks, or items that are not dropped from blocks defined as resource requirements must come from treasure generation which is only run when the structure is initially placed.

List of Materials

Proximities

^v0.4 OPTIONAL (default: null)
The proximities directive is an array of rules which define how close an expanding encounter is allowed to be to another encounter. If the proximities directive is omitted or null, the system will not hinder the expansion from being near another encounter. The format for a proximity configuration is as follows:

{
    "encounter":   "String",
    "minDistance": "Integer"
}

encounter:
^v0.4 REQUIRED
The encounter field is a string name of defined encounter. This string must exactly match the name field of an encounter configuration.

minDistance:
^v0.4 OPTIONAL (default: 1)
The distance field is an integer from 1 to 2³¹-1 which represents the distance in chunks the expanding encounter is allowed to be from the other encounter. It is important to note, the encounter defined in the proximity configuration must have already been placed in the world in order to be recognized by this rule. Any encounter (root, child, parent, other) using the defined encounter must be avoided by at least this distance in chunks.

An example of a proximities array is as follows:

    "proximities": [
        {
            "encounter":    "tower3",
            "minDistance":  10
        },
        {
            "encounter":    "castle3",
            "minDistance":  20
        }
    ]

In this example, the expansion must be at least 10 chunks away from any other tower3 encounter and at least 20 chunks away from any castle3 encounter. Keep in mind, this in combination with the minDistance and maxDistance could potentially cause no suitable locations for an expansion.

Collections

^v0.4.1 OPTIONAL (default: null)
The collections directive is an array of rules to be used for collecting resources. If the collection directive is omitted or null, the encounter will not attempt to collect resources and any expansions which require resources from this encounter must get them from treasure generation only. When each rule is run, a total number of random non-air blocks are chosen in a radius of distance between minHeight and maxHeight. If that block contains a defined resource, 20 of the block's nearest neighbors are checked. If they are of a valid resource, they will be collected, deposited in the encounter's vaults, and the blocks turned to air. If the encounter's vaults are full, the resources are lost. The format for a collection rule is as follows:

{
    "distance":     "Integer",
    "total":        "Integer",
    "duration":     "Integer",
    "destination":  "String",
    "minHeight":    "Integer",
    "maxHeight":    "Integer",
    "resources":    ["String"...]
}

distance:
^v0.4.1 OPTIONAL (default: 0)
The distance field is an integer from 0 to 2³¹-1 which represents the maximum distance in chunks the encounter is allowed to check for the defined resources.

    "distance": 20

total:
^v0.4.1 OPTIONAL (default: 0)
The total field is an integer from 0 to 2³¹-1 which represents the maximum number of random non-air blocks will check each time. It is important not to set this too high, as it could quickly consume all the resources in a large area.

    "total": 20

duration:
^v0.4.1 OPTIONAL (default: 60)
The duration field is an integer from 0 to 2³¹-1 which represents the number of minutes between running the resource collection rule.

    "duration": 20

destination:
^v0.4.1 OPTIONAL (default: "self")
The destination field is a string of either "self", "parent", or "root". This determines where the collected resources will be deposited. When set to "self", the resources will be deposited into this encounter's vaults. When set to "parent", the resources will be deposited into this encounter's parent's vaults. If this encounter is a root encounter, it is considered its own parent. When set to "root", the resources will be deposited into this encounter's root encounter's vaults. If this encounter is a root encounter, it is considered its own root.

    "destination": "self"

maxHeight:
^v0.4.1 OPTIONAL (default: 256)
The maxHeight field is an integer from 0 to 256 which represents the maximum height to be randomly chosen when the collection rule is run. It is important to consider what height levels the targeted resources may generate, as it may result in never collecting the targeted resources. If the maxHeight field is omitted or null, the maximum world height for the world in which the encounter is located is used.

    "maxHeight": 72

minHeight:
^v0.4.1 OPTIONAL (default: 0)
The minHeight field is an integer from 0 to 256 which represents the minimum height to be randomly chosen when the collection rule is run. It is important to consider what height levels the targeted resources may generate, as it may result in never collecting the targeted resources. It is also important that this number be lower than the maxHeight directive. Otherwise, no blocks will be checked.

    "minHeight": 40

resources:
^v0.4.1 OPTIONAL (default: null)
The resources directive is an array of material names this rule is targeting. Only if the checked block matches a material in this list will it be collected. It is important to keep in mind the types of blocks that may be world generated vs crafted. The collection will grab any block it finds which matches this rule, including bedrock, and blocks belonging to player structures. This will not take blocks which belong to another encounter.

    "resources": ["COAL_ORE","IRON_ORE"]

An example of a set of collection rules is:

    "collections": [
        {
            "distance":     8,
            "total":        100,
            "duration":     10,
            "destination":  "root",
            "resources":    [
                "COAL_ORE",
                "IRON_ORE",
                "GOLD_ORE",
                "EMERALD_ORE",
                "REDSTONE_ORE",
                "DIAMOND_ORE"
            ]
        },
        {
            "distance":     20,
            "total":        500,
            "duration":     5,
            "maxHeight":    72,
            "minHeight":    60,
            "destination":  "self",
            "resources":    [
                "LOG"
            ]
        }
    ]

In this example, every 10 minutes the encounter will choose 100 non-air blocks within a radius of 8 chunks at any height. If any of those blocks are an ore, it will check the 20 nearest blocks to each of them and collect all the drops. They will be deposited in the root encounter's vaults. Every 5 minutes, the encounter will choose 500 non-air blocks within a radius of 20 chunks between 60 and 72 high. If any of those blocks are logs, it will check the nearest 20 blocks to each of them and collect the drops. Those drops will be deposited in this encounter's vaults.