Description

World Primer can automatically run a set of commands when certain "events" happen, such as when a new world is first created, when a world is loaded, when a dimension is loaded, when a player joins the game, quits the game, dies or respawns. There are also scheduled/periodic commands.

Configuration

All of the configs can also be configured via the in-game config menu.

Read the comments in the configuration file. It has all the possible command substitutions listed, as well as lots of other information. Many of the substitutions and command prefixes have changed between mod versions, and later mod versions have more config/event types and string substitutions. The config comments are the easiest way to see the correct information for that particular mod version.

Note: None of the commands in the configuration file should have the slash prefix! The slash is only required in commands sent via the chat or the server console, to know that the message is not a chat message but a command. One notable exception of course would be World Edit commands, as they normally use the double slash via chat, so they should have a single slash in the configuration file.

Commands configuration

The commands to run at various events are set in the following config options.

Note: Older mod versions don't have all of these yet.

• dimensionLoadingCommands - commands to run each time a dimension gets loaded
• earlyWorldCreationCommands - Commands to run on initial world creation, before the spawn chunks have been generated or loaded. If dimension load tracking is enabled, then this happens even before any dimensions have been loaded/initialized yet.
• earlyWorldLoadingCommands - Commands to run every time the world gets loaded (i.e. when the server is starting). These are run when the server is starting, before any worlds have been loaded.
• playerChangedDimensionEnterCommands - Commands to run when (= after) a player entered into another dimension. Note that these will NOT run when a player joins the game or respawns after dying.
• playerChangedDimensionLeaveCommands - Commands to run when a player leaves a dimension while changing dimensions. Note: These commands will run after the player is already in the new dimension! Note: These will not run when a player leaves the game/server.
• playerDeathCommands - Commands to run when a player dies
• playerJoinCommands - Commands to run when a player joins (connects to) the server
• playerQuitCommands - Commands to run when a player disconnects from the server
• playerRespawnCommands - Commands to run when a player respawns after dying
• postWorldCreationCommands - Commands to run on initial world creation, after the spawn chunks have been generated and loaded.
• postWorldLoadingCommands - Commands to run every time the world gets loaded (i.e. when the server is starting). These are run when the server has started and the overworld spawn chunks have been loaded.
• timedCommands - Commands to run based on the world tick/time.
  • Must be in the format: worldprimer-timed-command <time> <dimension> <command>, where <time> is the total world time in ticks when the command should run.
  • The time can be prefixed with a % to make it run periodically, with that interval (basically a modulo).
  • With the periodic time, you can also use offsets, like so:

    worldprimer-timed-command %1200-80 0 say Something happens in 4 seconds!
    worldprimer-timed-command %1200 0 say Something happens now!
    worldprimer-timed-command %1200+80 0 Say something happened 4 seconds ago!
    

There are also separate config options to enable or disable all of these in the Toggles category. Those options allow you to disable the commands without having to remove them or comment them out if you want to temporarily disable them.

Other configs

• enableDebugLogging - Prints log messages from the various events, and also prints any commands that are attempted to be executed, so that it's easy to track what happens and when
• enableDimensionLoadTracking / enableDataTracking - Enables tracking and saving the number of times dimensions have loaded, how many times the server has started, how many times players have joined, died etc. This is needed for all the count based prefixes to work.

It's highly encouraged to use the enableDebugLogging logging option while testing things!

Command prefixes

There are a few different command prefixes/filters for running commands only in specific situation, like in specific dimensions, or only at specific times etc.

worldprimer-dim-command

The dimension loading commands can be targeted to only run when a specific dimension loads, by using this command prefix:

worldprimer-dim-command <dim id> <the actual command>

So for example:

worldprimer-dim-command 1 say The End dimension has loaded!

If you would just have a command without the prefix in dimensionLoadingCommands, then it will be executed any time any dimension loads, for example:

say Some dimension has loaded!

worldprimer-dim-command-nth

As of version 0.3.0, there is also another dimension loading command variant, which can run the command on a specific number of dimension loads, or on any multiple of the given value.

Note: This variant requires the option enableDimensionLoadTracking to be enabled!

The syntax for these (in the 0.6.0 and later versions) is:

worldprimer-dim-command-nth <load count> <dim id> <the actual command>

So to only run a command when the Nether loads for the very first time, you would use:

worldprimer-dim-command-nth 1 -1 say The Nether has loaded for the first time!

Or when the End loads for the 6th time:

worldprimer-dim-command-nth 6 1 say The End has loaded for the sixth time!

To run a command on any multiple of the given value, prefix the value with a '%':

worldprimer-dim-command-nth %5 1 say The End has loaded a multiple of 5 times!

Note/warning: The argument order for this prefix has changed between mod versions! The order was changed in the first 0.6.0-dev.* version.

In version 0.5.0 and older versions the usage was:

worldprimer-dim-command-nth <dim id> <load count> <the actual command>

worldprimer-tracked-command-nth

These prefixes allow you to limit for example when the player-specific commands should run.

For example in the playerRespawnCommands:

worldprimer-tracked-command-nth 3 say The player {PLAYER_NAME} has respawned for the third time at {PLAYER_X}, {PLAYER_Y}, {PLAYER_Z}
worldprimer-tracked-command-nth %5 say The player {PLAYER_NAME} has respawned for some multiple of 5 times

Command string substitutions

As of version 0.4.0, there is also support for substituting some values like the dimension id, or the current world spawn coordinates into the commands. They also support simple addition and subtraction of constant numeric values.

Note: Some of these substitutions were renamed in later mod versions! Many of these were also added in later mod versions, so if you are in an older version, all of these won't be available. Check the config file comments to see the available sunstitutions for your mod version!

The available substitution strings (in mod version 1.12.2-0.6.0-dev.20200122.211517) are:

For any commands:

• {DIMENSION} - The dimension ID
• {RAND:min,max} - Random numbers, integer and double type, for example {RAND:5,15} or {RAND:1.2,3.9} (the max value is exclusive)
• {SPAWN_X}, {SPAWN_Y}, {SPAWN_Z} - The dimension spawn point X, Y and Z coordinates
• {SPAWN_POINT_X}, ... - The spawn point X coodinate instead of the possible spawn coordinate (like in the End)
• {TIME_TICK} - The total world time in ticks
• {TIME_TICK_DAY} - The world day time in ticks
• {TIME_Y} - Real time year (4 digits: 2017)
• {TIME_M} - Real time month (2 digits: 03)
• {TIME_D} - Real time day (2 digits: 04)
• {TIME_H} - Real time hour (2 digits: 09)
• {TIME_I} - Real time minute (2 digits: 05)
• {TIME_S} - Real time second (2 digits: 07)
• {TOP_Y:x,z} - The y-coordinate of the top-most block in the world in the given coordinates (actually the air block above it). For example: {TOP_Y:-37,538}
• {TOP_Y_RAND:x,z;x-range,z-range} - The x y z coordinates of the top-most block in the world in a random location around a given x,z location (again, actually the air block above it). For example: {TOP_Y_RAND:-37,538;32,32} would be the top block at a random location within 32 blocks of x = -37, z = 538. That substitution will be replaced with the coordinates string like -49 72 544.

For player-specific commands such as playerJoinCommands:

• {PLAYER_NAME} - The player's name
• {PLAYER_X}, {PLAYER_Y}, {PLAYER_Z} - The player's current position X, Y and Z position
• {PLAYER_BED_X}, {PLAYER_BED_Y}, {PLAYER_BED_Z} - The last set (bed) spawn point
• {PLAYER_BED_SPAWN_X}, {PLAYER_BED_SPAWN_Y}, {PLAYER_BED_SPAWN_Z} - These also check that the bed exists, or otherwise they will revert to the fallback world spawn point. Note that these will load that one chunk to check for the bed.

Substitution examples

So for example, you can now do this in postWorldCreationCommands, to make the player spawn in a 5 x 5 x 3 cobblestone room under ground:

gameRule spawnRadius 0
setworldspawn {SPAWN_X} 7 {SPAWN_Z} (moves the world spawnpoint down to y = 7)
fill {SPAWN_X}-3 6 {SPAWN_Z}-3 {SPAWN_X}+3 10 {SPAWN_Z}+3 minecraft:cobblestone
fill {SPAWN_X}-2 7 {SPAWN_Z}-2 {SPAWN_X}+2 9 {SPAWN_Z}+2 minecraft:air

The spawnRadius 0 game rule sets the "spawn fuzz" to 0, so the player will spawn exactly at the world spawn point, and not on the surface (on top of the highest block) around the given radius (horizontally) from the exact spawn point. So in other words the player will spawn in the center of the small room, and not randomly somewhere around that room on the surface.

The fill commands will make a 5x5x3 room of air inside a cobblestone shell (walls, floor and ceiling) inside the ground, or whatever happened to be there originally.

Built-in commands

There are a few commands, bot "fake" and "actual commands" that World Primer provides. The "fake" commands only work from the config file, and aren't actual registered commands.

Schematic save/place commands

• The create-structure command can be used to save a given area either as a MCEdit/Schematica format .schematic file, or a vanilla Structure Block template .nbt file.
• The place-structure command can be used to place/paste a schematic to the world.
• The files go in config/worldprimer/structures/.

Tip: Tab-completion should work for everything.

• The create-structure command was added in mod version 1.12.2-0.6.0-dev.20180502.210326
• The place-structure command was added in mod version 1.12.2-0.6.0-dev.20171010.003436

Command format for create-structure

/worldprimer create-structure <x1> <y1> <z1> <x2> <y2> <z2> <schematic | vanilla> <name>

Where the schematic or vanilla argument defines if it's created in the MCEdit/Schematica .schematic format or in the vanilla Structure Block template .nbt format.

Examples:

/worldprimer create-structure 123 64 123 180 90 180 vanilla my_structure
/worldprimer create-structure 123 64 123 180 90 180 schematic my_schematic

Command format for place-structure

/worldprimer place-structure <x> <y> <z> <name> [rotation: none | cw_90 | cw_180 | ccw_90] [mirror: none | left_right | front_back] [centered] [data-functions]

• The rotation, mirror, centered and data-functions arguments are optional if you don't need them, but they are positional, so you need to add them starting from the left.
• The centered argument centers the structure (only horizontally!) to the given coordinate
• The data-functions argument causes any DATA type Structure Block's Custom Data Tag Name (metadata String tag) from the schematic to be interpreted as functions to run via the vanilla /function command

Examples:

/worldprimer place-structure 123 64 123 my_structure.nbt
/worldprimer place-structure 123 64 123 my_structure.nbt cw_90
/worldprimer place-structure 123 64 123 my_structure.nbt ccw_90 left_right
/worldprimer place-structure 123 64 123 my_structure.nbt none none centered

worldprimer-load-chunks (fake command)

As of version 0.5.0 there is a built-in "fake" chunk loading command:

worldprimer-load-chunks <chunkXMin> <chunkZMin> <chunkXMax> <chunkZMax>

Note: This isn't an actual registered command, and thus it's not usable via chat/server console, but instead it's only used internally if found in the config file.

It can be used to load a range of chunks, so that some other commands can actually work. For example the vanilla /fill and /setblock commands only work in loaded chunks, so this can be used to load the chunks before executing the /fill or /setblock commands. The chunks are also immediately queued for unloading, so they shouldn't stay loaded even until the next world save happens (every 45 seconds, when "should-not-be-loaded" chunks are normally unloaded), but instead they should unload on the next game tick.

The coordinates for this "command" are chunk coordinates (so block coordinates divided by 16). The range is inclusive, meaning from the minimum up to and including the maximum.

As of version 1.12.2-0.6.0-dev.20171117.213848 there is also another variant of this command, worldprimer-load-blocks, which just uses block coordinates instead of chunk coordinates. The loaded area will still of course be chunk aligned.

Here is an example of how to build a bedrock box at 0,0 in the End dimension when it loads for the first time. These would be added to dimensionLoadingCommands:

worldprimer-dim-command-nth 1 1 worldprimer-load-chunks -1 -1 0 0
worldprimer-dim-command-nth 1 1 fill 10 0 10 -10 7 -10 minecraft:bedrock
worldprimer-dim-command-nth 1 1 fill 9 1 9 -9 6 -9 minecraft:air
worldprimer-dim-command-nth 1 1 say Finished building your box!

/worldprimer spread-player

This command was added in version 1.12.2-0.6.0-dev.20190814.220944. Here is the description of the available options, and how the command works:

/worldprimer spread-player [options] <playername1 playername2 ...>

The command has two location search/selection modes: grid, and random. If the grid option is given with the grid size, then the grid mode is used. Otherwise the randomized location mode is used.

Options:

• --find-surface=<true | false> - If true, then the y-position is set to the top solid block on the found x/z position.
• --grid=<integer> - If given, then an outwards spriraling grid search pattern is used instead of randomized locations. The value is the interval betweeen the grid points.
• --max-radius=<integer> - The maximum distance from 0, 0 (per axis, not the absolute distance)
• --min-separation=<integer> - The minimum distance to previous player spread positions and any currently online players in the same dimension
• --new - If given, then if the command is run again for a player who was already spread previously, then a new location is generated, instead of teleporting them back to the original spread location
• --y=<integer> - If given, then this fixed y height is used
• --y-offset=<integer> - If given, and --find-surface=true, then this offset value will be added to the surface y position. This allows for example the position to be offset a certain distance under ground
• --y-max=<integer> - Limits the (possibly offset) y position from the --find-surface=true case
• --y-min=<integer> - Limits the (possibly offset) y position from the --find-surface=true case

Example:

/worldprimer spread-player --find-surface=true --min-separation=1024 --max-radius=10000 --new player_name

Discord

If you have ideas or questions or feedback, or maybe you just want to hang out, you can join us on Discord. It's linked in the side bar.