Mustard Server Management

This document describes the established high-level workflow for maintaining the Mustard testing server. It intentionally omits unverified deployment automation and command sequences.

Document Scope

This document covers:

Detailed source maintenance belongs in minecraft-projects. Pterodactyl environment and JVM settings remain in their dedicated documents.

Source and Deployment

Mustard project source is maintained in minecraft-projects. Server copies are deployment or runtime copies.

Make lasting changes in Git, review them, and deploy them separately. A direct server-side diagnostic correction must be reconciled back into Git rather than left as the only corrected copy.

Datapack, TreePack, configuration, script, and compatibility-JAR deployment is separate from source maintenance. A merged source change does not establish that deployment occurred.

Maintenance Cadence

Mustard has a lengthy startup, so routine mod, datapack, TreePack and configuration changes should be grouped into planned or bundled full restarts where practical. Test changes before treating them as permanent, and review the resulting startup and runtime evidence before accepting the deployed state.

This document does not define restart commands or unattended deployment automation.

Restart-Only Maintenance

Use a complete stop, reviewed file synchronization and restart for routine Mustard maintenance. The same policy applies to future heavily modded Minecraft servers, using each server's own maintained sources and deployment paths.

Do not use /reload for routine administration, deployment or general troubleshooting. Minecraft reloads global server resources and datapacks; successfully reloading one mod does not establish that every installed mod can reload safely. Other listeners may mutate shared data concurrently, accumulate entries, retain stale cached configuration or leave resources inconsistent. Live /datapack enable and /datapack disable also trigger this global reload; do not use them to bypass the offline pack-priority procedure.

Avoiding administrator reload commands does not stop mods or load functions from invoking the same API. Tumbleweeds 1.1.0 has a confirmed first-world reload; the independent source correction is pending review, not a statement of deployment. Verify effective override priority before the first new-world startup and inspect repeated resource/recipe loading, not just a Reloading! chat message. Keep a new-world test isolated until known automatic reload paths are corrected and acceptance passes.

For routine changes:

  1. Review the maintained Git source and the intended change before deployment.
  2. Stop Minecraft completely and confirm it has exited.
  3. Apply the reviewed changes to the appropriate persistent deployment sources: server-datapacks/, server-treepacks/, server mod staging, or the documented configuration/deployment paths as appropriate. Git remains authoritative.
  4. With Minecraft stopped, synchronize world-scoped datapacks and TreePack overlays through the established sync-mustard-world-assets.sh workflow. Resolve the active world through level-name; preserve unrelated runtime trees/ resources. Keep the existing offline level.dat priority workflow: mustard-fixes before mustard-rules, with mustard-rules highest.
  5. Start Minecraft. Verify startup reaches Done, required resources load, pack order is correct and the targeted behavior passes validation before accepting the deployed state or resuming a generation task.

For a brand-new world, use the fresh-world preparation below before its first startup. Verify the actual full-pack order afterward and use the offline fallback if dynamically registered packs appear above the Mustard packs. No live reload is required. This policy does not introduce automatic restarts or change schedules.

Deliberate reload testing is permitted only when specifically authorized for a reload investigation in an isolated, disposable environment. If an unexpected runtime reload occurs during acceptance testing, stop and restart with the reviewed files, then repeat the relevant checks; do not assume that issuing a second reload repairs state. Investigate any mod that requires or initiates a runtime reload separately before allowing that workflow in routine operation. Client-only resource-pack refresh and loading saved chunks are distinct from a global server resource reload; this policy does not claim they are equivalent.

Update Testing and Validation

The routine mod-maintenance workflow is documented in mod-management.md. It supports:

  1. Capturing a known-good pre-update baseline.
  2. Applying a separately reviewed update candidate.
  3. Comparing mod inventories, hashes, startup logs, and generated data.
  4. Repeating tests or targeted diagnostics when differences need investigation.
  5. Recording a final known-good result only after required validation succeeds.

Review startup completion, relevant errors and warnings, generated-resource differences, and targeted compatibility evidence. Reusable analysis and validation tools may be deployed into the update-test diagnostic toolbox; per-run workspaces remain operational output.

World Rebuild Lifecycle

Mustard is currently in a Creative-heavy Create and Aeronautics capability-testing phase. The intended switch to normal Survival gameplay is tied to a future world rebuild after that phase is sufficiently mature.

server-configuration.md is authoritative for the current and target game-mode state. chunky-pregeneration-guide.md documents pregeneration considerations for a new world.

Maintained Data Deployment

The source repository contains maintained datapacks and TreePack source. Deployment into the server and world, and generation of runtime tree data, are separate operations.

World-scoped Mustard datapacks are synchronized with scripts/sync-mustard-world-assets.sh. The helper derives the server root from its deployed location and reads level-name from server.properties; it does not assume a world named world or require a host-wide /home/container alias. Runtime TreePack synchronization remains an overlay: preserve unrelated content in the shared trees/ directory.

Fresh-World Preparation

Use the reviewed helpers from minecraft-projects PR #43, squash-merged as f16b0a9. The merged implementation documentation is authoritative for source behavior, validation and limitations. Source merge and deployment remain separate operations.

  1. Stop Minecraft completely and confirm it has exited.

  2. Prepare the reviewed persistent server-datapacks/mustard-fixes, server-datapacks/mustard-rules and server-treepacks/mustard-tree-fixes/trees deployment sources. Keep the sync and priority helpers together under the individual server's scripts/.

  3. Confirm the target level-name is genuinely fresh: no level.dat, level.dat_old, data/scoreboard.dat, session state or regions. Only intended pre-seeded datapacks may exist; do not delete ambiguous world data to bypass the helper's refusal checks.

  4. From the server root, while Minecraft remains stopped, run:

    scripts/sync-mustard-world-assets.sh

  5. Review the prepared initial selection. Starting from the existing vanilla default, the helper prepares:

    initial-enabled-packs=vanilla,mod_data,file/mustard-fixes,file/mustard-rules

    Other explicitly selected packs retain their relationships and disabled settings; valid discovered file packs are included before the Mustard packs. Preserve server.properties.mustard-initial-backup-*. The helper verifies and atomically replaces the initial-enabled assignment, without creating world NBT. Its read-only preflight and refusal checks protect existing/ambiguous state, unsafe paths and conflicting selections; see the source documentation for the complete checks. Unrelated runtime TreePack resources remain intact.

  6. Start Minecraft normally. Verify startup completion, actual resource loading, effective mod_data < mustard-fixes < mustard-rules order and whether both Mustard packs are actually last, using datapack list enabled in the console. Follow the full-pack limitation below before accepting the world or starting pregeneration.

No preliminary Minecraft startup or synthetic level.dat is required to prepare initial selection. This improvement does not guarantee final highest priority over every dynamically registered mod pack. It also does not remove the need for PR #42's effective Tumbleweeds override precedence on the very first load.

Full-Pack Priority Limitation and Offline Fallback

Owner-reported Mustard full-pack testing on October 18–19, 2026 demonstrated the remaining limitation: the first startup enabled 34 datapacks, with additional dynamically registered packs placed after mustard-fixes and mustard-rules. After stopping Minecraft, running the existing offline priority helper and restarting, both Mustard packs occupied the final two positions, with mustard-rules highest.

Observation Initial Full-Pack Startup After Offline Priority Correction and Restart
Recipes loaded 42,334 42,476
ERROR entries 286 10
Mustard pack priority Dynamically registered packs followed the two Mustard packs mustard-fixes then mustard-rules occupied the final two positions

The corrected 42,476 recipes and 10 ERROR entries matched the October 10 baseline. These are recorded comparison results, not fixed acceptance counts for future changed modpacks. PR #43 fixes the initial-selection problem but does not yet fully resolve first-start priority across the complete Mustard pack.

For an already-generated world with incorrect effective order, stop Minecraft completely, ensure world assets are synchronized, and run from the server root:

python3 scripts/set-mustard-datapack-priority.py

Use no arguments for this existing-world fallback. It uses the Python standard library, acquires the world's session lock, backs up level.dat, and puts file/mustard-fixes followed by file/mustard-rules at the end of the enabled selection while retaining other packs' relative order. No external nbtlib or confirmation flag is required. Restart normally and verify the effective order, startup completion and resource/error comparison again; do not use /reload or live /datapack enable / /datapack disable as the correction.

Changing initial properties does not replace an existing world's saved selection. Offline priority repair applies to subsequent resource loads; it does not prove that first-load initialization side effects or already-generated content have been undone. Keep full pregeneration gated on the required full-pack acceptance.

Do not hand-edit a deployed datapack, TreePack output, configuration, script, or compatibility artifact and then treat that runtime copy as maintained source. Reproduce or reconcile the lasting change in Git.

Generated output must be reviewed before separately authorized deployment.

Related Documentation

Document Purpose
mod-management.md Mod artifacts and routine update tooling
server-configuration.md Current server settings and gameplay lifecycle
server-startup.md JVM settings and startup characteristics
server-environment.md Pterodactyl environment and storage
server-backup-strategy.md Backup and recovery boundaries
chunky-pregeneration-guide.md World pregeneration guidance
Mustard maintained source Canonical project source and tooling

Change History

2026-10-19

2026-10-18

2026-10-05

2026-10-01

2026-09-25