# SERVER MASTER GUIDE — SCICRAFT: The Dark Photon Protocol

**NeoForge 1.21.1 (21.1.248) · packwiz v1.1.0 · version 1.0.0**

---

## 1. The Dark Photon Protocol (Lore)

> In the year 4.2.2.0.5, the universe is burning. The Time Lords sealed a
> collapsing star-empire inside a **Dimensional Door** — but the seal is
> decaying. The **Void Dimension** leaks entropy into the Overworld, and the
> **Deeper and Darker** have begun to answer.
>
> A single broadcast survives the fall: the **Dark Photon Protocol**, a plan
> to stabilize the galaxy by re-binding reality itself. You are the last
> engineer of the Second Renegade Flight. Construct the means, master the
> sciences of **Mekanism, Applied Energistics and Create**, and re-forge the
> photon lattice before the void consumes every world.

### Objective trees (what the pack asks you to build)
1. **Reignite the Ark** — build a base with power (Mekanism turbines /
   Flux Networks), storage (AE2 / Sophisticated / Functional Storage),
   and logistics (LaserIO / Modular Routers / Entangled / FastPipes).
2. **Walk the Stars** — unlock **Stellaris** rocket tiers; visit Mars,
   Venus, and beyond through the rocket menu.
3. **Breach the Doors** — survive **Dimensional Doors**, recover the
   **Void Dimension** stabilizer, and descend into the **Deeper and Darker**.
4. **The Protocol** — complete the FTB Quests line and KubeJS advancements.

---

## 2. Packs & Directories

| Path | Contents |
|------|----------|
| `./server_pack/`  | Server-only modpack (137 mod files). No shaders, no client render mods. |
| `./client_pack/`  | Full client pack (146 mod files). Adds Iris + Sodium (native NeoForge), Cull Leaves, LambDynamicLights, Dynamic FPS, 3D Skin Layers, Visuality, flywheel compat. |

### Key client-only mods (server must NOT have these)
`iris`, `sodium`, `iris-flw-compat`, `cull-leaves`, `lambdynamiclights`,
`dynamic-fps`, `3dskinlayers`, `visuality-forge`, `midnightlib`.

### Bridge layer (both packs)
Sinytra Connector + Forgified Fabric API run a small set of Fabric mods
(Immersive Portals, LambDynamicLights, Waystones-compat). Do not remove
either; the pack will not boot without them.

---

## 3. Install & Update

### Prereqs
- Java 21 (Adoptium Temurin 21 LTS recommended)
- ~12 GB RAM free for client, 8 GB minimum for server
- Disk: keep under **100 GB** total for world + packs

### First-time server setup
```bash
# from this repo root
packwiz install --dir server_pack            # downloads all mods into server_pack/
java -Xms2G -Xmx6G -jar server_pack/neoforge-21.1.248-installer.jar --installServer
# accept EULA, then launch:
java -Xms2G -Xmx6G -XX:+UseG1GC -jar server_pack/neoforge-21.1.248-server.jar nogui
```

### Adding a mod (both packs)
```bash
packwiz --dir server_pack  curseforge add --addon-id <CF_ID> -y
packwiz --dir client_pack  curseforge add --addon-id <CF_ID> -y
packwiz --dir server_pack  modrinth add <MR_SLUG_OR_ID> -y
packwiz --dir client_pack  modrinth add <MR_SLUG_OR_ID> -y
packwiz --dir server_pack  refresh
packwiz --dir client_pack  refresh
```
- Always add to **both** packs unless the mod is client- or server-only.
- For Fabric mods that must run through Sinytra, use
  `packwiz url add "<Name>" "<URL>" --force` and verify the Sinytra
  connector tolerates the version.

---

## 4. Server Properties (view-distance=8, simulation-distance=6)

`server_pack/server.properties` — set these values:

```properties
view-distance=8
simulation-distance=6
max-players=8
motd=SCICRAFT - The Dark Photon Protocol
difficulty=hard
spawn-protection=0
network-compression-threshold=256
enable-command-block=true
online-mode=true
```

`server_pack/eula.txt` → `eula=true` (after review).

---

## 5. Recommended JVM Flags (server)

```bash
java -Xms4G -Xmx8G \
  -XX:+UseG1GC \
  -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 \
  -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC \
  -XX:+AlwaysPreTouch \
  -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M \
  -XX:G1ReservePercent=20 \
  -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 \
  -XX:G1RSetUpdatingPauseTimePercent=5 \
  -Dlog4j2.formatMsgNoLookups=true \
  -jar neoforge-21.1.248-server.jar nogui
```

Notes:
- G1 tuning keeps large-tech-server TPS stable under chunk gen (Krypton
  Reno + BadOptimizations help server-side).
- `-Xms4G` avoids early GC churn. Cap at 8G; this pack is RAM-hungry
  from AE2/Mekanism tick load but does not need 16G.

---

## 6. Shader Tuning for 4GB VRAM (client)

Shader loader is **Iris** (native NeoForge). Recommended shaderpack:
**Complementary Reimagined r5.4** (`client_pack/shaderpacks/`, see README).

Preset for 4GB VRAM:
- Preset: **Fast / Performance**
- Render Distance: **8** (server view-distance)
- Antialiasing: **OFF**
- SSAO: **Fast**, Shadow Quality **1.0x** (0.5x if <30 FPS)
- Shadow Distance: **64**
- Bloom: **OFF/Low**, Clouds: **2D Fast**
- Water Reflections: **Screenspace Fast**
- Colored Light / Block Light: **OFF**

If still under 60 FPS: reduce Shadow Quality to 0.5x, then disable Bloom,
before touching render distance.

---

## 7. Mod Feature Hotspots (Quick Orientation)

| Domain | Mods | Notes |
|--------|------|-------|
| Power | Mekanism (turbine/boiler), Flux Networks | Flux wireless transfer; Mekanism cables for bulk |
| Storage | AE2, Sophisticated Storage, Functional Storage, Sophisticated Backpacks | AE2 for autocraft; Sophisticated for bulk; Functional for drawers |
| Logistics | LaserIO, Modular Routers, Entangled, FastPipes, Create belts | FastPipes adds vanilla pipe QoL |
| Automation | Create + Steam 'n' Rails + Rechiseled + FastPipes | Flywheel + Iris compat bundled |
| Tech Building | Building Gadgets, Hologenica, FramedBlocks, Chipped, Supplementaries | |
| Dimensions | Per Spatium/Stellaris, Dimensional Doors, Void Dimension, Deeper and Darker | Stellaris portal → rockets; Doors are the endgame hook |
| Mobs/Combat | Born in Chaos, Mutant Monsters, Nyf's Spiders, Better Combat, Simply Swords | Hard difficulty |
| UI/QoL | JEI, Jade (+Addons), JourneyMap, Waystones, AppleSkin, IPN, Clumps, Mouse Tweaks | JEI is the recipe source (no EMI) |
| Scripting | KubeJS (+Create, +Mekanism), LootJS, Blocks You Need | Advancements & loot live here |
| Server utils | FTB Chunks/Quests/Teams/Library | Chunk claims + questbook |

---

## 8. Story System (KubeJS + datapack)

Lore is code. All story text lives in the **story bible** and is referenced
from scripts — never hardcoded. See `STORY_CANON.md` for the full
canon, file map, and "add a beat in 5 minutes" workflow.

### File layout (mirrored in BOTH packs under `kubejs/`)
```
kubejs/
├── startup_scripts/registry_blocks.js   # photon_core, photon_fragment,
│                                         #   void_stabilizer, quantum_lattice, renegade_glass
├── server_scripts/
│   ├── 00_lore.js                       # THE STORY BIBLE (edit here first)
│   ├── 01_corruption_tide.js            # global Corruption Tide + Lattice re-seal
│   ├── 02_events.js                     # photon buffs, void/darker hazards
│   ├── 03_recipes_tags.js               # crafting chain + ore/ingot tag unification
│   └── 04_loot.js                       # LootJS: Darker bosses drop Photon Fragments
├── client_scripts/
│   ├── 01_tooltips.js                   # hover lore on Protocol items
│   └── 02_jei_info.js                   # JEI "how to obtain" pages
├── data/scicraft/advancements/protocol/*.json   # 9-node phase tree (non-terminal)
└── assets/scicraft/                     # lang, textures
```

### The phase tree (not a finale — the Protocol is maintained)
1. `root` — The Dark Photon Protocol (on login)
2. `first_signal` — recover a Photon Fragment
3. `the_core` — press 3 fragments → Photon Core
4. `the_seal` — craft the Void Stabilizer
5. `the_lattice` — assemble the Quantum Lattice
6. `the_legacy` — craft Renegade Glass
7. `through_the_doors` — enter Dimensional Doors Limbo
8. `the_wound` / `the_answer` / `per_spatium` — Void, Deeper&Darker, Stellaris

### Global Corruption Tide
- Rises +1 every 60s while Doors stay unsealed (global, all players share).
- Right-click a **Quantum Lattice** with a **Void Stabilizer** to re-seal
  a Door: −15 tide.
- ≥30 tide: players get `darkness`. ≥60: `darker_threshold` for future
  spawn ramps. 100 = maximum dark. No fail state — soft escalation only.

### Reload rules
- Server scripts / recipes / advancements: `/reload`
- Client tooltips / JEI / textures / lang: `F3+T`
- New items/blocks (`registry_blocks.js`): **full restart**

### Keep both packs in sync
```bash
rm -rf client_pack/kubejs && cp -r server_pack/kubejs client_pack/kubejs
```

---

## 9. Operations & Troubleshooting

### Server start order
1. `packwiz install --dir server_pack` (first time / after changes)
2. Accept EULA.
3. Launch with the JVM flags above.

### Common failures
| Symptom | Fix |
|---------|-----|
| "Mismatched mods" on client join | Run `packwiz refresh` both packs, redeploy. |
| Sinytra connector errors | Update Sinytra Connector + Forgified Fabric API together. |
| Iris black screen | Disable flywheel compat first, then test without shaders. |
| Crash on world gen (Deeper and Darker) | Ensure CF 659011 + its lithostitched data load; update both. |
| TPS lag from many AE2 cells | Check FTB chunk claims; lower `simulation-distance`. |
| Immersive Portals won't load | Must be the Fabric jar added via `url add --force` (Modrinth blocks loader mismatch). |

### Backups
- World: copy `server_pack/world/` (or use FTB Chunks backups).
- Configs: `server_pack/config/` mirrors client defaults; keep both in sync
  when changing KubeJS scripts or FTB settings.

---

*Generated for SciCraft Server · packwiz refresh passing on both packs · 146 client / 137 server files.*