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. With the latest format - tagged in the file as "2.0" - all system configuration or shared data is moved to the "sysconf" folder and _features.json and _replacements.json are now "sysconf/features-default.json" and "sysconf/replacements-default.json", which are joined by "sysconf/known-configs.json" (which tracks what mods have had their default configs extracted, so that your hard work isn't overwritten) and "sysconf/presets.json" (not always present, but allows for defining preset variables shared among all your config files).

The "features-default" file defines the "feature generators" provided by MMD OreSpawn (3.2) itself which should always be available to the end user - if you have a compatible feature generator (ie: one that implements "com.mcmoddev.orespawn.api.IFeature" and optionally extends "com.mcmoddev.orespawn.api.FeatureBase") you can provide a "feature" json of your own that tells MMD OreSpawn the preferred name of the feature generator and its fully qualified class name so it can be instantiated and utilized. The format of a "features" file is covered on the "features format" page.

For the "replacements-default.json" it is, nominally, empty - the default action is for any "Stone" in overworld dimensions, "Netherrack" in the Nether and "Endstone" in the End. You can, of course, provide a "replacements" file of your own, but this feature is, at this time, incomplete and the file format has not been documented because it is expected to change as this part of OreSpawn matures.

Lastly, the "presets" file has a somewhat open format, only requiring that it be a JSON Object. Each of the names of objects in it actually becomes part of a final variable name, denoted in use as the json-path-like format $.... - in this way you can define large chunks of repeated data to make writing your custom configurations easier. See the "Presets File" page for more details.

Outside of the "system configuration" directory is where the actual files defining how OreSpawn should spawn things are stored. These are a somewhat complex format, containing a "version" key, a "spawns" key and, optionally, a "presets" key. The "version" key, for the format described in this document, is "2.0" and the optional "presets" key should be an object formatted like the "presets" file - the definitions given in the object in a given config file, apply only to that file. Lastly is the "spawns" key, which is an object where each key represents the name of a spawn and the attached object to that key describes the spawn itself.

The bare minimum required for an OreSpawn 3 config file is, then, as follows:

{
    "version": "2.0",
    "spawns": {
        "<<<NAME>>>": {
            "retrogen": false,
            "enabled": true,
            "feature": "default",
            "replaces": "default",
            "dimensions": [],
            "biomes": { "excludes": [] },
            "parameters": {
		"size": 8,
                "variation": 4,
                "frequency": 5,
                "minHeight": 0,
                "maxHeight": 128
            },
	    "blocks": [ { "name": "<<<block 'registry name' here>>>", "chance": 100 } ]
        }
    }
}

In that example the "default" feature generator is being used, there are no biome restrictions, the spawn will occur in all dimensions that are not "The Nether" or "The End" and the spawn is not registered for retrogeneration. Fully described:

• retrogen - a boolean value defining whether or not to attempt to apply retrogeneration for this entry
• enabled - a boolean value defining whether this spawn entry is to even be attempted or not
• feature - string value containing the feature name as defined in any of the "features" files in the sysconf directory
• replaces - string value containing the replacement name as defined in any of the "replacements" files in the sysconf directory
• dimensions - at this time an array - empty meaning "all dimensions except the Nether and the End" or of specific identifiers for dimensions where this spawn will be active. Expect this to change as it is planned to become a full whitelist/blacklist system like the biomes
• biomes - json object containing one or two keys - "includes" and "excludes", with "includes" defining an array of specifically allowed biomes and "excludes" defining an array of specifically excluded dimensions. Providing an empty array for "excludes" is an "empty blacklist" meaning that all biomes are allowed. Biomes can be specified by their registry-name or by using a BiomeDictionary ID.
• parameters - parameters passed to the specific feature generator being utilized - each feature generator defines their own defaults and you only have to specify the values that you are changing away from the default, though best practice is to specify them all to cover for the defaults possibly changing between versions.
• blocks - an array of "Block Definitions" defining the blocks that this spawn should contain. Note that any block that is specified but not available in-game will be ignored.

It is not an error to specify a spawn entry for a block that is not available in-game. The system should ignore those entries entirely - treat them as if they are not enabled - but nobody is perfect and a bug might find its way into the code, causing those entries to generate what we call "zombie holes" in the world. If you come across small chunks of missing blocks that are shaped right for a spawn, please be sure to let us know that its happening and we'll see about fixing this issue.

A working example of the format that places blocks from different mods is available.