# Minecraft Server — Known File & Directory Reference

**Purpose:** Reference for file browser implementation. Covers all supported ZLH variants.
**Scope:** Files and directories users most commonly need to view, edit, upload, or delete.

---

## Universal (All Variants)

These exist on every Minecraft server regardless of loader.

### Root-Level Files

| File | Format | Why Users Touch It |
|------|--------|-------------------|
| `server.properties` | Key=value | Primary server config — gamemode, difficulty, max players, view distance, PvP, whitelist, MOTD, port, online-mode, seed |
| `ops.json` | JSON | Operator (admin) list |
| `whitelist.json` | JSON | Allowlisted players |
| `banned-players.json` | JSON | Banned player list |
| `banned-ips.json` | JSON | Banned IP list |
| `usercache.json` | JSON | UUID ↔ username cache (rarely edited manually) |
| `eula.txt` | Plain text | Must be accepted on first run |

### Root-Level Directories

| Directory | Why Users Touch It |
|-----------|-------------------|
| `world/` | Primary world — **never touched by file browser automation** |
| `world_nether/` | Nether dimension (Vanilla layout) |
| `world_the_end/` | End dimension (Vanilla layout) |
| `logs/` | Server logs — users download for debugging |
| `crash-reports/` | Crash dumps — users download when server won't start |

---

## Mod Loaders (Forge / NeoForge / Fabric / Quilt)

### Directories

| Directory | Format | Why Users Touch It |
|-----------|--------|-------------------|
| `mods/` | `.jar` files | Add, remove, enable, disable mods — primary user action |
| `mods-removed/` | `.jar` files | ZLH soft-delete location — restore from here |
| `config/` | `.toml`, `.json`, `.cfg`, `.yml` | Per-mod configuration — most commonly edited after mods dir |
| `defaultconfigs/` | Various | Default configs applied on new world creation (Forge/NeoForge) |
| `kubejs/` | `.js` files | KubeJS scripting (popular modpack customization tool) |
| `scripts/` | Various | CraftTweaker and similar scripting mods |
| `resourcepacks/` | `.zip` files | Server-side resource packs |
| `datapacks/` | `.zip` or folder | Data-driven game modifications |

### Config File Formats (inside `config/`)

| Format | Extension | Notes |
|--------|-----------|-------|
| TOML | `.toml` | Most common for NeoForge/Forge 1.18+ mods |
| JSON | `.json` | Common for Fabric mods and some Forge mods |
| CFG | `.cfg` | Older Forge mod format (1.12 era, still seen) |
| YAML | `.yml` | Less common, some mods use it |
| Plain text | `.txt`, `.conf` | Rare, older mods |

### NeoForge / Forge Specific

| File/Dir | Why Users Touch It |
|----------|--------------------|
| `config/forge-server.toml` | Forge server settings |
| `config/neoforge-server.toml` | NeoForge server settings |
| `config/fml.toml` | FML (Forge Mod Loader) settings |
| `libraries/` | Loader libraries — do not touch |
| `mods/dev/` | ZLH dev-promoted mods channel |
| `mods/curated/` | ZLH Modrinth-installed mods channel |

### Fabric / Quilt Specific

| File/Dir | Why Users Touch It |
|----------|--------------------|
| `fabric-server-launch.jar` | Loader binary — do not touch |
| `fabric-server.properties` | Fabric-specific settings (rare) |
| `config/fabric/` | Fabric mod configs |

---

## Plugin Servers (Paper / Purpur / Spigot / Bukkit)

### Directories

| Directory | Format | Why Users Touch It |
|-----------|--------|-------------------|
| `plugins/` | `.jar` files | Add, remove plugins — equivalent of mods/ for this stack |
| `plugins/<PluginName>/` | Various | Per-plugin config folder, created on first run |
| `plugins/<PluginName>/config.yml` | YAML | Primary config for most plugins |

### Paper-Specific Config Files

| File | Why Users Touch It |
|------|--------------------|
| `bukkit.yml` | Bukkit base config — spawn limits, chunk GC, aliases |
| `spigot.yml` | Spigot config — mob spawning, merge radius, tick limiters |
| `config/paper-global.yml` | Paper global settings (1.19+) |
| `config/paper-world-defaults.yml` | Paper per-world defaults |
| `config/paper-world/` | Per-world Paper overrides |
| `pufferfish.yml` | Pufferfish-specific optimizations |
| `purpur.yml` | Purpur-specific gameplay customizations |

### Common Plugin Config Files (by plugin name)

These are the most widely deployed plugins — their configs are commonly edited:

| Plugin | Config Location |
|--------|----------------|
| EssentialsX | `plugins/Essentials/config.yml` |
| LuckPerms | `plugins/LuckPerms/config.yml` |
| Vault | `plugins/Vault/config.yml` |
| WorldEdit | `plugins/WorldEdit/config.yml` |
| WorldGuard | `plugins/WorldGuard/config.yml` |
| CoreProtect | `plugins/CoreProtect/config.yml` |
| Dynmap | `plugins/dynmap/configuration.txt` |
| Multiverse-Core | `plugins/Multiverse-Core/config.yml` |

---

## World Directory Structure

> **ZLH Note:** World data is excluded from all automation. Never touched by the agent, mod deployment safety, or file browser delete operations.

### Vanilla / Forge / Fabric Layout

```
world/
  level.dat          ← World metadata, seed, game rules
  level.dat_old      ← Backup of level.dat
  session.lock       ← Prevents concurrent access
  playerdata/        ← Per-player .dat files
  stats/             ← Player statistics JSON
  advancements/      ← Player advancement data
  data/              ← Scoreboard, structure data, maps
  region/            ← Overworld chunk data (.mca files)
  entities/          ← Entity chunk data (1.17+)
  poi/               ← Point-of-interest data

world_nether/
  DIM-1/
    region/

world_the_end/
  DIM1/
    region/
```

### Paper Layout (different from Vanilla)

```
world/
  region/            ← Overworld chunks

world/DIM-1/
  region/            ← Nether chunks (stored inside world/)

world/DIM1/
  region/            ← End chunks (stored inside world/)
```

> This layout difference is why migrating between Paper and Vanilla requires manual steps.

---

## Logs & Diagnostics

| File/Dir | Contents | User Action |
|----------|----------|-------------|
| `logs/latest.log` | Current session log | Download for support |
| `logs/<date>-N.log.gz` | Archived logs | Download for debugging |
| `crash-reports/<timestamp>.txt` | JVM crash report | Download when server won't start |
| `debug/` | Verbose debug output (Paper) | Rarely needed |
| `lifecycle.log` | ZLH agent lifecycle/probe log | ZLH-specific diagnostic |

---

## File Types Summary (for browser rendering decisions)

| Extension | Editable in Browser | Notes |
|-----------|--------------------|----|
| `.properties` | ✅ Yes | `server.properties` |
| `.yml` / `.yaml` | ✅ Yes | Plugin configs |
| `.toml` | ✅ Yes | NeoForge/Forge mod configs |
| `.json` | ✅ Yes | Ops, whitelist, some mod configs |
| `.cfg` | ✅ Yes | Older Forge configs |
| `.txt` | ✅ Yes | EULA, some configs |
| `.js` | ✅ Yes | KubeJS scripts |
| `.log` | ✅ Read-only | Logs |
| `.jar` | ❌ No — download only | Mods, plugins |
| `.gz` | ❌ No — download only | Archived logs |
| `.mca` | ❌ No — download only | Chunk data |
| `.dat` | ❌ No — download only | Binary world data |
| `.zip` | ❌ No — download only | Resource/datapacks |

---

## Priority Surfaces for File Browser (by user need)

**High — most users will need these:**
1. `server.properties` — edit directly
2. `mods/` — view, enable/disable, delete, upload
3. `mods-removed/` — restore deleted mods
4. `config/` — edit mod configs
5. `logs/latest.log` — download for support
6. `crash-reports/` — download when broken

**Medium — modpack/advanced users:**
7. `plugins/` (plugin servers)
8. `plugins/<Name>/config.yml`
9. `bukkit.yml`, `spigot.yml`, `paper-global.yml`
10. `kubejs/`, `scripts/` (heavily modded servers)

**Low — rarely needed:**
11. `ops.json`, `whitelist.json`, `banned-*.json`
12. `defaultconfigs/`
13. `resourcepacks/`, `datapacks/`

---

## ZLH-Specific Paths

| Path | Purpose |
|------|---------|
| `mods/curated/` | Modrinth-installed mods |
| `mods/dev/` | Dev-container promoted mods |
| `mods-removed/` | Soft-deleted mods (restore via file browser) |
| `.zlh_snapshots/` | Deployment safety snapshots — do not expose in browser |
| `lifecycle.log` | Agent probe/lifecycle diagnostics |