Maze Generator

Epic showcase by KasaiSora

My miserable showcase attempt

Usable on low end servers or big crowded servers

---~~~~

Maze Generator is a plugin capable of generating random and large labyrinths. Let me know what features you would like to see in the future 😄

Leave your positive or negative feedback, both are useful to everyone!

Feel free to contact me at mazegenerator@radqnico.anonaddy.com

See the GIF -> Link

My plugins are free to use without any catch, but if you want to support me and give me a way to continuing releasing new features, please consider a small contribution 😊

https://www.buymeacoffee.com/radqnico

---

Performance first

The placing of the maze is completely LAG FREE. The generation of the maze is VERY fast for mazes up to 5000x5000 then you COULD get some lag or crash your server if you're running on <2GB RAM 😂

Highlights

• Mathematically Proven: It is mathematically proven that from ANY position of the maze you can ALWAYS reach ANY OTHER position.
• LAG FREE: It does not impact the performance of the server. Generate your huge mazes on crowded servers like a breeze.
• Reload-Safe: It's reload-safe but the interrupted maze generation cannot be resumed (for now...).
• Progress Notifications: It notifies you on the progress for very long processes!
• Customizable Themes: Create your own theme from config!

MazeGenerator

Build massive, themed mazes in Minecraft without freezing the server. The plugin generates the maze layout incrementally and places blocks over time with a configurable per‑tick budget. Work is grouped per chunk, and chunks are only loaded on demand at the exact moment blocks need to be placed.

• Paper

Features

• Streaming generation and placement — no giant in‑memory queues.
• On‑demand chunk loading only (never preloads).
• Autotuned per‑tick time budget to protect TPS.
• Chunk‑grouped placement (multiple cells per job) to reduce overhead.
• Weighted material themes for floor/wall/top (themes.yml).
• Options for hollow walls and closed roofs.
• Tab‑complete for arguments, plus /maze help, /maze stop, /maze reload.

---

Installation

1. Build or download the plugin JAR.
2. Drop the JAR into your server’s plugins/ folder.
3. Start the server once to generate default config and data files.

Files created/used:

• plugins/MazeGenerator/config.yml — performance and behavior settings.
• plugins/MazeGenerator/themes.yml — material weights per theme.
• plugins/MazeGenerator/messages.yml — user‑facing messages.

Use /maze reload after changing these files, or restart the plugin/server.

---

Commands

• /maze — starts a build with sensible defaults near your position.
• /maze stop — stops all active maze builds.
• /maze help — prints usage and argument reference.
• /maze reload — reloads config.yml, themes.yml, and messages.yml.

Permissions:

• mazegenerator.maze — use /maze and view status.
• mazegenerator.reload — use /maze reload.

Arguments (key:value)

Order doesn’t matter; tab‑complete suggests keys and many values.

• x, y, z: World coordinates (defaults to your position).
• world: World name (defaults to your world).
• mazeSizeX, mazeSizeZ: Maze size in cells (odd enforced internally).
• cellSize: Block width/length of each cell footprint.
• wallHeight: Vertical wall height (excluding top layer).
• hasExits: true|false — ensure at least one exit at maze border.
• additionalExits: Extra exits on top of the first (0..N).
• hasRoom: true|false — carves a central rectangular room.
• roomSizeX, roomSizeZ: Room dimensions (cells) for the central room.
• erosion: 0..1 — occasional small holes in nearby walls while carving.
• closed: true|false — roof over paths as well (otherwise paths are open to sky).
• hollow: true|false — wall cells as a shell (edges only) for huge block savings.
• themeName: Theme key from themes.yml (tab‑complete lists available themes).

Examples:

• /maze mazeSizeX:51 mazeSizeZ:51 cellSize:2 wallHeight:4 hasExits:true additionalExits:1 themeName:forest
• /maze world:world_nether x:100 y:80 z:-200 mazeSizeX:41 mazeSizeZ:41 themeName:snowy
• /maze mazeSizeX:75 mazeSizeZ:75 cellSize:3 wallHeight:5 hasExits:true hollow:true closed:false themeName:desert

---

Configuration (config.yml)

Defaults are tuned to preserve TPS on most servers. Key settings:

• millis-per-tick (default 3)

  • Base time budget per tick used by the builder. Autotune adjusts this up/down within bounds.

• jobs-batch-cells (default 64)

  • How many maze cells the scheduler tries to collect per top‑up. Larger values reduce overhead a little, but can increase burstiness.

• cells-per-job (default 16)

  • How many cells to pack into a single placement job for a given chunk. Higher values reduce scheduler overhead and redundant chunk loads.

• set-block-data (default false)

  • Attach CustomBlockData to placed blocks. For most builds this should remain false (saves I/O and memory).

• defer-wall-fill (default false)

  • Build order option:
    • true: carve first (corridors appear quickly), then fill remaining walls; generally fewer total writes.
    • false: fill walls first, then carve; looks like a solid mass at first, then paths appear.

• autotune: (enabled by default)

  • min-millis-per-tick, max-millis-per-tick — bounds for the per‑tick time budget.
  • increase-step, decrease-step — how fast the budget grows/shrinks.
  • spare-high, spare-low — thresholds based on remaining time in the current 50 ms tick.

• status-interval-jobs (default 1000)

  • Prints a progress update in chat roughly every N jobs executed.

Note: The plugin loads chunks on demand at placement time — there is no preloading and no background chunk budgets.

Example: Smooth (minimal TPS impact)

millis-per-tick: 2
jobs-batch-cells: 32
cells-per-job: 8
set-block-data: false

autotune:
  enabled: true
  min-millis-per-tick: 1
  max-millis-per-tick: 4
  increase-step: 1
  decrease-step: 2
  spare-high: 18
  spare-low: 12

defer-wall-fill: true
status-interval-jobs: 500

Example: Balanced (default‑like)

millis-per-tick: 3
jobs-batch-cells: 64
cells-per-job: 16
set-block-data: false

autotune:
  enabled: true
  min-millis-per-tick: 1
  max-millis-per-tick: 8
  increase-step: 1
  decrease-step: 2
  spare-high: 18
  spare-low: 12

defer-wall-fill: false
status-interval-jobs: 1000

Example: Fast (accept some risk of spikes)

millis-per-tick: 5
jobs-batch-cells: 128
cells-per-job: 32
set-block-data: false

autotune:
  enabled: true
  min-millis-per-tick: 2
  max-millis-per-tick: 10
  increase-step: 1
  decrease-step: 1
  spare-high: 20
  spare-low: 10

defer-wall-fill: true
status-interval-jobs: 750

---

Themes (themes.yml)

Themes control weighted material selection for three sections: floor, wall, and top.

Example:

desert:
  floor:
    SANDSTONE: 20
    RED_SANDSTONE: 10
  wall:
    SAND: 40
    CHISELED_SANDSTONE: 20
  top:
    SANDSTONE: 3

forest:
  floor:
    GRASS_BLOCK: 20
    DIRT: 2
  wall:
    OAK_LOG: 30
    OAK_LEAVES: 25
  top:
    OAK_LOG: 3

Weights are positive integers; higher weight = more likely. If a section is empty, it falls back to STONE.

Tips:

• Use more variety in wall and top for a more organic look.
• Keep top materials lighter for interesting silhouettes.

---

Messages (messages.yml)

• plugin-prefix, job-started, job-status, job-done, job-stopped, command-error, no-permission, config-reloaded.
• Color codes use & and are translated on send.

---

How Autotune Works (Quick)

• Measures spare time within the current 50 ms server tick (based on a tick start event).
• If there’s plenty of spare time (spare >= spare-high), it increases the per‑tick time budget by increase-step up to max-millis-per-tick.
• If the tick is tight (spare < spare-low), it decreases by decrease-step down to min-millis-per-tick.
• The builder places blocks only until now + currentMillisPerTick each tick.

---

Performance Tips

• Use hollow: true and a larger cellSize to reduce total blocks dramatically.
• Increase cells-per-job and jobs-batch-cells to reduce scheduling overhead.
• Keep set-block-data: false unless you really need it.
• Prefer defer-wall-fill: true for faster “time‑to‑visible maze” and fewer writes.

---

Troubleshooting

• “Maze seems stuck” or no progress:
  • Chat updates are periodic; lower status-interval-jobs for more frequent feedback.
  • Check console for errors. If chunks are extremely far, each job will load them on demand; this can be slow but should not stall.
• TPS dips during build:
  • Lower millis-per-tick, jobs-batch-cells, or cells-per-job.
  • Keep autotune.enabled: true so budget backs off automatically.
• Themes look too uniform:
  • Add more materials and weights to wall/top sections.

Tired of sweats?

/maze cellSize:1 mazeSizeX:1000 mazeSizeZ:1000 wallHeight:4 themeName:mountain erosion:0.05

Have fun, cheers!