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

8.0 KiB
Raw Blame History

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.