Templates and worlds

A template is one dimension of a world, kept in memory. A world opened from a template reads the template's chunks and keeps its own changes in memory — nothing is copied on disk. Any number of worlds can be open from one template, and closing a world throws its changes away.

Names (templates and worlds): letters, digits, _ - ., at most 64 characters.

The flow

1. Import a world folder as a template, once (an admin step or at setup).
2. Open a world from the template each time you need it — instant, from memory.
3. Close it when the game ends — the world folder is deleted, changes dropped.
4. Save a world back as its template when an admin edited the map and the edit should stay.

With the commands:

/fwl import maps/castle castle     # a world folder -> a template named "castle"
/fwl open castle castle-game-1     # open a world from it
/fwl save castle-game-1 castle     # keep this world as the new template (after an edit)
/fwl close castle-game-1           # unload, delete the folder, drop changes
/fwl list                          # templates and open worlds

See Commands for the full list, or the API to do this from your own plugin.

Old maps are upgraded once

Since 1.13 the server upgrades every chunk an older Minecraft wrote (DataFixer: block ids to block states, light, …) each time it loads it — also for every world opened from a template of an old map. FastWorldLoader does that once per template.

A template older than the server is upgraded in the background: at startup, and after an import or a save. Worlds keep opening from the old template meanwhile; when the upgrade is done, the next worlds open from the new one.

• upgrade-templates: false turns it off.
• /fwl upgrade <template> starts one by hand.
• A 26.x server that pauses when empty (pause-when-empty-seconds) pauses the upgrade too.

TIP

The upgrade runs a few chunks per tick within upgrade-tick-budget milliseconds and backs off when the server is busy, so it doesn't hurt a live server's TPS. A big map can take a few minutes; it only happens once.

Nether and End

A template remembers the dimension it was imported from and opens as it. importFolder(folder, template, environment) imports one dimension of a folder that has several (a world_nether folder). The API's open options can open a template as a different dimension. See the API.

Saving an edit back to a folder

exportTemplate(template, folder) (API) or a plugin like SurvivalGames writes a template back out as a normal world folder (level.dat, region files) in the server's layout — useful when another plugin or server reads world folders.