Four-Layer Directory Model

Last updated on

The Four Layers

Every instance in Polymerium has four directories. Each has a different job and a different lifecycle:

instances/my-modpack/
├── import/     ← Files that ship with the modpack (authoritative source)
├── live/       ← Working copy — receives in-game modifications
├── persist/    ← Files you choose to preserve across resets and updates
└── build/      ← The deployed game directory (build artifact)

import/ — The Modpack Source

This is what the modpack author intended. When you import a modpack, its files land here — configs, default options, custom resources, etc.

• Who writes it: The modpack author (via import or manual placement)
• When it changes: When you update or re-import the modpack
• What it's for: The authoritative, distributable version of the modpack's files

live/ — The Working Copy

This is a writable copy of import/. When you play the game, in-game changes (modified configs, generated files) land here instead of in import/.

• Who writes it: The game runtime (and you, when tweaking configs)
• When it changes: Every play session
• What it's for: A sandbox for runtime modifications without polluting the source

persist/ — User-Managed Persistence

This directory is yours. Polymerium doesn't write to it automatically — you decide what goes here.

The idea is simple: some files are too important to lose on reset or modpack update. Maybe your options.txt has sensitivity settings you spent an hour dialing in, or your saves/ directory has a world you can't afford to lose. You move those files into persist/ yourself.

How it works:

1. For single files — move the file from build/ to persist/. For example, move build/options.txt to persist/options.txt. On the next deploy, Polymerium will link persist/options.txt into build/ with the highest priority, so your version always wins.

2. For directories — move the directory (e.g. saves/) into persist/, then create an empty .keep file inside it: persist/saves/.keep. This tells Polymerium to project the entire directory into build/.

• Who writes it: You
• When it changes: When you decide to add or update files
• What it's for: Files you want to survive resets, modpack updates, and rebuilds

build/ — The Deployed Game

This is the final game directory — what Minecraft sees as .minecraft. It's assembled from the other layers during deploy.

• Who writes it: Polymerium's deploy engine
• When it changes: Every deploy
• What it's for: The runnable game directory
• Can you delete it? Yes — but anything that only exists in build/ and isn't backed by persist/, live/, or import/ will be lost. Files you've moved to persist/ are always safe. Everything else gets rebuilt from the metadata and cache.

How They Relate

import/ ─────→ live/ ─────→ build/
                ↑              ↑
          Game writes    Final game dir
                │              
persist/ ───────┴────────────→ build/
  (highest priority, user-managed)

During deploy, files are layered into build/ in this order:

1. Cached files — mods, libraries, assets (symlinked from cache)
2. import/ files — modpack source files
3. live/ files — working copy (overrides import)
4. persist/ files — your preserved files (highest priority, always wins)

If the same file exists in both live/ and persist/, the persist/ version takes precedence in build/.

What Happens During Common Operations

Key Takeaways

• Reset clears live/ and build/. Files you've placed in persist/ are untouched.
• Modpack update replaces import/ and clears live/. persist/ is preserved — that's the whole point.
• build/ is disposable as long as anything you care about is backed by persist/.

Why This Matters

This four-layer model solves a real tension in modded Minecraft:

• Modpack authors want to distribute consistent configs and resources.
• Players want to keep their settings and saves across updates.
• Both want modpack updates to work without losing important data.

Polymerium's answer: separate these concerns into distinct directories with different lifecycles. You control what's preserved — move it to persist/, and Polymerium guarantees it survives.

Next Step

Learn how deploy assembles these layers → Deploy Pipeline