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 CoFHWorld 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 features_default.json (as generated by running OreSpawn 3 without any other mods loaded) is:

[
  {
    "name": "default",
    "class": "com.mcmoddev.orespawn.impl.features.DefaultFeatureGenerator"
  },
  {
    "name": "vein",
    "class": "com.mcmoddev.orespawn.impl.features.VeinGenerator"
  },
  {
    "name": "normal-cloud",
    "class": "com.mcmoddev.orespawn.impl.features.NormalCloudGenerator"
  },
  {
    "name": "precision",
    "class": "com.mcmoddev.orespawn.impl.features.PrecisionGenerator"
  },
  {
    "name": "clusters",
    "class": "com.mcmoddev.orespawn.impl.features.ClusterGenerator"
  }
]

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.2",
  "dimensions" : [
    {
      "dimension" : -1,
      "ores": [
        {
          "blocks": [ { "name":"minecraft:quartz_ore", "chance":100 } ],
          "parameters": {
            "size": 15,
            "variation": 4,
            "frequency": 7.0,
            "minHeight": 0,
            "maxHeight": 128
          },
          "feature": "default",
          "replace_block": "default",
          "biomes": []
        }
      ]
    }
  ]
}

Explained: The "version" defines which version of the JSON this file is in - right now we are on "version 1.2" 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" or "blocks" entry - with "block" being ignored if "blocks" is found. The new "blocks" syntax is used to allow for multiple ores to be part of the same node/vein/etc... and also supports using OreDictionary entries by using "ore" in the spot where the mod-id would normally go.

Each entry in the "blocks" array is an object that requires at least a "name" entry, although "state", "meta" and "chance" are also allowed. The "state" and "meta" pieces work like the classic "state" and "blockMeta" options in specifying a specific variant of the blocks that happen to share the same name. On the other hand, the "chance" element is a number from 1 to 100 that specifies a percentile chance that this will be the specific ore that spawns in any given spot of a generated lode.

Then there is the "feature" entry that defines how the nodes are going to be placed and generated. Currently there is "default", which acts similar to the existing Minecraft spawn logic; "vein", which generates a randomly wandering vein; "normal-cloud", which generates a "cloud" of single ores around a center point using a normal-distribution function; and "cluster", which uses the same normal distribution function as "normal-cloud" but spawns small lodes using lode generating logic that is the same as used by "default".

Next is the "replace_block" entry - this is a simple one that should generally be left as "default", but is a reference saying which block - or blocks - the feature generator should be replacing when creating this, specific, spawn.

And then there is the "biomes" entry - this gets very complex very easy, but specifies the biomes that the spawn should either generate in or not generate in - or even both. As this, alongside the "parameters" entry is one of the more complex bits - to the point that it deserves a document of its own - I'll try to keep it brief. In short this is an array of mixed items. Used directly, it contains the resource-location strings or biome dictionary names that define a whitelist of allowed biomes. When the entry is an object, however, it has the "includes" and "excludes" keywords that can be used to create complex selection logic denoting precisely the set of allowed biomes.

Example of a simple Biome entry - this one replicates, to an extent, vanilla Emerald restrictions:

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

A more complex example might be:

  "biomes": [
     { "includes": ["FOREST", "minecraft:extreme_hills"],
       "excludes": ["minecraft:roofed_forest"] }
   ]

The second example shows both the whitelist and blacklist capabilities, as well as the ability to specify by biome dictionary type.

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.

Other generators have different parameters. In the future there will be some more pages describing those generators and what their parameters mean.