zlh-grind/docs/reference/minecraft-file-locations.md

# Minecraft Server — Known Files, Directories & Change Locations

**Purpose:** Reference for file browser implementation. Defines what files users commonly access, edit, or upload across all supported Minecraft server variants.

---

## Universal (All Variants)

These exist regardless of loader or server software.

| Path | Type | Notes |
|------|------|-------|
| `server.properties` | Text / Key-Value | Most commonly edited file on any server. Gamemode, difficulty, max players, MOTD, ports, whitelist, PvP, view distance, seed. Requires restart to apply. |
| `server.jar` | Binary | The server executable. Never directly edited by users but occasionally replaced during upgrades. |
| `eula.txt` | Text | Must be accepted on first run. |
| `logs/latest.log` | Text | Current session log. Frequently downloaded for debugging. Read-only in most cases. |
| `logs/` | Directory | Archived logs (`.log.gz`). Download only. |
| `world/` | Directory | Overworld data. Never touched by file browser — excluded from safety scope. |
| `world_nether/` | Directory | Nether dimension (Vanilla layout). Excluded. |
| `world_the_end/` | Directory | End dimension (Vanilla layout). Excluded. |
| `banned-players.json` | JSON | Banned player list. Occasionally edited directly. |
| `banned-ips.json` | JSON | Banned IP list. Occasionally edited directly. |
| `whitelist.json` | JSON | Whitelist entries. Edited when allow-list=true. |
| `ops.json` | JSON | Operator list. Edited to grant/revoke op. |
| `usercache.json` | JSON | UUID to username cache. Read-only in practice. |

---

## Vanilla

Minimal file surface. No mods, no plugins.

```
server.properties
eula.txt
server.jar
logs/
world/
world_nether/
world_the_end/
```

No `mods/` or `plugins/` directory. Config changes are limited to `server.properties` and the JSON admin files above.

---

## Paper / Spigot / Purpur (Plugin-based)

### Additional Config Files

| Path | Type | Notes |
|------|------|-------|
| `bukkit.yml` | YAML | Core Bukkit settings (spawn limits, chunk GC, aliases). |
| `spigot.yml` | YAML | Spigot-specific tuning (mob spawn ranges, tick rates, bungeecord). |
| `config/paper-global.yml` | YAML | Paper global settings (added ~1.19+). |
| `config/paper-world-defaults.yml` | YAML | Paper world-level defaults. |
| `config/paper-world/` | Directory | Per-world Paper overrides. |
| `purpur.yml` | YAML | Purpur-specific options (only on Purpur). |
| `help.yml` | YAML | Custom help command entries. |
| `commands.yml` | YAML | Command aliases and overrides. |
| `permissions.yml` | YAML | Basic permission definitions (rarely used with permission plugins). |

### World Storage Layout (Paper differs from Vanilla)

Paper stores nether and end inside the main world folder:

```
world/
  region/         ← Overworld chunks
  DIM-1/          ← Nether
  DIM1/           ← End
  playerdata/
  stats/
  advancements/
  data/
```

Vanilla stores them as siblings:
```
world/
world_nether/
world_the_end/
```

**This matters for file browser display** — do not assume a flat sibling layout.

### Plugins Directory

```
plugins/
  PluginName.jar              ← Plugin binary
  PluginName/
    config.yml                ← Primary plugin config
    messages.yml              ← Usually messages/lang
    data.yml                  ← Persistent data (do not edit while running)
```

Common plugin configs users edit:
- `plugins/EssentialsX/config.yml`
- `plugins/LuckPerms/config.yml`
- `plugins/WorldGuard/config.yml`
- `plugins/Vault/config.yml`

Plugin configs are almost always `.yml`. Restart or `/reload` required to apply.

---

## Forge / NeoForge (Mod-based)

### Mods Directory

```
mods/
  modname-1.0.0.jar           ← Active mod
  modname-1.0.0.jar.disabled  ← Disabled mod (ZLH convention)
mods-removed/
  modname-1.0.0.jar           ← Soft deleted mod (ZLH convention)
```

### Config Directory

Most mod configs live in `config/`. Two common formats:

| Format | Extension | Notes |
|--------|-----------|-------|
| TOML | `.toml` | Standard for modern Forge/NeoForge mods |
| JSON | `.json` | Less common, some older mods |
| Properties | `.properties` | Rare, legacy mods |

```
config/
  modname-common.toml         ← Shared client+server config
  modname-server.toml         ← Server-only config
  modname/
    config.toml               ← Some mods use a subfolder
```

Some mods also create a top-level directory:

```
modname/
  config.toml
```

### Additional Forge/NeoForge Files

| Path | Type | Notes |
|------|------|-------|
| `user_jvm_args.txt` | Text | JVM arguments for the server. Edit with care. |
| `libraries/` | Directory | Forge/NeoForge runtime libs. Never user-edited. |
| `kubejs/` | Directory | KubeJS script mod directory. Heavily edited on modpack servers. |
| `kubejs/server_scripts/` | Directory | Server-side KubeJS scripts (`.js`). Very commonly edited. |
| `kubejs/startup_scripts/` | Directory | Startup scripts. |
| `defaultconfigs/` | Directory | Default configs applied to new worlds. |
| `global_packs/` | Directory | Global data/resource packs. |
| `packs/` | Directory | Per-world data and resource packs. |

---

## Fabric / Quilt (Mod-based)

Same `mods/` and `config/` structure as Forge/NeoForge. Config formats vary by mod but `.json` is more common in the Fabric ecosystem than `.toml`.

```
mods/
  fabric-api-*.jar
  modname.jar
config/
  modname.json
  modname/
    config.json
```

### Fabric-specific Files

| Path | Type | Notes |
|------|------|-------|
| `fabric-server-launch.jar` | Binary | Fabric launch wrapper. Not user-edited. |
| `fabric_loader_libraries/` | Directory | Internal. Not user-edited. |

---

## Frequently Edited — Priority List for File Browser

These are the files users will navigate to most often, across all variants. The file browser should make these discoverable:

**Tier 1 — Edited constantly**
- `server.properties`
- `config/*.toml` (Forge/NeoForge)
- `plugins/PluginName/config.yml` (Paper/Spigot)
- `kubejs/server_scripts/` (modpack servers)
- `mods/` (install, enable, disable, remove)

**Tier 2 — Edited occasionally**
- `bukkit.yml`
- `spigot.yml`
- `config/paper-global.yml`
- `config/paper-world-defaults.yml`
- `ops.json`
- `whitelist.json`
- `banned-players.json`
- `purpur.yml`

**Tier 3 — Downloaded, rarely edited**
- `logs/latest.log`
- `logs/*.log.gz`
- `usercache.json`

**Never expose in file browser**
- `world/` and dimension subdirectories (backup system handles this)
- `libraries/` (Forge/NeoForge runtime, read-only)
- `fabric_loader_libraries/`
- Any `.lock` files

---

## Config File Formats by Loader

| Loader | Primary Format | Secondary |
|--------|---------------|-----------|
| Vanilla | `.properties` | `.json` |
| Paper / Spigot / Purpur | `.yml` | `.json` |
| Forge | `.toml` | `.json`, `.properties` |
| NeoForge | `.toml` | `.json` |
| Fabric | `.json` | `.toml` |
| Quilt | `.json` | `.toml` |

**Implication for in-browser editor:** syntax highlighting or at minimum format-aware display should handle `.toml`, `.yml`, `.json`, and `.properties`.

---

## ZLH-Specific Paths

These are ZLH conventions, not Minecraft defaults.

| Path | Notes |
|------|-------|
| `mods/` | Active mods (`.jar` and `.jar.disabled`) |
| `mods-removed/` | Soft-deleted mods. Restore via file browser. |
| `.zlh_snapshots/` | Deployment safety snapshots. Hidden, not shown in file browser. |

---

## Notes for Implementation

- **Paper world layout differs from Vanilla.** Do not assume nether/end are sibling directories. Detect by loader type from agent metadata.
- **Plugin configs are always inside `plugins/PluginName/`** — the plugin `.jar` and its config folder share the same name.
- **Mod configs can be in `config/` or a top-level named directory** — no single rule covers all mods.
- **`.toml` files need TOML-aware editing** — malformed TOML will break mod config loading silently or with cryptic errors.
- **KubeJS** is worth treating as a first-class surface. Modpack servers using KubeJS will have users editing scripts frequently.
- **`server.properties`** should have a structured editor (key-value form), not just raw text, for non-technical users.