Packet Block Themes

Packet-block themes let players sharing one physical arena see different cosmetic material palettes. The plugin sends sparse block changes through Paper's public packet API; it never changes the physical world and does not require ProtocolLib.

Configure a theme

An area must have explicit bounds before it can define replacements:

areas:
  shared_arena:
    bounds:
      minimum: 'world,-30,44,282,0,0'
      maximum: 'world,144,153,429,0,0'
    packet-blocks:
      replace-blocks:
        SAND: RED_SAND
        LIME_TERRACOTTA: ORANGE_TERRACOTTA
        SPRUCE_PLANKS: ACACIA_PLANKS

Material names may use Bukkit names or a minecraft: namespace. Source and target must be different block materials.

Visual setup tool

After applying arena bounds in /dga setup:

1

Select a source block

Right-click a physical source block inside the arena.

2

Select a target appearance

Sneak-right-click any sample block with the desired target appearance.

3

Remove a replacement

Punch a configured source block to remove its replacement.

4

View the current selection

Right-click air to view the current selection and replacement count.

Advanced direct commands are:

/dga setup <zone> packetblock <source> <target>
/dga setup <zone> packetblockremove <source>

Safety validation

The physical server remains authoritative for collision, interaction, lighting, fluids, containers, redstone, and ticking. Validation rejects replacements that would make the client view disagree with server behavior.

It also rejects missing bounds, empty maps, unknown materials, sources absent from the live area, identical source and target, oversized areas, too many changed blocks, and configurations exceeding global theme or memory caps.

Use cosmetic full-block swaps with compatible behavior. Do not use themes to change geometry, doors, containers, fluids, redstone, or air/solid state.

Engine limits

The packet-blocks section of settings/engine.yml controls:

• area and total captured volume;

• changes per theme and total retained changes;

• maximum theme count;

• capture blocks per tick;

• delivery blocks and sections per tick;

• maximum queued sections.

Lower per-tick budgets reduce pressure but make large preparation or delivery slower. Global caps reject unsafe configurations before publication.

Commands and cache

/dga validate
/dga reload
/dga blocks status
/dga blocks rebuild

validate checks configuration but does not capture or publish world blocks. reload performs live capture, compilation, validation, and publication.

Captured bases are cached under cache/packet-blocks/. These files are disposable. To force a full recapture, stop the server and delete only that cache directory.

Coordinates used by an active compiled theme are protected from physical changes. Staff with drakodungeons.packetblocks.bypass may edit them deliberately; run /dga reload afterward to rebuild every affected palette.