---
layout: default
title: Modpack Format
nav_order: 4
---

# Modpack Format

## Project Layout

`rimpack` treats a modpack as a normal directory tree.

Recommended shape:

```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/
    activation/
  local/
    mods/
  generated/
    diagnostics.json
    resolved_load_order.txt
```

Authored files and generated outputs are intentionally separated.

## `pack.toml`

`pack.toml` is the root manifest. It stays small and points to the rest of the project instead of
duplicating mod entries.

Minimal example:

```toml
[pack]
name = "My Modpack"
rimworld_version = "1.6"
pack_format_version = 1

[layout]
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",
]

[paths]
config_dir = "config/Mod_Configs"
diagnostics_file = "generated/diagnostics.json"
resolved_load_order_file = "generated/resolved_load_order.txt"
local_mods_dir = "local/mods"
```

Important rules:

- paths are project-relative
- `layout.mod_files` is the authoritative list order
- full mod contents do not belong in `pack.toml`
- machine-local runtime paths do not belong in `pack.toml`

## `.list` Files

`.list` files are text-first authored documents.

Supported line types:

- blank lines
- `@alias` directives
- comments
- mod entries
- unknown lines that are preserved as-is

Supported entry references:

- `steam:<workshop_id>`
- `packageid:<package_id>`
- `local:<folder_name>`

Examples:

```text
@alias libraries

# Core libraries
steam:2009463077  # Harmony
steam:818773962   # HugsLib
!local:MyFork     # disabled for testing
```

Key behavior:

- untouched lines are preserved exactly
- disabled entries use `!`, not comments
- comments are positional
- trailing comments move with their entry

## Ordering Rules

Ordering rules live in TOML files declared by `[paths].ordering_rule_files`.

Example:

```toml
[[rules]]
type = "after"
mod = "packageid:my.ce.patch"
target = "packageid:ceteam.combatextended"
reason = "Compatibility patch loads after CE"
```

Use ordering rules for exceptions and constraints. Base order still comes from:

1. file order in `layout.mod_files`
2. line order inside each `.list` file
3. enabled entries only

## Activation Rules

Activation rules live in TOML files declared by `[paths].activation_rule_files`.

Example:

```toml
[[rules]]
mod = "packageid:patch.biotech_support"
when_all_present = [
  "packageid:Ludeon.RimWorld.Biotech",
]
reason = "Only active when Biotech is enabled"
```

Activation rules are evaluated after resolution and before ordering.

They answer whether a resolved candidate mod should participate in the final active set.

## Generated Outputs

Current generated paths usually include:

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

These are outputs, not authored source-of-truth files.
