📐 GlymeraChunkGrid 📐

Toggle chunk boundary visualization using DebugShape boxes with the /grid command.

Don't miss my other exciting projects — take a look at GlymeraCraft's Profile Discord: https://discord.gg/s5NRFWfxgy

◆ What is GlymeraChunkGrid?

GlymeraChunkGrid lets players visualize the exact boundaries of the chunk they are standing in using semi-transparent purple debug boxes. Toggle it on with the /grid command and a complete outline of your current 32x32 block chunk will appear around you - four horizontal border lines at your Y level marking all four edges, plus four vertical pillars at each corner extending 20 blocks upward.

The display is completely per-player. Each player controls their own chunk grid independently. The debug shapes are sent exclusively to the player who enabled them via direct packet sending - no other player on the server sees them, and no actual entities or blocks are placed in the world. The display updates every half second, following the player seamlessly as they move between chunks.

This is a utility tool for server administrators, builders, and players who need to know exact chunk boundaries. It is especially useful when working with chunk-based systems like plot protection, population caps, spawn beacons, or any other mechanic that operates on a per-chunk basis.

◆ How it Works - Step by Step

The player types /grid in chat.
The command retrieves the player's current position and calculates which chunk they are in by dividing the X and Z coordinates by 32 (Hytale's chunk size) and flooring the result.
The player's UUID is added to the enabled players set. A confirmation message is sent: "Chunk grid ON - You are in chunk 4:7" (showing the chunk coordinates).
Every 500 milliseconds, a scheduled render task runs on the server. It iterates over all enabled players across all loaded worlds.
For each enabled player, the plugin:
- Retrieves the player's current position from their TransformComponent
- Calculates the chunk boundaries: minX, maxX (minX + 32), minZ, maxZ (minZ + 32)
- Clears all previously displayed debug shapes for that player
- Sends horizontal border boxes along all 4 edges of the chunk at the player's Y level, each edge composed of two half-length bars placed end-to-end
- Sends vertical pillar boxes at all 4 corners of the chunk, extending 20 blocks upward from the player's Y position
All debug shapes are sent as DisplayDebug packets directly to the individual player's packet handler using writeNoCache(). No other players receive these packets.
The display automatically follows the player. As they walk into a different chunk, the next render cycle (within 500 milliseconds) will show the new chunk's borders.
To disable, the player types /grid again. Their UUID is removed from the set, all debug shapes are cleared, and the message "Chunk grid OFF" is sent. No more shapes are rendered for that player.
If a player disconnects while the display is active, the next render cycle detects that the PlayerRef is null and automatically removes them from the enabled set.

◆ Features

Per-player toggle - Each player independently enables or disables their own chunk grid display with /grid. Multiple players can have it active simultaneously without interfering with each other.
Private display - Debug shapes are sent as direct packets to the individual player only. No other players see them. No entities or blocks are placed in the world. Zero visual impact on other players.
Horizontal chunk outline - Semi-transparent purple boxes trace all 4 edges of the 32x32 chunk at the player's current Y level. Each edge is composed of two half-length bars (16 blocks each) placed end-to-end, creating a continuous border line. The north edge (minZ), south edge (maxZ), west edge (minX), and east edge (maxX) are all rendered.
Vertical corner pillars - At each of the 4 chunk corners (NW, NE, SW, SE), a vertical box extends 20 blocks upward from the player's Y position. This helps visualize the chunk boundary in 3D, especially in hilly terrain.
Smooth real-time tracking - The display updates every 500 milliseconds. As the player moves, the borders shift smoothly to show whichever chunk the player is currently standing in. The 2-second display duration of each shape overlaps with the 0.5-second refresh rate, ensuring continuous visibility with no blinking or gaps.
Chunk coordinate display - When enabling the grid, the player sees their current chunk coordinates in the format "chunk X:Z" in the chat message.
Multi-world support - The render task iterates over all loaded worlds on the server. If a player moves to a different world, their grid continues to render in the new world. Players are only rendered in the world they are currently in (checked via store reference comparison).
Automatic cleanup - If a player disconnects or their PlayerRef becomes invalid, they are automatically removed from the enabled set during the next render cycle. On plugin shutdown, all debug shapes are cleared for every enabled player before the set is emptied.
Zero server load when inactive - The render task checks if the enabled players set is empty before doing any work. If no players have the grid active, the task returns immediately with zero processing.
Thread-safe - The enabled players set uses ConcurrentHashMap.newKeySet() for thread safety. The render task dispatches to each world's thread via world.execute() to safely access entity positions. The command handler also dispatches via world.execute() to safely read the player's position.

◆ Debug Shape Layout

Each render cycle generates the following debug shapes for one player:

▸ Horizontal Borders (at player Y)

North edge - Two boxes placed end-to-end along the X axis at z=minZ, each 16 blocks long and 0.1 blocks thick. The first box covers from minX to midX, the second from midX to maxX.
South edge - Two boxes placed end-to-end along the X axis at z=maxZ, same layout as the north edge.
West edge - Two boxes placed end-to-end along the Z axis at x=minX, each 16 blocks long and 0.1 blocks thick. The first box covers from minZ to midZ, the second from midZ to maxZ.
East edge - Two boxes placed end-to-end along the Z axis at x=maxX, same layout as the west edge.

▸ Vertical Pillars (at 4 corners)

NW corner - A vertical box at (minX, playerY, minZ) extending 20 blocks upward, 0.1 blocks thick on X and Z
NE corner - A vertical box at (maxX, playerY, minZ) extending 20 blocks upward, 0.1 blocks thick on X and Z
SW corner - A vertical box at (minX, playerY, maxZ) extending 20 blocks upward, 0.1 blocks thick on X and Z
SE corner - A vertical box at (maxX, playerY, maxZ) extending 20 blocks upward, 0.1 blocks thick on X and Z

Total debug shapes per render cycle per player: 12 boxes (8 horizontal border bars + 4 vertical corner pillars). Each shape has a display duration of 2 seconds. With the 500ms refresh rate, shapes overlap for continuous visibility.

◆ Commands

/grid - Toggle chunk grid display on or off. When enabled, shows your current chunk coordinates (e.g. "Chunk grid ON - You are in chunk 4:7"). When disabled, clears all debug shapes and shows "Chunk grid OFF". Can only be used by players, not from console.

◆ Configuration

This plugin has no configuration file. All values are built into the plugin:

Chunk size - 32 blocks (Hytale default chunk size)
Shape type - DebugShape.Cube (solid semi-transparent boxes)
Color - Purple (RGB 0.78, 0.36, 1.0) matching the Glymera theme
Opacity - 0.6 (semi-transparent, visible but not obstructive)
Line thickness - 0.1 blocks for both horizontal borders and vertical pillars
Pillar height - 20 blocks upward from the player's Y position
Display duration - 2 seconds per shape (overlaps with refresh rate for continuous display)
Render interval - 500 milliseconds (shapes are refreshed twice per second)

◆ Technical Details

Chunk boundaries are rendered using DisplayDebug packets with DebugShape.Cube, which draws solid semi-transparent boxes defined by a 4x4 column-major transformation matrix
Each box is defined by its center position (translation) and dimensions (scale) encoded in the transformation matrix. The scale values in the diagonal control the box size, while the bottom row controls the position.
Previous debug shapes are cleared before each render cycle using a ClearDebugShapes packet, ensuring no leftover shapes accumulate
Packets are sent via playerRef.getPacketHandler().writeNoCache() - directly to the individual player, bypassing the server's normal broadcast system
The enabled player set uses ConcurrentHashMap.newKeySet() for thread-safe concurrent access
The render task runs on Hytale's ScheduledExecutor at a fixed 500ms interval and dispatches to each world's thread via world.execute()
Players in different worlds are skipped by comparing ref.getStore() against the current world's store
Chunk coordinate calculation: chunkX = floor(playerX / 32), chunkZ = floor(playerZ / 32)
On plugin shutdown, all debug shapes are cleared for enabled players and the render task is cancelled
The plugin has no persistent state. If the server restarts, all players' chunk grids are off by default.

◆ Installation

Stop your Hytale server
Copy GlymeraChunkGrid.jar into your server's mods/ folder
Start your server
Check the server log for the message: "GlymeraChunkGrid v2.2.0 started!"
In-game, type /grid to toggle the display on or off

No asset pack is required. This plugin is a single JAR file with no external dependencies.

◆ Support

Having issues or questions? Leave a message here or visit our Discord!

Developed by GlymeraCraft