OreSpawn 3 JSON Documentation

In OreSpawn 3 the JSON system has been expanded to include several new features and be extensible. There are, with "version 1" of this new system two special files introduced - _features.json and _replacements.json.

The default "_features.json" contains one entry but gives a good example of the format of this file. What this files does is allow anyone to specify a means of adding ores to the game - similar to how CoFHCore Worldgen has things such as "fractal" and "sheet", this allows for an extensible, compatible system of defining new types of generators.

Structured as an array of objects, each object defines a human-readable and understandable name for the feature and what the classname is of the generator. Said generator has to implement the IFeature interface (com.mcmoddev.orespawn.api.IFeature) for it to actually be useful - anything not implementing that interface will cause a crash.

The default _features.json (as generated by running OreSpawn 3 without any other mods loaded) is:

[
    {
      "name": "default",
      "class": "com.mcmoddev.orespawn.impl.features.DefaultFeatureGenerator"
    }
]

That defines the default generator - which is almost exactly what OreSpawn 1 used.

(what follows is subject to change as we move OreSpawn 3 towards a "release" state) By default _replacements.json is an empty JSON array ("[]"), as the default item for it is complex and handled in the code rather than via this file. Each entry in the array specifies a human-readable name, a resource-location type name for the block and, optionally, a serialized block-state describing the block. An example:

[
  {
    "name" : "andesite",
    "blockName" : "minecraft:stone",
    "blockState" : "variant=andesite"
  }
]

The example above shouldn't work - but shows how the bits would work together. The "name" is what you'd use to refer to this item in your JSON and the other bits specify the block being replaced by the ore.

The actual JSON for specifying a new set of ore-spawns is as follows:

{
  "version" : 1,
  "dimensions" : [
    {
      "dimension" : -1,
      "ores": [
        {
          "block": "minecraft:quartz_ore",
          "parameters": {
            "size": 15,
            "variation": 4,
            "frequency": 7.0,
            "minHeight": 0,
            "maxHeight": 128
          },
          "feature": "default",
          "replace_block": "default"
        }
      ]
    }
  ]
}

Explained: The "version" defines which version of the JSON this file is in - right now we are on "version 1" of the OreSpawn 3 format. The rest of the file is an array, under the "dimensions" name.

In that array is a set of entries, with an optional "dimension" tag (if it is excluded, it means "applies to all dimensions except the Nether and the End") - in the above example it is specified as "-1" - the Nether. This is followed by the "ores" array, which defines the ores to spawn in that dimension.

Each "ore" has a "block" and an optional serialized blockstate under "state" which defines which block, exactly, this entry is mean to spawn. It also has a "feature" - a human readable name that is defined in _features.json - and a "replace_block" - which is a human-readable name for the block this one will be spawned in place of. The default value for both is "default" - for "replace_block" this means "replace netherrack when in the nether, end stone when in the end and stone in any other dimension" and for "feature" this just points to whatever was defined with that name in _features.json.

A part of the system that is not shown above - and only showing rarely in any of the default files - is the "biomes" block. At the moment it has the following format (and this is its definition for Emeralds):

  "biomes": [
    "minecraft:extreme_hills",
    "minecraft:smaller_extreme_hills"
  ]

The "biomes" block/array is a list of resource-location-like identifiers that specify which, specific, biomes the ore can spawn in.

The last part of an ore-definition is the "parameters" object - this object is not interpreted in any manner by the code that reads the files, as it is passed in the "JsonObject" it is read as by the code directly to the feature generator specified. For the default generator, it has the following items and meanings:

          "parameters": {
            "size": 15,
            "variation": 4,
            "frequency": 7.0,
            "minHeight": 0,
            "maxHeight": 128
          },

Size is the maximum number of blocks in the vein. Variation is how much the node can grow from the selected starting point of the node. Frequency varies in meaning - when greater than one it is how many attempts are made to generate a node in a given chunk, when less than one it is a percentage chance for a node to be spawned in a chunk. The last two parameters define the Y range in which the ore can spawn - it cannot spawn below "minHeight" or above "maxHeight", even if a node were to spawn at minHeight, it would not spread below - and the same for maxHeight - a node spawned at maxHeight would not spread above that.