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.