# Instance Specification: Forge 1.20.1 Survival Modpack

## 1. Overview & Compose Profile
* **Instance ID**: `forge-1.20.1-survival`
* **Container Name**: `mc_forge_server`
* **Minecraft Version**: `1.20.1`
* **Mod Loader**: Forge (`47.4.10`)
* **Java Runtime**: OpenJDK 17 (`itzg/minecraft-server:java17`)

> **JVM Flag Rule**: `-XX:+UnlockExperimentalVMOptions` must precede experimental flags in `JVM_OPTS` to avoid JVM start failure on OpenJDK 17.

### `docker-compose.yml` Reference

```yaml
services:
  mc:
    image: itzg/minecraft-server:java17
    container_name: mc_forge_server
    restart: unless-stopped
    ports:
      - "25565:25565"
      - "24454:24454/udp"
    environment:
      EULA: "TRUE"
      TYPE: "FORGE"
      VERSION: "1.20.1"
      MEMORY: "12G"

      # Server Properties Mapping
      VIEW_DISTANCE: "8"
      SIMULATION_DISTANCE: "6"
      NETWORK_COMPRESSION_THRESHOLD: "256"
      MAX_TICK_TIME: "120000"       # Prevents watchdog crashes during heavy worldgen
      PLAYER_IDLE_TIMEOUT: "0"      # Prevents auto-kicking AFK players
      ALLOW_FLIGHT: "TRUE"          # Prevents kicks when using Ad Astra rockets/ships
      SYNC_CHUNK_WRITES: "FALSE"
      ENABLE_STATUS: "TRUE"
      MOTD: "MC SotoHome!"
      MAX_PLAYERS: "15"
      DIFFICULTY: "hard"
      ONLINE_MODE: "FALSE"

      # JVM Garbage Collection & Network Flags
      JVM_OPTS: >-
        -Dfml.readTimeout=180
        -Dfml.loginTimeout=180
        -XX:+UnlockExperimentalVMOptions
        -XX:+UseG1GC
        -XX:MaxGCPauseMillis=50
        -XX:G1HeapRegionSize=8M
        -XX:G1ReservePercent=15
        -XX:InitiatingHeapOccupancyPercent=45
        -XX:G1MixedGCCountTarget=4
        -XX:G1HeapWastePercent=5
        -XX:G1NewSizePercent=30
        -XX:G1MaxNewSizePercent=40
        -XX:SurvivorRatio=8
        -XX:MaxTenuringThreshold=1
        -XX:+DisableExplicitGC
        -XX:+AlwaysPreTouch
    volumes:
      - ./data:/data
```

---

## 2. Server Mod Manifest (60 Mods)

```text
[forge]ctov-3.4.14.jar
ad_astra-forge-1.20.1-1.15.20.jar
ad_astra_extra_additions-1.20.1-1.1.1.jar
ad_astra_more_structures-1.0.1-forge.jar
alexsmobs-1.22.9.jar
architectury-9.2.14-forge.jar
bettercombat-forge-1.9.0+1.20.1.jar
Botania-1.20.1-454-FORGE.jar
botarium-forge-1.20.1-2.3.4.jar
citadel-2.6.3-1.20.1.jar
cloth-config-11.1.136-forge.jar
Clumps-forge-1.20.1-12.0.0.4.jar
corpse-forge-1.20.1-1.0.23.jar
create-1.20.1-6.0.8.jar
create_ad_astra_recipes-1.0.0-forge-1.20.1.jar
createaddition-1.20.1-1.3.3.jar
curios-forge-5.14.1+1.20.1.jar
decocraft-3.0.4-1.20.1-slim.jar
DistantHorizons-3.2.0-b-1.20.1-fabric-forge.jar
FarmersDelight-1.20.1-1.3.2.jar
ferritecore-6.0.1-forge.jar
flan-1.20.1-1.11.16-forge.jar
geckolib-forge-1.20.1-4.8.4.jar
ImmersiveEngineering-1.20.1-10.2.0-183.jar
improvedmobs-1.20.1-1.13.7-forge.jar
irons_lib-1.20.1-2.1.0.jar
irons_spellbooks-1.20.1-3.16.2.jar
Jade-1.20.1-Forge-11.13.3.jar
jei-1.20.1-forge-15.48.0.180.jar
journeymap-forge-1.20.1-6.0.0.jar
Krypton_Reno-forge-1.20.1-26.1.1-1.20.1.jar
lithostitched-forge-1.20.1-1.4.11.jar
locks_reforged-1.6.1.jar
lts_auth-1.0.1+mc1.20.1.jar
LuckPerms-Forge-5.4.102.jar
majrusz-library-forge-1.20.1-7.0.8.jar
majruszs-difficulty-forge-1.20.1-1.9.10.jar
mcda-5.0.2.jar
mcdw-9.0.4.jar
minecraft-comes-alive-7.6.28-beta.10+1.20.1-universal.jar
modernfix-forge-5.27.66+mc1.20.1.jar
Nullscape_1.20.x_v1.2.8.jar
Patchouli-1.20.1-85-FORGE.jar
perspatium-1.20.1-1.2.0.jar
planets+-bv1.7.5-1.20x.jar
player-animation-lib-forge-1.0.2-rc1+1.20.jar
resourcefulconfig-forge-1.20.1-2.1.3.jar
resourcefullib-forge-1.20.1-2.1.29.jar
SimpleBackups-1.20.1-3.1.24.jar
sophisticatedbackpacks-1.20.1-3.24.63.2049.jar
sophisticatedcore-1.20.1-1.3.75.2231.jar
spark-1.10.53-forge.jar
tectonic-3.0.17-forge-1.20.1.jar
tenshilib-1.20.1-1.7.6-forge.jar
Terralith_1.20.x_v2.5.4.jar
voicechat-forge-1.20.1-2.6.22.jar
YungsApi-1.20-Forge-4.0.6.jar
YungsBetterDungeons-1.20-Forge-4.0.4.jar
YungsBetterMineshafts-1.20-Forge-4.0.4.jar
YungsBetterStrongholds-1.20-Forge-4.0.3.jar
```

---

## 3. Client Mod Manifest (50 Mods)

This list contains all client-side required mods, including client performance engines (`Embeddium`, `Oculus`, `Rubidium Extra`) and server expansion dependencies:

```text
ad_astra-forge-1.20.1-1.15.20.jar
ad_astra_extra_additions-1.20.1-1.1.1.jar
ad_astra_more_structures-1.0.1-forge.jar
alexsmobs-1.22.9.jar
architectury-9.2.14-forge.jar
bettercombat-forge-1.9.0+1.20.1.jar
BetterPingDisplay-1.20.1-1.1.jar
Botania-1.20.1-454-FORGE.jar
botarium-forge-1.20.1-2.3.4.jar
citadel-2.6.3-1.20.1.jar
cloth-config-11.1.136-forge.jar
Clumps-forge-1.20.1-12.0.0.4.jar
corpse-forge-1.20.1-1.0.23.jar
create-1.20.1-6.0.8.jar
create_ad_astra_recipes-1.0.0-forge-1.20.1.jar
createaddition-1.20.1-1.3.3.jar
curios-forge-5.14.1+1.20.1.jar
decocraft-3.0.4-1.20.1-slim.jar
DistantHorizons-3.2.0-b-1.20.1-fabric-forge.jar
embeddium-0.3.31+mc1.20.1.jar
FarmersDelight-1.20.1-1.3.2.jar
ferritecore-6.0.1-forge.jar
geckolib-forge-1.20.1-4.8.4.jar
ImmersiveEngineering-1.20.1-10.2.0-183.jar
irons_lib-1.20.1-2.1.0.jar
irons_spellbooks-1.20.1-3.16.2.jar
Jade-1.20.1-Forge-11.13.3.jar
jei-1.20.1-forge-15.48.0.180.jar
journeymap-forge-1.20.1-6.0.0.jar
Krypton_Reno-forge-1.20.1-26.1.1-1.20.1.jar
locks_reforged-1.6.1.jar
majrusz-library-forge-1.20.1-7.0.8.jar
majruszs-difficulty-forge-1.20.1-1.9.10.jar
mcda-5.0.2.jar
mcdw-9.0.4.jar
minecraft-comes-alive-7.6.28-beta.10+1.20.1-universal.jar
modernfix-forge-5.27.66+mc1.20.1.jar
oculus-mc1.20.1-1.8.0.jar
Patchouli-1.20.1-85-FORGE.jar
perspatium-1.20.1-1.2.0.jar
planets+-bv1.7.5-1.20x.jar
player-animation-lib-forge-1.0.2-rc1+1.20.jar
resourcefulconfig-forge-1.20.1-2.1.3.jar
resourcefullib-forge-1.20.1-2.1.29.jar
rubidium-extra-0.5.4.4+mc1.20.1-build.131.jar
sophisticatedbackpacks-1.20.1-3.24.63.2049.jar
sophisticatedcore-1.20.1-1.3.75.2231.jar
tenshilib-1.20.1-1.7.6-forge.jar
TUTORIAL_DISABLE-1.0.0.jar
voicechat-forge-1.20.1-2.6.22.jar
```

---

## 4. Instance Management & Mod RCON Commands

### Distant Horizons Chunk & LOD Pre-Generation
With `distantGeneratorMode = "FULL"` enabled in `DistantHorizons.toml`, DH generates both standard terrain chunks and Level of Detail (LOD) visual data simultaneously:

```bash
# Start pre-generation (250 chunks radius = 4,000 blocks around 0,0)
docker exec -i mc_forge_server rcon-cli "dh pregen start overworld 0 0 250"

# Check status
docker exec -i mc_forge_server rcon-cli "dh pregen status"

# Stop pre-generation
docker exec -i mc_forge_server rcon-cli "dh pregen stop"
```

### Claim Management (FLAN)
```bash
docker exec -i mc_forge_server rcon-cli "flan reload"
```

### Performance Profiling (spark)
```bash
docker exec -i mc_forge_server rcon-cli "spark profiler --timeout 30"
docker exec -i mc_forge_server rcon-cli "spark healthreport"
```