DecoSwap

Build once. Save it. Bring it back whenever you need it.

DecoSwap is a Minecraft Paper plugin that lets you capture, manage and reuse decorations made from blocks and entities.

Whether you're creating seasonal events, decorating a lobby or building detailed displays with Armor Stands and Display Entities, DecoSwap lets you save your creations and bring them back without rebuilding everything manually.

Unlike traditional schematics, DecoSwap works with exact object selections, allowing you to include only the blocks and entities you actually want.

✨ Features

• Precise Selection — Select individual blocks and entities or import entire regions. Combine selection modes and exclude unwanted objects.
• Three Selection Modes — OBJECT, REGION and ANCHOR, with private visual outlines to help you see exactly what you're selecting.
• Reusable Decorations — Save, update, edit and pack decorations without having to recreate them.
• Flexible Placement — Deploy decorations at their original location or somewhere else, with 0°, 90°, 180° and 270° rotations.
• Deployment Snapshots — Before placing blocks, DecoSwap records their previous state so it can restore them when the decoration is removed.
• Decoration Groups — Organize multiple decorations into Groups and deploy or restore them together. Perfect for seasonal events!
• Change Detection — Detect modifications to saved decorations, with red visual outlines and reports for administrators.
• In-Game GUI — Manage decorations, groups and active deployments through convenient menus with customizable Group icons.
• Recovery System — Inspect and recover interrupted deployment operations using saved transaction data.
• Multilanguage Support — English and Spanish included, with automatic language detection and an in-game guide.

🛠️ Getting Started

Getting started is simple:

1. Get your selection tool

/ds wand

2. Select your decoration

Use the wand to select blocks and entities individually, or switch to REGION mode to select larger areas.

Switch between OBJECT, REGION and ANCHOR using Shift + F (the sneak and swap-hand controls).

3. Save your creation

/ds save christmas_tree

This creates a reusable Decoration without removing anything from the world.

4. Pack your decoration (optional)

/ds pack christmas_tree

Saves the current decoration and removes its selected objects from the world.

5. Deploy and restore

/ds place christmas_tree

/ds remove christmas_tree

Deploy your saved creation and later restore the block state recorded before that deployment.

You can also open /ds gui to manage your decorations through the in-game interface.

📋 Commands

The main command is /decoswap, with /ds as its shorter alias.

Selection & Editing

Command	Description
/ds wand	Get the selection wand.
/ds mode <mode>	Switch between object, region and anchor modes.
/ds select region [all|blocks|entities]	Import objects from the selected region.
/ds select info	View your current selection.
/ds undo	Undo the last selection change.
/ds clear	Clear the current selection.
/ds anchor set	Set a custom decoration origin.
/ds edit <name>	Edit an existing Decoration.

Decoration Management

Command	Description
/ds save <name>	Save or update a Decoration.
/ds pack <name>	Save and remove the original objects.
/ds place <name>	Deploy at the saved location.
/ds place <name> here	Deploy at your current location.
/ds remove <name>	Restore a recorded deployment.
/ds changes <name>	Check for modifications to a saved home Decoration.
/ds info <name>	View Decoration information.
/ds list	List saved Decorations.
/ds active	List active Deployments.

Placement also supports --rotation 0|90|180|270. Advanced placement and restoration commands support --force, subject to additional permissions.

Groups & Administration

Command	Description
/ds group create <name>	Create a new Group.
/ds group add <group> <decoration>	Add a Decoration to a Group.
/ds group remove <group> <decoration>	Remove a Group member.
/ds group deploy <name>	Deploy a Group.
/ds group restore <name>	Restore a Group.
/ds recovery list	List incomplete transactions.
/ds gui	Open the management interface.
/ds guide	Open the in-game guide.
/ds language <auto|en_US|es_ES>	Change your language preference.
/ds reload	Reload supported configuration and language files.
/ds version	Display plugin and server compatibility information.

Tip: Use /ds help for the in-game command overview. Additional selection, recovery and administration commands are documented in the Wiki.

🔐 Permissions

DecoSwap provides permission-based access to editing tools, decoration management, deployment and administrative operations.

All permissions default to server operators (OP). The decoswap.admin permission grants access to all declared DecoSwap permissions.

General & Selection

Permission	Description
decoswap.use	Access to the main command.
decoswap.help	Access to the help command.
decoswap.wand	Obtain the selection wand.
decoswap.select	Use selection tools and commands.
decoswap.anchor	Manage custom Anchors.

Decoration Management

Permission	Description
decoswap.decoration.create	Legacy explicit Decoration creation.
decoswap.decoration.save	Save Decorations, including automatic updates through the save command.
decoswap.decoration.update	Explicitly update and edit Decorations.
decoswap.decoration.pack	Pack Decorations.
decoswap.decoration.delete	Delete saved Decorations.
decoswap.decoration.deploy	Deploy Decorations.
decoswap.decoration.restore	Restore Deployments.
decoswap.decoration.info	View Decorations and active deployment information.
decoswap.decoration.changes	Scan and receive Decoration change reports.

Groups & Administration

Permission	Description
decoswap.group.create	Create Groups.
decoswap.group.edit	Manage Group members and icons.
decoswap.group.delete	Delete Groups.
decoswap.group.deploy	Deploy Groups.
decoswap.group.restore	Restore Groups.
decoswap.recovery	Inspect and recover incomplete operations.
decoswap.reload	Reload supported settings.
decoswap.admin	Grant all DecoSwap permissions.

Advanced Permissions

The following permissions control sensitive operations:

• decoswap.capture.inventory
• decoswap.capture.commandblock
• decoswap.capture.dangerous
• decoswap.deploy.force
• decoswap.restore.force

Sensitive block capture also depends on the server configuration.

Recommendation: Grant decoration editing and deployment permissions only to trusted staff, especially when using force operations or capturing sensitive block data.

📦 Requirements & Compatibility

• Server: Paper (built against 1.21.4)
• Java: Java 21 bytecode; use the Java runtime required by your Paper version
• Dependencies: None required
• Optional integration: EasyArmorStands
• Languages: English and Spanish

Later Paper versions are intended compatibility targets but require validation on their respective server builds.

No WorldEdit, FAWE, ProtocolLib or resource pack is required.

⚠️ Important Information

DecoSwap records the previous block state before each deployment, allowing tracked placements to be restored. Saving an original decoration does not create a historical backup of the terrain that existed before it was built.

Restoration checks for modified blocks and aborts on conflicts by default, helping prevent accidental overwrites. State preservation depends on the supported block and entity types.

We recommend keeping world backups when managing important builds.