From 0731304bec20bf20ca6dc8df1887f4dbd3b28f79 Mon Sep 17 00:00:00 2001 From: jester Date: Sun, 1 Mar 2026 19:48:20 +0000 Subject: [PATCH] docs: add Minecraft server file and directory reference for file browser implementation --- docs/reference/minecraft-file-reference.md | 229 +++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 docs/reference/minecraft-file-reference.md diff --git a/docs/reference/minecraft-file-reference.md b/docs/reference/minecraft-file-reference.md new file mode 100644 index 0000000..0a20496 --- /dev/null +++ b/docs/reference/minecraft-file-reference.md @@ -0,0 +1,229 @@ +# 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//` | Various | Per-plugin config folder, created on first run | +| `plugins//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/-N.log.gz` | Archived logs | Download for debugging | +| `crash-reports/.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//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 |