jester/zlh-grind
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
0731304bec
zlh-grind/docs/reference/minecraft-file-reference.md

8.1 KiB
Raw Blame History

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