230 lines
8.1 KiB
Markdown
230 lines
8.1 KiB
Markdown
# 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 |
|