Subworld Library

Subworld Library on Your Terraria Server

Subworld Library is a pure developer library: it lets other mods add their own dimensions ("subworlds"), handling saving, lighting, and multiplayer behavior behind the scenes. One technical detail matters a lot if you run the server — per the mod's own description, it opens a separate "subserver" for every subworld that's currently occupied. That means mods with subworld support can spin up extra server processes on your tModLoader server as soon as players step into those dimensions. You enable the library normally through enabled.json; you never play it directly, it's just a silent prerequisite for mods that use subworlds.

Tip: Expect somewhat higher resource use with subworld-enabled mods once several players occupy different subworlds at the same time.

Plan the rollout and operation

Subworld Library is useful only with a specific subworld content mod. Document every dependency and test entry, exit, death, saving, and simultaneous players across dimensions. Watch memory and CPU because occupied subworlds may create additional processes. Update the library and content mods together. If a dimension fails to load, back up the world and characters before removing dependencies from the active list.

Before enabling it, back up the world, characters, enabled.json, and mod configuration directory, and record the tModLoader, mod, and dependency versions. Start a world copy with the full list and connect at least two matching clients. Check the core feature, saving, restarting, reconnecting, and, for content mods, world generation or progression. Agree on server-wide settings and reload them after changes in ModConfigs. Update related libraries and content mods together, while adding independent packages one at a time. Before removal, store or discard mod-owned items, NPCs, tiles, and storage structures on a copy; missing content can otherwise damage a world or character. Move to a live maintenance window only after that copy loads without errors. Keep the previous package as a rollback until several sessions have completed successfully. Publish the active list for every player so clients and server do not start with different tModLoader profiles or stale dependencies.