onion-mc/analysis/archive/FINDINGS.md

# Onion MC - Configuration, Compatibility & Performance Review

**Pack:** Onion MC 0.1.0 - Minecraft 1.21.1 / NeoForge 21.1.251 - 146 mods (packwiz; 141 Modrinth + 5 CurseForge)
**Scope:** options and settings that improve inter-mod behaviour, performance, or are useful to the
players and the server administrator.

> **Snapshot note.** The mod-list statistics in section 1 were measured against an earlier pack
> revision (140 entries). The pack has since changed: **FTB Chunks was replaced by Open Parties and
> Claims + Xaero's World Map/Minimap**, the rest of the FTB suite that depended on it (**FTB Quests,
> FTB Teams, FTB XMod Compat**) was removed, Iris/shaders landed upstream, and Clumps/C2ME/Noisium were
> added. Sections 3.3 and 7.1 have been updated for these; section 1's counts have not been re-run.

---

## How to read this document

Every claim is tagged with a confidence level, because "a Reddit comment said so" and "I read the
mod's config source" are not the same thing.

| Tag | Meaning |
| --- | --- |
| **VERIFIED** | Read from the mod's own jar metadata, upstream source code, or bundled default config. |
| **DOCUMENTED** | Stated in official project docs (Modrinth/GitHub/wiki/NeoForge docs). |
| **COMMUNITY** | User reports (Reddit, forums). Directionally useful, not authoritative. |
| **INFERENCE** | My reasoning from the above. |

Methods used: Modrinth API (project + version metadata for all 131 Modrinth-tracked mods), extraction
of all 131 mod jars (reading `META-INF/neoforge.mods.toml` for dependencies, sides and declared
incompatibilities), upstream source/config files on GitHub/GitLab, and official documentation.

> **Section 8 lists what is still unverified.** Nothing there should be acted on as fact.

---

## 1. Pack state - it is in good shape

This matters because it means the work here is **tuning, not repair**. There is no fire to put out.

### 1.1 Integrity - VERIFIED

| Check | Result |
| --- | --- |
| Version validity (every pinned version supports 1.21.1 + NeoForge/Forge) | **129 / 131 OK** |
| Unsatisfied required dependencies | **0** |
| `side` flags that disagree with Modrinth's authoritative client/server support | **0** |
| Mods that would be wrongly installed on a dedicated server | **0** |

- The two non-"release" pins are **Incendium** and **Sound Physics Remastered**, both tagged
  `alpha` on Modrinth. For Incendium that is normal (Stardust Labs datapacks); for Sound Physics
  Remastered 1.5.1 it is currently the *only* 1.21.1 NeoForge build.
- Libs that look "missing" are correctly bundled via jar-in-jar: `apollib` (inside Tectonic and
  Lithostitched), `flywheel` + `ponder` (inside Create), `atmosphere` (Slice & Dice),
  `sablecompanion` (Sable), `mezz_config` (JEI), `Registrate` (Create/Ars Delight/Twilight Delight).
- The 16 client-only mods carry `side = "client"`, so `packwiz-installer -s server` will exclude them.
  **The server mod list is already correct - do not hand-prune it.**

### 1.2 Version currency - VERIFIED

108 / 131 pins are the newest 1.21.1 NeoForge build. The 23 that are behind are mostly trivial patch
bumps, with three worth a decision:

| Mod | Pinned | Newest 1.21.1 | Note |
| --- | --- | --- | --- |
| Terralith | 2.5.8 | **2.6.2** | Minor bump. **New worlds only** - see section 2.4. |
| Apotheosis | 8.8.0 | 8.9.0 | Feature release. |
| Sophisticated Storage | 1.5.91 | 1.6.0 | Minor bump. |

Also available: **NeoForge 21.1.252** (pack pins .251). The 21.1.x line is the 1.21.1 LTS branch and
still receives fixes, so a patch bump is low-risk if you want bugfixes.

### 1.3 Declared incompatibilities - VERIFIED

These are asserted by the mods' own metadata. They are not opinions.

| Mod | Declares incompatible | In pack? |
| --- | --- | --- |
| `create` | `radium`, `palladium` | No [OK] - **never add Radium** |
| `sodium` | `embeddium` (any version) | No [OK] - **never add Embeddium** |
| `sable` | `scalablelux`, `sablecompanion` > 1.6.0 | No [OK] |
| `distanthorizons` | `ssrd` <= **1.8.6** | 1.8.7 [OK] - **one release clear of a hard break** |
| `geckolib` | `geckoanimfix` | No [OK] |
| `cristel-lib` | `t_and_t` <= 1.13.3 | 1.13.11 [OK] |

### 1.4 Hard version constraints - do not break these

**VERIFIED** from mod metadata. These are the version pins that are load-bearing:

1. **Sodium must stay >= `0.8.12-alpha.2+mc1.21.1`.** `sable` declares every Sodium below that
   incompatible. Current 0.8.13 is fine. *Downgrading Sodium breaks Create Aeronautics.*
2. **SSRD must stay >= 1.8.7.** Distant Horizons declares SSRD <= 1.8.6 incompatible.
3. **`create-enchantment-industry` requires Create >= 6.0.10** and `create_dragons_plus` >= 1.11.9.
   The pack sits *exactly* on both minimums, so Create cannot be downgraded.
4. **`ssrd` requires `sable` and `sodium`** (`sodium` at `side=CLIENT`, so the dedicated server is
   unaffected).
5. **Towns and Towers must stay > 1.13.3** (cristel-lib constraint).

---

## 2. Where the server load actually comes from

Four cost centres dominate, in rough order of impact. Everything in section 3 maps to one of these.

1. **Worldgen & structure density** - this pack stacks Terralith + Tectonic + Incendium + Nullscape +
   Towns and Towers + When Dungeons Arise + nine YUNG's mods + Explorify. Structure-heavy worldgen is
   the classic cause of chunk-generation spikes and stutter while players explore.
2. **Apotheosis spawners and entities** - Apotheosis spawners can manufacture mob counts far beyond
   vanilla, and spawner-spawned mobs are *deliberately prevented from despawning*.
3. **Create + Sable physics** - Create Aeronautics runs a physics pipeline. Sable's own README calls
   itself "an incredibly intrusive mod" that "makes extensive use of mixins" and is "prone to many
   compatibility issues". This is the highest-risk component in the pack.
4. **OPAC claim force-loading + offline chunk loading** - per-player force-loaded chunks that tick
   even when nobody is online.

---

## 3. Server tuning

### 3.1 Structure density - the single biggest lever

**Sparse Structures is already in the pack and already active.** - DOCUMENTED/VERIFIED

- Config file: **`config/sparsestructures.json5`** (confirmed in `Constants.java`:
  `Path.of("config", "sparsestructures.json5")`).
- **`spreadFactor` - default `2`.** This multiplies structure spacing globally: >1 = rarer,
  1 = untouched, <1 = more common. So the pack is *already* halving structure frequency versus
  default. Good default; raising it is the cheapest TPS win available.
- **`customSpreadFactors`** - array of `{ "structure": "namespace:name", "factor": n }`. The value
  may be a **structure set** or a **structure name**; using a structure name modifies the whole set
  it belongs to.
- `/dumpstructuresets` dumps every structure set to a file - use this to get real names instead of
  guessing.
- **Changes require a full game restart.**
- Source: <https://github.com/MaxenceDC/sparsestructures> (`sparse-structures-default-config.json5`)

Suggested next step - push the expensive/oversized structure sets harder than the global 2x:

```json5
{
  "spreadFactor": 2,
  "customSpreadFactors": [
    { "structure": "minecraft:mansion", "factor": 2 }
    // run /dumpstructuresets, then add entries for the dungeons_arise:*
    // and t_and_t:* sets with factor 3-4
  ]
}
```

> **Caveat (INFERENCE):** I have not verified the exact `dungeons_arise` / `t_and_t` structure-set
> names. Use `/dumpstructuresets` on the server to obtain them rather than copying names from the web.

**Chunky** (in pack) is the other half: pregenerate so players don't force live generation.
DOCUMENTED - commands are `/chunky radius <n>`, `/chunky world <dim>`, `/chunky center`, `/chunky start`,
`/chunky pause`, `/chunky continue`. See section 3.4 for the Chunky <-> Distant Horizons interaction, which
matters here.

### 3.2 Apotheosis - entity accumulation

**VERIFIED** by reading the config source of Apothic Spawners 1.21 branch.

Config file: **`config/apothic_spawners.cfg`** - section `[general]`:

| Key | Default | Notes |
| --- | --- | --- |
| **`Entity Despawn Delay`** | **600** | Ticks that spawner-spawned mobs are *prevented from despawning* after spawning. Range 0-24000. |
| `Spawners Drop Empty` | false | Clears stored entity when broken. |
| `Capturing Drop Chance` | 0.005 | Per-level spawn-egg drop chance. |
| `Spawner Silk Level` | 1 | Silk touch level needed; -1 disables. |
| `Spawner Silk Damage` | 100 | Durability damage per spawner harvested. |

`Entity Despawn Delay` is the lever most people miss. At the default 600 ticks, every spawner keeps
its output alive for 30 seconds regardless of mobcap pressure. On a server with several upgraded
spawners this is a steady entity tax. **Lowering it to 0-100 is a direct, low-risk TPS improvement**
and is unlikely to be noticed by players (vanilla spawners have no such protection).

> Note: this config surface is *small*. In Apotheosis 8.x the spawner **modifiers** (spawn range,
> delay, count, ...) are **datapack-driven**, not config-driven. So you cannot cap spawner throughput
> from the config file alone - `Entity Despawn Delay` plus the loot-table/datapack layer is what you
> have.

Config file: **`config/apotheosis/apotheosis.cfg`** - sections and keys (defaults in parentheses), all **VERIFIED**:

> **Note the directory.** Apotheosis's module configs are *not* in the config root: `configDir` is
defined as `<config>/apotheosis` (`ApothicAttributes.java`, line 58), and `getConfigFile(p)` returns
`<config>/apotheosis/<p>.cfg`. The one exception is Apothic Spawners, which uses Placebo's
`Configuration(String)` constructor and therefore lands at the config root as
`config/apothic_spawners.cfg`. Do not go looking for `config/apotheosis.cfg` - it does not exist.

| Section | Key | Default |
| --- | --- | --- |
| `bosses` | `Boss Spawn Cooldown` | 3600 ticks (3 min) |
| `bosses` | `Boss Announcement Range` | vanilla spawn distance + 12 blocks |
| `bosses` | `Curse Boss Items` / `Boss Auto-Aggro` / `Boss Glowing On Spawn` | false / false / true |
| `worldgen` | **`Generation Dimension Whitelist`** | `["overworld"]` |
| `spawners` | `Spawner Value Chance` | 0.11 |
| `affixes` | `Cleave Players`, `Disable Quark Tooltips for Affix Items`, `Torch Placement Item` | false / true / `minecraft:torch` |
| `augmenting` | `Upgrade Sigil Cost` / `Upgrade Level Cost` / `Reroll Sigil Cost` / `Reroll Level Cost` | 2 / 225 / 1 / 175 |
| `potion_charms` | `Restrict Charms to Curios` | false |
| `quality_of_life` | `Enable Item Linking`, `Item Linking Cooldown`, `Enable Equipment Comparisons` | true / 100 / true |
| `flair` | `Enable Affix Item Effects` | true (clientside) |
| `world_tiers` | `Enable Manual World Tier Changes` | true |

Two worth acting on:

- **`Boss Spawn Cooldown`** (3600): invading bosses are among the most expensive things Apotheosis
  spawns. Raising this is a legitimate, cheap difficulty/load dial.
- **`Generation Dimension Whitelist`** = `["overworld"]`: Apotheosis worldgen currently only runs in
  the Overworld. This pack has Twilight Forest, plus Incendium's Nether and Nullscape's End. If you
  want rogue spawners/boss dungeons there you must add the dimension IDs - and understand that doing
  so *increases* worldgen cost.

Related configs, same pattern (`config/apotheosis/apothic_attributes.cfg`,
`config/apotheosis/apothic_enchanting.cfg`, and `config/apotheosis/name_generation.cfg`):

- `apothic_attributes.cfg` -> `[combat_rules]` holds the damage formulas as **editable expressions**
  (`Protection Formula`, `A-Value Formula`, `Armor Formula`, `Armor Toughness Formula`,
  `Negative Armor Factor`=0.015). These are how you retune Apotheosis combat *without* a mod - useful
  because Apotheosis's armour model is the thing players most often call "broken" in a pack with
  Better Combat. `[general] Hidden Attributes` controls what shows in the attributes GUI (supports
  namespace wildcards and `!` negation entries).
- `apothic_enchanting.cfg` -> `[client]` `Sculkshelf Noise Chance` = **200** (1-in-200 chance per
  *client tick* to play a sculk shelf sound; `0` disables). Minor client perf/noise lever.

### 3.3 Open Parties and Claims - force-loading and ticking

**Replaces FTB Chunks** (removed 2026-09-30 in favour of Open Parties and Claims + Xaero's
World Map/Minimap; see `analysis/FTB-CHUNKS-SWAP.md`). Everything below is the OPAC equivalent of the
tuning this section used to document for FTB Chunks.

**DOCUMENTED** - OPAC's main config lives **inside the world save**, not the pack:

| File | Purpose |
| --- | --- |
| `world/serverconfig/openpartiesandclaims-server.toml` | Main server config (limits, protection, forceloading, party backend). |
| `world/serverconfig/openpartiesandclaims-*` | Global "player configs" (default player config, server-claim, expired-claim, wilderness). |
| `<server dir>/config/openpartiesandclaims-server.toml` | Reported location on Fabric/Quilt only. |

**Warning - stop the server before editing.** The README is explicit: the server may overwrite your
changes otherwise. Do **not** assume the file the server generated matches any list here; read the
generated file, which carries inline `# Default:` comments for every key.

**Easiest route for an admin:** in-game, the mod UI is bound to `'` by default. Claim/party commands
are `/oclaims`, `/oparties`, `/opac` and `/opm` (party chat). Server-wide options are still edited in
the file, not the UI.

**`defaultconfigs/` and packwiz cannot help here** - the file is in the world save, so it cannot be
shipped at all. See section 7.1.

Keys and defaults - **DOCUMENTED where the project's own issue quotes or README state them**, else
flagged:

| Key | Default | Why it matters |
| --- | --- | --- |
| `maxPlayerClaims` | 500 | Per-player claim cap. Same as FTB Chunks' `max_claimed_chunks`, so no capacity loss on the swap. Overridable via the `xaero.pac_max_claims` permission. |
| `maxPlayerClaimForceloads` | low/0 - **verify** | Per-player forceload cap. **This pack sets it to 25** (matching FTB Chunks' old `max_force_loaded_chunks`); the stock default is not 25, so leaving it unset silently removes forceloading. Overridable via `xaero.pac_max_forceloads`. |
| `claims.forceload.offlineForceload` | **verify** (documented as "true" in a 2021 issue, so possibly stale) | Force-loaded chunks stay loaded while the owner is **offline**. This is the OPAC equivalent of FTB Chunks' `chunk_load_offline`, and the same farms-vs-TPS trade applies: 25 forceloads x ~10 players is potentially 250 chunks ticking around the clock. |
| `primaryPartySystem` | built-in | **Left at OPAC's built-in default** - FTB Teams was removed along with FTB Quests, so the built-in system is now the only one. Pointing this at `ftbteams` would be a no-op that logs missing-mod noise. |
| `staticFakePlayers` | - | Position-bound fake players for automation (miners, auto-clickers). The analogue of FTB Chunks' `fake_players`. |
| `playerConfigurablePlayerConfigOptions` / `opConfigurablePlayerConfigOptions` | - | Which options players (and OPs) may change in their own config. Adding a key to these arrays is what exposes it - e.g. `claims.forceload.offlineForceload` is not player-changeable until listed. |
| protection exception lists | - | `forcedBlockProtectionExceptionList`, `forcedEntityProtectionExceptionList`, `itemUseProtectionExceptionList`, plus the optional per-claim groups. This is OPAC's answer to FTB Chunks' protection; modded blocks/entities that misbehave go here. |

**Recommended starting point for a ~10-player server:** keep `maxPlayerClaims = 500`,
`maxPlayerClaimForceloads = 25` (decided 2026-09-30), leave `primaryPartySystem` at the built-in
default, and take a deliberate decision on `claims.forceload.offlineForceload` - it is the same straight
farms-vs-TPS trade FTB Chunks' `chunk_load_offline` was, with a larger blast radius now that each player
may forceload 25 chunks.

**Reliability caveat - COMMUNITY (open upstream issues).** OPAC force-loading has a recurring "marked
the chunk but it does not actually stay loaded" failure mode with issues open at the time of writing
(#855, #927, plus #237/#528 further back). Because this pack's farm design leans on offline
force-loading, verify per-player forceloading on a staging world *before* trusting it, and re-test
after each OPAC bump.

Sources: <https://github.com/thexaero/open-parties-and-claims> (README: config locations, permission
nodes, `primaryPartySystem`, `staticFakePlayers`), <https://modrinth.com/mod/open-parties-and-claims>
(commands, keybind, FAQ; also states the mod is in beta),
<https://github.com/thexaero/open-parties-and-claims/issues/228> and
<https://github.com/thexaero/open-parties-and-claims/issues/731> (default keys and the
`offlineForceload` description), <https://github.com/thexaero/open-parties-and-claims/issues/855>
(force-loading reliability).

### 3.4 Distant Horizons - decide deliberately, and mind Chunky

**DOCUMENTED** - Distant Horizons has real server-side support and it is opt-in. From the official
"Server Owners" wiki:

- **DH >= 2.3 is required on a server**; older builds crash. The pack's 3.3.2 is fine.
- **"Using the same version / build on both the server and the client is strongly preferred."**
- Server support only engages if **"Distant Generation" is enabled on both server and client**;
  the same applies to every toggle with a server-side counterpart.
- DH is **optional on both sides** - vanilla clients can still connect. So marking it optional in the
  pack is correct and safe.
- Default settings need **>= 500 KB/s (4 Mbit/s)** per client. If players see "Timed out" kicks, lower
  their client bandwidth settings.
- **"Pre-generating LODs is highly recommended to avoid performance issues."**
- **Warning: Chunky interaction:** *"Running Chunky will also generate & update LODs, but it's not
  recommended to rely on this behavior for pre-generation. LODs and chunks are independent, and by
  loading a lot of chunks quickly you risk overloading DH and ending up with a lot of holes. Either
  use DH's pre-generation, or temporarily disable the mod entirely."*
  **This pack has both Chunky and DH.** If you pregenerate with Chunky, expect DH LOD holes. Use
  `/dh pregen` instead, or disable DH while Chunky runs.

Server-side config keys (use `/dh config <key>`; the command prints the current value, description and
the config file path, which is the reliable way to find the file):

| Setting | Purpose |
| --- | --- |
| `common.threadPreset` | CPU load preset for DH's worker threads. |
| `common.maxDataTransferSpeed` | Per-player bandwidth cap. |
| `generation.mode` | Set to `INTERNAL_SERVER` to generate chunks alongside LODs. |
| `generation.requestRateLimit` | Requests/second cap. |
| `generation.maxRequestDistance` | Per-player generation radius. |
| `generation.nSized` | Experimental: generate LODs directly at the required size. |
| `generation.bounds.x` / `.z` / `.radius` | Global generation area restriction (disabled while `radius` is 0). |
| `realTimeUpdates.playerDistance` | How far chunk updates are converted to LOD pushes. |
| `syncOnLoad.rateLimit` / `syncOnLoad.maxRequestDistance` | Login-time sync throttling. |
| `levelKeyPrefix` | **Required if several servers share a proxy** - set a unique string. |

Also: pregenerate **beyond the world border** if you use one, or clients will show LOD holes at the edge.
**Avoid running `/dh pregen` on a server people are actively playing on.**

Source: <https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/5-server-owners/Server-Owners>

### 3.5 Diagnosing lag: spark is already installed

**DOCUMENTED** - `spark` 1.10.124 is in the pack, so no setup is needed. Per spark's own docs, ~30
seconds of profiling is enough for useful results.

Admin workflow:

- `/spark tps` - accurate TPS.
- `/spark health` - TPS, tick durations (min/avg/max), CPU usage, GC activity. **Start here.**
- `/spark profiler start --timeout 60` - sample the server; then `/spark profiler stop`.
  Target specific threads with `--thread`, and record only slow periods to cut noise.
- Use GC figures from `/spark health` to decide heap/GC flags rather than guessing.
- On Linux x86_64 spark uses async-profiler via `perf_events`, which gives better results than the
  fallback `ThreadMXBean` engine - worth knowing when comparing reports.

Docs: <https://spark.lucko.me/docs>

---

## 4. Client tuning and cross-mod conflicts

### 4.1 The SSRD -> Distant Horizons -> Sodium chain

**VERIFIED/DOCUMENTED.** SSRD ("Separate Sable Render Distance") is a *client rendering* addon that
exists to decouple Sable's sub-level render distance from the normal one.

- SSRD's own README: **"Distant Horizons or voxy AND Sodium MUST be installed on the Client!"**
- **Versions 1.8 and up REQUIRE Sodium 0.8.** The pack has Sodium 0.8.13 [OK] and SSRD 1.8.7 [OK].
- **But Distant Horizons is marked `optional = true, default = false` in the pack.**
  **INFERENCE:** any player who leaves DH disabled gets a non-functional SSRD. Either ship DH by
  default, or mark SSRD optional alongside DH so the two travel together.
- SSRD has **server-side gamerules**:
  - `/gamerule ssrdMaxRenderDistance` - default **128** chunks (server-wide cap).
  - `/gamerule ssrdForceloadLimit` - default **2** per player for `/ssrd forceload`.
  - `/ssrd forceload` does not require op but respects that cap.
- SSRD README also warns: *"Certain Iris shader packs cause rendering issues."*

### 4.2 EntityCulling will break Ars Nouveau's spell visuals

**DOCUMENTED** - EntityCulling's README: *"Client-side entities, commonly used by magic mods for
animations, may not behave as expected. Whitelist the relevant entities via the config screen for tick
culling and/or entity culling."*

**INFERENCE:** this pack has Ars Nouveau, which uses client-side entities for spell/projectile visuals,
plus Create Aeronautics (Sable) and several mob mods with custom animations. EntityCulling has a wide
whitelist surface and its config screen supports per-entity toggles - expect to need it. EntityCulling
is a solid win in general (it is one of the biggest client FPS wins on busy servers), so whitelist
rather than remove.

### 4.3 Should you add shaders? Probably not yet

**DOCUMENTED**, two independent blockers:

1. **Create Aeronautics 1.1.3 README:** *"Aeronautics currently has visual issues when used with
   **Iris Shaders**."*
2. **SSRD README:** certain Iris shader packs cause rendering issues.

Combined with the fact that the pack contains **no shader mod at all** (no Iris/Oculus) and that DH +
Sodium + Sable already form a tight, version-sensitive trio, adding shaders introduces a new
compatibility axis in exactly the most fragile part of the pack. **INFERENCE: leave shaders out** unless
you are willing to own that debugging surface.

### 4.4 Tectonic - optional terrain knobs

**VERIFIED** from Tectonic v3 config source. File: **`config/tectonic.json`** (DOCUMENTED via the
official changelog: "Added a proper config to the mod version at config/tectonic.json"). Keys and
defaults:

| Group | Key | Default |
| --- | --- | --- |
| `general` | `mod_enabled` / `snow_start_offset` | true / 128 |
| `global_terrain` | `vertical_scale` / `increased_height` / `lava_tunnels` | 1.125 / **false** / true |
| `continents` | `ocean_offset` / `continents_scale` / `erosion_scale` / `ridge_scale` | -0.8 / 0.13 / 0.25 / 0.25 |
| `continents` | `underground_rivers` / `river_lanterns` / `flat_terrain_skew` / `rolling_hills` / `jungle_pillars` | true / true / 0.1 / true / true |
| `islands` | `enabled` / `noise_scale` | true / 0.11 |
| `oceans` | `ocean_depth` / `deep_ocean_depth` / `monument_offset` / `remove_frozen_ocean_ice` | -0.22 / -0.45 / -30 / false |
| `biomes` | `temperature_multiplier` / `temperature_scale` / ... | 1.0 / 0.25 / ... |

Note `increased_height` is already `false` - good. It raises the build/generation ceiling to **y640**,
which is a meaningful worldgen and memory cost. **Do not enable it on a server.**

The Tectonic wiki (<https://github.com/Apollounknowndev/tectonic/wiki/Config>) explains every option;
the in-game mod-menu config screen shows them with tooltips.

---

## 5. Terralith + Tectonic - the combination is correct

**DOCUMENTED**, and this is a commonly-messed-up setup, so it's worth confirming it's right:

- Terralith's README: *"Terralith is **fully compatible with the mod version of Tectonic**."*
- Tectonic's README: *"Tectonic has a special version with Terralith compatibility. **This version is
  shipped in the mod version of Tectonic**, but it is available as a standalone datapack
  [Terratonic]."*
- Terralith's README: *"If you are using the **datapack** versions, you must use **Terratonic
  instead** of Tectonic."*

The pack has **both as mods**, so the Terralith-compat layer is already active.
**Do not add Terratonic** - it is for the datapack route and would conflict.

### 5.1 Terralith updates require a new world

**DOCUMENTED** - Terralith's README: *"It is **not recommended to add Terralith to an existing world**
- reset yours first, or use a new world."*

Also relevant: *"In 2.6.0, the **mod** version of Terralith relies on **Lithostitched** as a required
dependency."* The pack has Terralith **2.5.8** and **already ships Lithostitched 1.8.0**, so the
eventual 2.6.x update is dependency-safe. **But it is a worldgen change - new worlds only.**

**INFERENCE / worth checking:** if the live server world predates the addition of Terralith (the pack
added it recently), terrain seams and abrupt biome transitions are expected and are not a bug.

---

## 6. Cross-mod notes worth knowing

### 6.1 Apothic Combat silently disables the attack-range affix

**DOCUMENTED** - from the Apothic Combat README (the "Better Combat x Apotheosis Compat" mod):

The problem it solves: Apotheosis adds a "Heavy Weapon" category (loosely like Better Combat's
two-handed weapons, but unrelated), and **Apotheosis/Forge treat attack range as an entity attribute**
that grows with gems and affixes, while **Better Combat defines attack range as an immutable weapon
property** in its own JSON format - so they cannot both work.

What the compat mod does:

- Registers all two-handed Better Combat weapons automatically as `HEAVY_WEAPON` for Apotheosis.
- **"Removes the Entity Reach Attribute from all weapons, and makes the attack range affix
  nonfunctional."**

**Player-facing consequence:** any gem/affix investment in attack range does nothing in this pack.
That is a legitimate thing to tell players, and if you want, the README notes that *disabling the
Apotheosis Attack Range affix from appearing at all* is possible via datapack.

Source: <https://modrinth.com/mod/apothic-combat>

### 6.2 Apotheosis enchanting vs other enchanting overhauls

**COMMUNITY.** The well-known Apotheosis enchanting-table conflict is with **Quark**, which is *not* in
this pack, so that specific issue does not apply. No verified conflict with Ars Nouveau's enchanting
was found. Flagging only that both touch the enchanting system; if you see an enchanting-table UI
problem, test with Apothic Enchanting disabled first.

### 6.3 Lootr - exact keys, and one gotcha

**DOCUMENTED** - file **`config/lootr-common.toml`**. Lootr **must be installed on both client and
server** (its FAQ is explicit). Selected keys and defaults:

| Key | Default | Notes |
| --- | --- | --- |
| `disable_break` | false | Prevents breaking Lootr containers except sneaking in **creative**. |
| `blast_resistant` | false | Makes Lootr containers explosion-proof. |
| `decay_all` | false | **All** chests decay after first open (overrides the per-list options). |
| `decay_value` | 6000 | Ticks for a decaying container to decay (5 min). |
| `decay_dimensions` / `decay_modids` / `decay_loot_tables` | `[]` | Targeted decay. |
| `refresh_all` | false | **All** chests refresh after first open. |
| `refresh_value` | 24000 | Ticks to refresh (20 min). |
| `refresh_dimensions` / `refresh_modids` / `refresh_loot_tables` | `[]` | Targeted refresh. |
| `convert_wooden_chests` / `convert_trapped_chests` / `convert_mineshafts` | true | Conversion scope. |
| `convert_quark` | true | Quark isn't in this pack; harmless. |
| `skip_unloaded` | true | Skip containers in unloaded chunks (queued for later). |
| `maximum_age` | 3600 | How long a container may sit in the conversion queue (180x20 ticks). |
| `loot_modid_blacklist` / `loot_table_blacklist` / `dimension_blacklist` / `dimension_whitelist` | `[]` | Exclusions. |
| `power_comparators` | true | Comparators output 1 - **important for trap-based structures**; `false` makes traps fire on load. |
| `report_unresolved_tables` | false | Log unresolved loot tables. |
| `randomise_seed` | true | Warning: see caveat below. |
| `vanilla_textures` | false | Client-side; hides Lootr textures. |

Two things to flag:

- **Warning: `randomise_seed`'s documentation is contradictory** in the official wiki - the Forge section
  and the Fabric section describe opposite behaviours. **Do not change this key on the strength of the
  wiki alone**; test on a scratch world first.
- **Warning: Structure blacklists do not work on 1.21.1.** The wiki states plainly: *"structure blacklists
  are not functional outside of 1.16.5 due to tagging and holder changes."* So `decay_structures` and
  `loot_structure_blacklist` are dead keys here. Don't waste time on them.

Lootr interacts with the pack's structure mods (When Dungeons Arise, the nine YUNG's mods) and with
Apotheosis loot tables by converting their chests. If a specific structure's loot behaves oddly, the
`loot_table_blacklist` / `loot_modid_blacklist` route is the supported fix - not the structure keys.

### 6.4 Known compatibility risks to keep on the radar

- **Sable / Create Aeronautics** - self-described as highly intrusive and mixin-heavy. If you get a
  weird crash or a visual bug you can't explain, **test with Sable removed first**. The five Sable
  compat addons in the pack (`sablecompat`, `aeronauticscompat`, `gravestone_sable_compat`,
  `waystonessable`, `sablejade`) exist precisely because it needed patching.
- **Create declares `radium` and `palladium` incompatible** - this rules out the most obvious
  "add more server performance mods" candidates. See section 7.

---

## 7. Config mechanics - how to actually apply any of this

This is the part that decides whether the rest of the document is usable.

**DOCUMENTED** (NeoForge config docs) - three locations, and they behave differently:

| Location | Scope | Synced to clients? |
| --- | --- | --- |
| `config/` | Global, both sides | Depends on config type |
| `world/serverconfig/` | **Per-world override** of `SERVER`-type configs | Yes - server wins |
| `defaultconfigs/` | Seeds new worlds | n/a |

- `SERVER`-type configs are **synced from server to client** and can be overridden per world in
  `world/serverconfig/`. `STARTUP` / `COMMON` / `CLIENT` are **not synced**.
- Server configs are only editable via the in-game screen on a local world; they are greyed out on a
  multiplayer server - so on a real server you edit the files.
- **The Apotheosis stack is the exception:** those are Placebo `.cfg` files under
  `config/apotheosis/` (+ `config/apothic_spawners.cfg`) and are **not** NeoForge `SERVER`-type
  configs, so they are not synced and not per-world. They're plain global files you edit directly.
  **This also means `defaultconfigs/` will not seed them** - see 7.1.

### 7.1 The pack currently cannot ship server configs

**VERIFIED** - `.packwizignore` contains:

```
config/
defaultconfigs/
```

So **every** config is excluded from the pack index. Consequences:

- None of the tuning in section 3 can be delivered to players or to a fresh server via the pack as it stands.
- A fresh server generates stock defaults for everything.

This is a cleaner end state than before: the only config the pack used to ship was the FTB Chunks
minimap client file, and it left with FTB Chunks (section 3.3).

**Recommendation (INFERENCE):** if you want these settings to be part of the pack rather than tribal
knowledge, un-ignore the specific files you care about (a `!config/<path>` rule alongside the `config/`
ignore) and/or use `defaultconfigs/` for per-world `SERVER`-type defaults.

**Caveat - the systems this document tunes are mostly unreachable from packwiz.**

- **OPAC** keeps its main config in `world/serverconfig/`, inside the world save. Not shippable, ever.
- the **Apotheosis stack** uses Placebo `.cfg` files, which `defaultconfigs/` does not seed.

The one exception now worth knowing: **Xaero's** server-side settings live in `<server dir>/config/xaero/`
(`world-map`, `minimap`), so a `!config/xaero/*` rule *would* let the pack ship enforced map profiles
if that is ever wanted. Those configs also register the status effects that block non-modded clients,
so shipping them has a real consequence - see the Xaero's pages before doing it.

Note the `.packwizignore` also excludes `*.json` globally, which would also exclude
`config/tectonic.json` even if `config/*` were relaxed. It needs an explicit `!` rule.

### 7.2 Installing on the server

**DOCUMENTED** - use the server side flag so client-only mods are skipped:

```
java -jar packwiz-installer-bootstrap.jar -g -s server <pack-url>
```

`-g` disables the optional-mods GUI, `-s server` downloads only server-side mods. Because every
`side = "client"` flag in this pack is already correct (section 1.1), this produces a correct server mod list
automatically.

---

## 8. Prioritised recommendations

Ordered by value / risk. **P0 items are the ones I'd do first.**

| # | Pri | Change | Where | Evidence |
| --- | --- | --- | --- | --- |
| 1 | **P0** | Set `Entity Despawn Delay` to `0`-`100` (from 600) | `config/apothic_spawners.cfg` -> `[general]` | VERIFIED source |
| 2 | **P0** | Decide `claims.forceload.offlineForceload` (true = farms run while owners are offline, costs TPS); set `maxPlayerClaimForceloads` to 25 | OPAC server config, `world/serverconfig/openpartiesandclaims-server.toml` | DOCUMENTED |
| 3 | **P0** | Leave `primaryPartySystem` at the built-in default (FTB Teams is gone; pointing it at `ftbteams` is a no-op) | OPAC server config | VERIFIED |
| 4 | **P0** | Fix SSRD/DH mismatch: ship DH by default, or mark SSRD optional with it | `mods/*.pw.toml` | VERIFIED + DOCUMENTED |
| 5 | **P0** | Whitelist Ars Nouveau (and Sable/Create) entities in EntityCulling | client config screen | DOCUMENTED |
| 6 | P1 | Raise `spreadFactor` for the expensive structure sets via `customSpreadFactors` (use `/dumpstructuresets`) | `config/sparsestructures.json5` | VERIFIED source |
| 7 | P1 | Cap SSRD via `/gamerule ssrdMaxRenderDistance` (default 128 chunks) | server command | DOCUMENTED |
| 8 | P1 | Pregenerate with `/dh pregen`, **not** Chunky, or disable DH while Chunky runs | server | DOCUMENTED |
| 9 | P1 | Raise `Boss Spawn Cooldown` above 3600 if invader load is heavy | `config/apotheosis/apotheosis.cfg` -> `[bosses]` | VERIFIED source |
| 10 | P1 | Establish a `/spark health` -> `/spark profiler` baseline before and after changes | server | DOCUMENTED |
| 11 | P1 | Un-ignore the specific configs you want shipped (or adopt `defaultconfigs/`) | `.packwizignore` | VERIFIED |
| 12 | P2 | Consider NeoForge 21.1.251 -> 21.1.252 | `pack.toml` | VERIFIED |
| 13 | P2 | Tell players the attack-range affix is inert (Apothic Combat) | player comms | DOCUMENTED |
| 14 | P2 | Decide on the 23 outdated pins (Terralith 2.6.2 is **new-world only**) | `mods/*.pw.toml` | VERIFIED |
| 15 | P2 | Leave `increased_height: false` in Tectonic; never add Embeddium/Radium/shaders | various | VERIFIED/DOCUMENTED |
| 16 | P2 | Set `levelKeyPrefix` if you ever run multiple servers behind a proxy | DH server config | DOCUMENTED |

---

## 9. Not verified / open questions

Listed so nobody mistakes absence of evidence for evidence of absence.

1. **Client-side performance options not yet reviewed in depth** - Distant Horizons' client quality/
   thread presets, ImmediatelyFast, Dynamic FPS, EMF/ETF, Fusion/Athena, Legendary Tooltips, Prism.
   These are very likely fine at defaults; DH's client quality preset is the one worth player guidance.
2. **Missing server-side performance mods not yet assessed** - ServerCore, Noisium, Clumps,
   Connectivity, Packet Fixer, ThreadTweak on NeoForge 1.21.1, and whether each overlaps with the
   already-installed Lithium/ModernFix/FerriteCore/AllTheLeaks. **Note Create's declared
   incompatibility with Radium and Palladium**, which removes two candidates. Do not add anything here
   without checking for overlap with Lithium and ModernFix first.
3. **Create / Sable / Aeronautics config surface** - not yet read from source. SSRD and the Sable
   gamerules in section 4.1 are the only Sable-family settings verified so far.
4. **FTB Backups 3** config keys (interval, retention, compression) - not yet verified. Relevant to
   disk/IO on the server.
5. **Waystones, GraveStone, Sophisticated Storage/Backpacks, Curios, Artifacts** config keys - not yet
   verified.
6. **JVM flags / heap sizing** for this pack size - not yet researched. Use `/spark health` GC data
   (section 3.5) to decide empirically rather than copying generic flags.
7. **`server.properties` / gamerule tuning** (view-distance vs simulation-distance, entity cramming,
   mobcaps, `network-compression-threshold` for large modded packets) - not yet verified.
8. **Exact `dungeons_arise` / `t_and_t` structure-set names** - use `/dumpstructuresets`.
9. **Lootr `randomise_seed` semantics** - the official wiki contradicts itself; test before changing.
10. **The 5 CurseForge-sourced mods** (FTB Backups 3, FTB Library, AllTheLeaks, Collapsible Groups,
    Twilight Forest) could not be version-checked by packwiz for currency without a CurseForge API key.
    The FTB Chunks swap plus the later FTB suite removal cut this blind spot from nine mods to five.

---

## Appendix A - Verified config file paths

| Mod | File | Format |
| --- | --- | --- |
| Tectonic | `config/tectonic.json` | JSON |
| Sparse Structures | `config/sparsestructures.json5` | JSON5 |
| Apotheosis (adventure) | `config/apotheosis/apotheosis.cfg` | Placebo CFG |
| Apothic Attributes | `config/apotheosis/apothic_attributes.cfg` | Placebo CFG |
| Apothic Spawners | `config/apothic_spawners.cfg` (config root - see note in section 3.2) | Placebo CFG |
| Apothic Enchanting | `config/apotheosis/apothic_enchanting.cfg` | Placebo CFG |
| Apotheosis name generation | `config/apotheosis/name_generation.cfg` | Placebo CFG |
| Open Parties and Claims | `world/serverconfig/openpartiesandclaims-server.toml` (main server config - inside the world save) plus `openpartiesandclaims-*` player configs alongside it | TOML |
| Xaero's World Map / Minimap | server-side: `config/xaero/world-map`, `config/xaero/minimap`; client map + waypoint data under the instance `xaero/` directory | TXT / binary |
| Lootr | `config/lootr-common.toml` | TOML |
| Distant Horizons | use `/dh config <key>` to print the path | TOML |

## Appendix B - Sources

- Modrinth API v2 (`/project/{id}`, `/version/{id}`, `/project/{id}/version?game_versions=["1.21.1"]`) - pack inventory, sides, incompatibilities, version currency.
- All 131 mod jars - `META-INF/neoforge.mods.toml` (dependencies, sides, declared incompatibilities).
- Apotheosis stack config source: `Shadows-of-Fire/Apotheosis@1.21`, `Apothic-Spawners@1.21`, `Apothic-Attributes@1.21`, `Apothic-Enchanting@1.21`, `Placebo@1.21`.
- Sparse Structures: `MaxenceDC/sparsestructures@1.21` (`Constants.java`, `sparse-structures-default-config.json5`).
- Tectonic: `Apollounknowndev/tectonic@v3` (`config/state/ConfigState.java`), Tectonic wiki `/wiki/Config`, official changelog for `config/tectonic.json`.
- NeoForge config docs: <https://docs.neoforged.net/docs/misc/config/>
- Distant Horizons server owners wiki: <https://gitlab.com/distant-horizons-team/distant-horizons/-/wikis/1-user-guide/1-frequently-asked-questions/5-server-owners/Server-Owners>
- OPAC README and Modrinth page (config locations, permission nodes, `primaryPartySystem`, `staticFakePlayers`, commands, beta status): <https://github.com/thexaero/open-parties-and-claims>, <https://modrinth.com/mod/open-parties-and-claims>
- OPAC default keys and `offlineForceload` semantics (issue quotes): <https://github.com/thexaero/open-parties-and-claims/issues/228>, <https://github.com/thexaero/open-parties-and-claims/issues/731>
- OPAC force-loading reliability reports: <https://github.com/thexaero/open-parties-and-claims/issues/855>, <https://github.com/thexaero/open-parties-and-claims/issues/927>
- Xaero's World Map / Minimap server-side config locations and modpack terms: <https://modrinth.com/mod/xaeros-world-map>, <https://modrinth.com/mod/xaeros-minimap>
- Lootr wiki: <https://github.com/LootrMinecraft/Lootr/wiki/Lootr-Configuration>
- spark docs: <https://spark.lucko.me/docs>
- Modrinth/CurseForge project pages and READMEs for Sable, Create Aeronautics, SSRD, Terralith, EntityCulling, Apothic Combat, FerriteCore, Lithium, Chunky.