# Modpack Folder Layout Spec

## Purpose

A modpack folder should behave like a normal project directory, not an opaque app database.

It should be:

- easy to browse in a file manager
- easy to edit in a text editor
- suitable for Git
- clear about what is authored by the user versus generated by the tool

The folder layout should separate:

- authored pack definition files
- authored configuration and local content
- generated resolution and diagnostic files
- optional export and snapshot artifacts
- machine-local launch runtime state

---

## Recommended folder layout

```text
MyModpack/
  pack.toml
  README.md
  mods/
    00_core.list
    10_libraries.list
    20_ui.list
    30_gameplay.list
    40_qol.list
    50_overhaul.list
    60_factions.list
    70_combat.list
    80_graphics.list
    90_textures.list
    99_patch.list
  config/
    Mod_Configs/
  rules/
    ordering.toml
  local/
    mods/
  generated/
    resolved_load_order.txt
    diagnostics.json
  exports/
  snapshots/
```

This is the recommended full layout. Some directories are optional.

---

## Design principles

1. The modpack folder must remain understandable without the app.
2. Human-authored files must be easy to locate and edit.
3. Generated files must be clearly separated from authored files.
4. The root should stay small and readable.
5. The layout should scale to very large modpacks.

---

## Required files and directories

### `pack.toml`
Required.

This is the root manifest for the modpack project.

It should contain compact project metadata and references to the pack structure, such as:

- pack name
- RimWorld version
- ordered list of `.list` files
- paths to rule files
- path to config directory

Example:

```toml
name = "My Modpack"
rimworld_version = "1.5"

mod_files = [
  "mods/00_core.list",
  "mods/10_libraries.list",
  "mods/20_ui.list",
  "mods/30_gameplay.list",
  "mods/40_qol.list",
  "mods/50_overhaul.list",
  "mods/60_factions.list",
  "mods/70_combat.list",
  "mods/80_graphics.list",
  "mods/90_textures.list",
  "mods/99_patch.list",
]

config_dir = "config/Mod_Configs"
ordering_rules_file = "rules/ordering.toml"
```

`pack.toml` should remain small, structured, and human-readable.

---

### `mods/`
Required.

This directory contains the main authored mod list files.

Each `.list` file represents one group of mods and is ordered text-first data intended for human editing and UI manipulation.

Example:

```text
mods/
  00_core.list
  10_libraries.list
  20_ui.list
  30_gameplay.list
  40_qol.list
  50_overhaul.list
  60_factions.list
  70_combat.list
  80_graphics.list
  90_textures.list
  99_patch.list
```

The order of these files is normally determined by `mod_files` in `pack.toml`, not by filesystem enumeration.

These files are the primary source of pack author intent.

---

## Optional but strongly recommended files and directories

### `README.md`
Recommended.

This file should describe the pack for humans.

Suggested contents:

- what the pack is
- target RimWorld version
- any required setup notes
- special local content notes
- export/import notes
- known caveats

This is especially useful when the project is shared or versioned.

---

### `config/`
Recommended.

This directory contains pack-owned game configuration files that should travel with the modpack.

Suggested structure:

```text
config/
  Mod_Configs/
    HugsLib_ModSettings.xml
    RimHUD.xml
    DubsMintMenus.xml
```

This should mirror RimWorld configuration structure where practical.

This directory is considered authored state, not temporary output.

---

### `rules/`
Recommended.

This directory contains structured rule files that influence pack behavior but do not belong in `.list` files.

Suggested contents:

```text
rules/
  ordering.toml
```

Possible future additions:

```text
rules/
  ordering.toml
  known_issues.toml
```

Examples of appropriate rule data:

- explicit `before` and `after` ordering rules
- static compatibility warnings
- pack-level policy rules

Rules should not be embedded inside `.list` comments.

---

### `local/`
Optional but useful.

This directory contains pack-local authored content, such as custom compatibility mods or patch content.

Suggested structure:

```text
local/
  mods/
```

Possible uses:

- local forked mods
- private compatibility patches
- pack-specific tweak mods

This keeps pack-specific local content in a predictable place.

---

## Generated files and directories

### `generated/`
Recommended.

This directory contains files produced by the tool that can be regenerated.

Suggested contents:

```text
generated/
  resolved_load_order.txt
  diagnostics.json
```

#### `resolved_load_order.txt`
Human-readable final resolved mod order for debugging or export inspection.

#### `diagnostics.json`
Machine-readable warnings, errors, and resolution diagnostics.

### Rules for generated content

- Generated files must not be mixed with authored `.list` files or config files.
- Files in `generated/` should be safe to regenerate.
- The app should clearly treat `generated/` as output, not as source of truth.

---

## Launch runtime behavior

Launching a modpack must use a symlinked virtual RimWorld directory instead of copying the game
install or mutating the real install in place.

The tool should construct a machine-local runtime view like this:

1. Start from the configured real RimWorld install directory.
2. Create a new virtual root for the launch.
3. Symlink every top-level file and directory from the real install into the virtual root except
   the real `Mods/` directory.
4. Create a fresh `Mods/` directory inside the virtual root.
5. Populate that virtual `Mods/` directory with directory symlinks for the active mod folders in
   final resolved load-order order.
6. Resolve a separate machine-local save-data root for the pack.
7. Reuse that save-data root across launches for the same pack instead of deleting it each time.
8. Create `Config/` inside that save-data root.
9. Seed missing files in `Config/` from the pack-authored config directory referenced by
   `pack.toml` when one is declared, preserving relative file and directory layout from the
   authored config directory without overwriting existing per-pack machine-local config files.
10. Generate `Config/ModsConfig.xml` in that save-data root from the final resolved active load
   order.
11. Launch RimWorld from the virtual root while pointing the game at the separate save-data root.

This launch tree is runtime state, not pack-authored project content.

The save-data root is also machine-local state, but unlike the runtime tree it should persist per
pack so that pack-specific settings survive relaunches.

### Runtime state boundary

The symlinked launch root should be machine-local and outside the pack project by default.

The save-data/config root should also be machine-local, outside the pack project by default, and
separate per modpack.

The tool should not:

- write the launch tree into `mods/`, `config/`, `rules/`, `local/`, or `generated/`
- treat the launch tree as an export artifact
- require pack-authored files to store machine-local launch paths
- require global tool config to store per-pack runtime or save-data/config paths

### Runtime validation expectations

Before creating the launch tree, the tool should validate at least:

- the configured RimWorld install directory exists
- each selected mod root exists and is a directory
- the target launch root does not already contain unrelated content unless the tool is explicitly
  rebuilding it

Failures should produce clear diagnostics rather than partially mutating the real install.

---

## Export and snapshot directories

### `exports/`
Optional.

This directory contains user-requested exported artifacts.

Examples:

```text
exports/
  steam_collection_export.json
  modlist_export.txt
  release_2026-03-22.zip
```

Exports are not source-of-truth files.

---

### `snapshots/`
Optional.

This directory contains named pack snapshots or rollback points.

Examples:

```text
snapshots/
  2026-03-22-before-ce-rework/
  2026-03-24-ui-cleanup/
```

This is useful even when the user also uses Git, because snapshots can be app-visible and task-oriented.

---

## Root directory rules

The project root should stay minimal.

Recommended root contents:

- `pack.toml`
- `README.md`
- a small number of well-named directories

Avoid placing the following directly in the root unless there is a strong reason:

- generated diagnostics
- exported archives
- loose config XML files
- many `.list` files without a `mods/` directory
- app caches
- UI state files

---

## Authored vs generated content

The layout must clearly distinguish between authored state and generated state.

### Authored content

These are intended to be maintained by the user:

- `pack.toml`
- `README.md`
- `mods/*.list`
- `config/`
- `rules/`
- `local/`

### Generated content

These are intended to be created by the tool:

- `generated/resolved_load_order.txt`
- `generated/diagnostics.json`

This distinction should be preserved in both code and documentation.

---

## MVP layout

A smaller first version may use this reduced structure:

```text
MyModpack/
  pack.toml
  mods/
    00_core.list
    10_libraries.list
    20_ui.list
    30_gameplay.list
  config/
    Mod_Configs/
  generated/
    resolved_load_order.txt
```

This is sufficient for an early release.

Additional directories such as `rules/`, `local/`, `exports/`, and `snapshots/` can be added later.

---

## Non-goals

The folder layout should not assume:

- that all packs use local mods
- that all packs use exports
- that all packs use snapshots
- that UI-only state belongs in the project root
- that generated files should be hand-edited

---

## Suggested agent guidance

The agent should follow these rules:

1. Treat `pack.toml` as the root manifest.
2. Treat `mods/*.list` as the primary authored mod order files.
3. Treat `config/` as authored pack state.
4. Treat `generated/` as regenerated output.
5. Do not mix generated files into authored directories.
6. Prefer explicit paths from `pack.toml` over implicit filesystem discovery.
7. Keep the root directory clean and predictable.

---

## Compact machine-oriented summary

```text
folder layout:
- pack.toml is required root manifest
- mods/ contains human-authored ordered .list files
- config/ contains authored pack-owned config files
- rules/ contains structured ordering or issue rules
- local/ contains pack-local authored mods or patches
- generated/ contains resolved load-order exports and diagnostics
- exports/ contains user-requested export artifacts
- snapshots/ contains restore points
- launch runtime state is machine-local and outside the pack project by default

authored:
- pack.toml
- README.md
- mods/*.list
- config/
- rules/
- local/

generated:
- generated/resolved_load_order.txt
- generated/diagnostics.json
```
