Spawn Templates

Spawn Templates

Spawn templates are JSON files loaded from a datapack:

data/<namespace>/spawn_rules/.../<name>.json

The file path is only for organization; the dimension field inside the JSON is the authoritative key. A template from a datapack overrides the built-in template for the same dimension.

Schema

{
  "dimension": "minecraft:overworld",
  "method": "default",
  "parameters": {
    "allow_position_overwrite": true,
    "center_x": 0,
    "center_z": 0,
    "max_radius": 256,
    "ring_step": 64,
    "max_chunk_loads": 64
  },
  "fallback": "platform",
  "fallback_parameters": {
    "x": 0,
    "y": 64,
    "z": 0,
    "size": 3,
    "material": "minecraft:stone"
  }
}

Fields:

Field	Meaning
dimension	Dimension id; used as the rule key.
method	Spawn method id.
parameters	Method-specific parameters.
fallback	Method to try if the main method fails; may be omitted.
fallback_parameters	Parameters passed to the fallback method.

Numbers are parsed as integers when they have no decimal point/exponent, otherwise as doubles. Booleans and strings are also supported.

parameters.allow_position_overwrite is a reserved boolean (default false). When true, gotodim may replace the template position with the dimension's current global spawn: search methods use its center_x/center_z, while fixed/platform use its coordinates. All built-in vanilla templates set this to true; datapack templates must opt in.

Fallback chain

When a method returns a non-success result, the resolver tries fallback. Fallback rules can chain further, but the depth is limited by search.fallbackMaxDepth (default 3) and cyclic method ids are skipped.

A successful fallback is reported as status FALLBACK; the final position is still usable.

Built-in defaults

The three vanilla dimensions always have a built-in template, even with no datapacks:

• minecraft:overworld: default → platform
• minecraft:the_nether: portal_type → platform
• minecraft:the_end: fixed → platform

All three built-ins set allow_position_overwrite: true. Datapack templates override these entries by dimension and default to false unless they set the flag.

Examples

Overworld land search

{
  "dimension": "minecraft:overworld",
  "method": "default",
  "parameters": {
    "allow_position_overwrite": true,
    "center_x": 0,
    "center_z": 0,
    "max_radius": 256,
    "ring_step": 64,
    "max_surface_depth": 16,
    "max_chunk_loads": 64
  },
  "fallback": "platform",
  "fallback_parameters": {
    "x": 0, "y": 64, "z": 0,
    "size": 3,
    "material": "minecraft:stone"
  }
}

Nether portal site

{
  "dimension": "minecraft:the_nether",
  "method": "portal_type",
  "parameters": {
    "allow_position_overwrite": true,
    "center_x": 0,
    "center_z": 0,
    "min_y": 32,
    "max_y": 127,
    "search_radius": 128,
    "ring_step": 32,
    "portal_width": 2,
    "portal_height": 3,
    "avoid_lava": true,
    "build_platform": true,
    "platform_x": 0,
    "platform_y": 64,
    "platform_z": 0,
    "platform_size": 5,
    "platform_material": "minecraft:netherrack",
    "max_chunk_loads": 64
  },
  "fallback": "platform",
  "fallback_parameters": {
    "x": 0, "y": 64, "z": 0,
    "size": 5,
    "material": "minecraft:netherrack"
  }
}

portal_type only chooses a site; it does not build obsidian or light a portal.

End fixed point

{
  "dimension": "minecraft:the_end",
  "method": "fixed",
  "parameters": {
    "allow_position_overwrite": true,
    "x": 100,
    "y": 64,
    "z": 0,
    "angle": 90.0,
    "safe_check": true
  },
  "fallback": "platform",
  "fallback_parameters": {
    "x": 100, "y": 64, "z": 0,
    "size": 5,
    "material": "minecraft:end_stone"
  }
}

Cave / no-sky dimension

{
  "dimension": "your:no_sky_dimension",
  "method": "cave",
  "parameters": {
    "allow_position_overwrite": true,
    "center_x": 0,
    "center_z": 0,
    "min_y": 32,
    "max_y": 120,
    "search_radius": 128,
    "ring_step": 32,
    "min_air_height": 2,
    "roof_scan": 8,
    "avoid_lava": true,
    "max_chunk_loads": 64
  },
  "fallback": "platform",
  "fallback_parameters": {
    "x": 0, "y": 64, "z": 0,
    "size": 5,
    "material": "minecraft:netherrack"
  }
}

A copyable example is in the repository at docs/cave_template.json. Change its dimension and place it in your datapack.

Testing a rule

/betterspawn gotodim simulate --verbose
/betterspawn gotodim simulate --method cave --params {"min_y":32,"max_y":120}

--params merges into the template's current parameters for that run only.

With allow_position_overwrite: true, the probe starts from the dimension's current global spawn (Overworld: level.dat; other dimensions: WorldSpawnData). After /betterspawn worldspawn global, gotodim uses the new position immediately. Add position keys to --params to test a different position, for example {"center_x":0,"center_z":0} or {"x":0,"y":64,"z":0}.