Directory Model

Last updated on

The Three Directories

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

instances/my-modpack/
├── import/     ← Pack Source: files that ship with the modpack
├── persist/    ← Local Data: files you explicitly choose to preserve
└── build/      ← Run Directory: the game directory Minecraft writes to

These names appear throughout Polymerium. See the Glossary → for the full terminology.

import/ — Pack 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

persist/ — Local Data

This directory is yours, but Polymerium does not automatically move personal data into it. You decide what goes here.

The important rule is simple: files survive reset and modpack updates only after they are placed in persist/. Your saves/ directory, screenshots, options, and mod-generated configs usually start in build/, which means reset can delete them until you move the ones you care about into persist/.

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
• What it is not: Automatic backup. Data only becomes protected after you put it here.

build/ — Run Directory

This is the final game directory — what Minecraft sees as .minecraft. It's assembled from the other layers during deploy. When you play, the game reads and writes here.

• Who writes it: Polymerium's deploy engine, and the game while you play
• When it changes: Every deploy, and every play session
• What it's for: The runnable game directory
• Can you delete it? Only with care. Reset clears build/, and anything that only exists there can be permanently lost, including saves, screenshots, logs, and game or mod configuration. Files you've moved to persist/ are safe. Files from import/, packages, metadata, and cache can be rebuilt or relinked.

How They Relate

import/  ──────────→  build/
persist/ ──────────→  build/
  (highest priority)

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

1. Cached files — mods, libraries, assets (symlinked from cache)
2. Pack Source (import/) files — modpack source files
3. Local Data (persist/) files — your preserved files (highest priority, always wins)

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

What Happens During Common Operations

¹ Clears the import working copy under build/, not the whole game directory.

Key Takeaways

• Reset clears build/. This can delete saves and game configuration unless you already moved them to persist/.
• Modpack update replaces or updates import/ and refreshes the import working copy under build/. persist/ is preserved — that's the whole point.
• build/ is disposable only for data that is backed by persist/, import/, metadata, packages, or cache. Treat personal data stored only in build/ as at risk.

Why This Matters

This 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 reset and updates.

Next Step

Learn how deploy assembles these layers → Deploy Pipeline