From 2c8a9de41c0eac4c457d4c7a209d31ebe004df5e Mon Sep 17 00:00:00 2001 From: jester Date: Sun, 1 Mar 2026 19:50:51 +0000 Subject: [PATCH] docs: add Minecraft known file locations reference for file browser implementation --- docs/reference/minecraft-file-locations.md | 251 +++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 docs/reference/minecraft-file-locations.md diff --git a/docs/reference/minecraft-file-locations.md b/docs/reference/minecraft-file-locations.md new file mode 100644 index 0000000..9d49b91 --- /dev/null +++ b/docs/reference/minecraft-file-locations.md @@ -0,0 +1,251 @@ +# 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.