Skip to main content

EternalTD Custom Content Packaging

EternalTD still supports filesystem-driven custom content, but the current code expects a specific folder layout and package-tracking model.

Import Root​

Manual imports still go through:

plugins/EternalTD/imports/

After importing content manually, run:

/etd reload

Canonical Content Folders​

The current plugin scans these lowercase folders:

plugins/EternalTD/levels/
plugins/EternalTD/waves/
plugins/EternalTD/npcs/
plugins/EternalTD/worlds/

Legacy note:

  • Levels/ and NPCs/ are legacy folder names.
  • EternalTD now migrates them to levels/ and npcs/ during startup and reload.

World Packaging Rules​

EternalTD treats the worlds under:

plugins/EternalTD/worlds/

as world templates.

When a player starts a level, EternalTD clones the matching template world into the server world container and runs the session in that cloned copy.

A template is validated before it is copied, and the copy is refused if any of these hold:

  • the template has no level.dat at its root
  • the template folder is a symbolic link, or contains a symbolic link anywhere inside it
  • the template contains a file named .eternaltd-instance

That last name is reserved: EternalTD writes it into every runtime clone as an ownership marker, and refuses to delete any world folder that does not carry a matching marker. Never ship one inside a packaged template.

Practical implication:

  • package template worlds under plugins/EternalTD/worlds/
  • do not treat the runtime cloned worlds as the source of truth for packaged content
  • world folder names must be plain names — no path separators, no :, no control characters, and not . or ..

The official hub world is a special case and is tracked in the server world container directly as:

etd_spawn

What Makes a Package Toggleable​

Package toggling in /etd setup only works for packages that expose tracked config files.

The current tracked asset fields are:

  • levelFiles
  • waveFiles
  • npcFiles
  • worldFolders
  • worldContainerFolders
  • markerFileName

In practice:

  • level, wave, and NPC packages can be enabled or disabled by writing isEnabled inside those YAML files
  • tracked file names are matched recursively, so levels/, waves/, and npcs/ subfolders are fine — only the filename has to match
  • shared world-container content and marker-only resource packages are not toggleable in the same way

Package Metadata Fields​

The current package config field model supports:

  • isEnabled
  • name
  • description
  • downloadLink
  • version
  • nightbreakSlug
  • levelFiles
  • waveFiles
  • npcFiles
  • worldFolders
  • worldContainerFolders
  • markerFileName
  • category
  • toggleable

If you want custom content to behave like a tracked package in the setup UI, you need package metadata that matches those fields.

There is one more tracked field, markerFallbackFolders, which lists folders under plugins/ whose non-empty presence also counts as the package being installed. It exists for content that can reach the server without the download flow writing a marker. It is defined in code only — writing it into a package YAML has no effect.

Model-Packaging Notes​

The current EternalTD Custom Models package is tracked with a marker file rather than normal EternalTD config files.

That means:

  • EternalTD can track whether the shared model pack was downloaded
  • the actual model assets live in the FreeMinecraftModels side of the setup when FMM is installed
  • cleanup is manual and followed by /etd reload

What This Page Does Not Claim​

This page documents the current on-disk destinations and tracking model that are verified in the repo.

It does not define a first-party ZIP schema for Nightbreak package archives, because that packaging format is not spelled out in this repo as a standalone public authoring spec.