GC-CommandMagic

(this README was created with AI assistance and fact-checked by a human)

A Paper 1.20.x plugin that lets builders drop “magic” entities into a GhibliCraft world with a single command and a selection wand. Teleport pads, particle shows, sound cues, schematic blocks and more are all defined, moved and removed completely in-game.

---

Highlights

• Seven entity types: TELEPORTER, PARTICLE, SOUND, CHAIN, SINGLEBLOCK, SCHEMBLOCK, TRIGGER
• Single root command /gc-magic with sub-commands create, remove, move, list, wand, reload
• Selection wand for accurate block targeting plus a handy /gc-magic wand where locator
• JSON persistence (everything auto-saves to magicBlocks.json and re-applies on server start)
• Runs on Java 17 and the Paper 1.20.4 API

---

Installation

1. Clone or download the repository.

2. Build with Maven:

   mvn clean package

   The shaded JAR will appear in target/.

3. Drop the JAR into your server’s plugins/ folder and restart the server.

---

Basic Usage

Action	Command pattern
Create an entity	/gc-magic create <type> <name> [extra-args]
Move an entity	/gc-magic move <type> <name> …
Delete an entity	/gc-magic remove <type> <name>
List entities	/gc-magic list <type|all|schems> [simple]
Give yourself a wand	/gc-magic wand  or  /gc-magic wand where
Reload the plugin	/gc-magic reload

Permission required: gc.commandmagic

---

Entity Types – quick reference

• TELEPORTER: clickable pad that moves players
• PARTICLE: repeating particle emitter for ambience
• SOUND: positional sound-effect trigger
• CHAIN: links multiple magic actions in sequence
• SINGLEBLOCK: single block that toggles or changes state
• SCHEMBLOCK: drops a WorldEdit schematic at run time
• TRIGGER: fires other entities based on conditions

---

Data & reloading

All entities are cached in memory and written to plugins/GC-CommandMagic/magicBlocks.json.
Running /gc-magic reload stops the scheduler, reloads entities from disk and resumes without a full server restart.

---

Detailed entity reference

Type everything below after the root command /gc-magic.
[square] brackets are literal text, <angle> brackets are values you choose.

1. TELEPORTER

Operation	Syntax
Create	create teleporter <name> <destX> <destY> <destZ> <yaw> <pitch> <CLICK|APPROACH>
Move	move teleporter <name> origin move teleporter <name> destination
Notes	CLICK = right-click the origin block. APPROACH = stand on it. Destination yaw & pitch are preserved.

---

2. PARTICLE

Operation	Syntax
Create	create particle <name> <particle> <x> <y> <z> <dx> <dy> <dz> <speed> <count> <force|normal> <true|false-loop>
Create (wand)	Same as above but omit <x y z> to use the wand block
Move	move particle <name> [x y z] or wand move
Notes	loop=true emits every 10 ticks. force shows particles to all players regardless of distance.

---

3. SOUND

Operation	Syntax
Create	create sound <name> <soundKey> <category> [x y z] <volume> <pitch> <minVolume> <true|false-loop> [intervalSecs]
Move	move sound <name> [x y z] or wand move
Notes	If looping, volume is recalculated per tick per player. minVolume = the quietest volume at max range (16 × volume). Default interval is 50 s (1000 ticks).

---

4. SINGLEBLOCK

Operation	Syntax
Create	create singleblock <name> <x> <y> <z> <CLICK|APPROACH> <blockData…> (wand selects the trigger)
Move	move singleblock <name> <x> <y> <z> trigger|block
Notes	Saves the original block data before replacement and restores it on toggle—ideal for doors, lamps and décor.

---

5. SCHEMBLOCK

Operation	Syntax
Create	create schemblock <name> <x> <y> <z> <file.schem> <CLICK|APPROACH> <true|false-replaceAir> (wand selects the trigger)
Move	move schemblock <name> <x> <y> <z> trigger|destination
Notes	Paste runs asynchronously; undo uses FAWE’s paste ID. replaceAir=false keeps existing blocks, true overwrites with air.

---

6. CHAIN

Operation	Syntax
Create	create chain <name> <CLICK|APPROACH> [x y z] TYPE:name [delay] TYPE:name …
Move	move chain <name> [x y z] or wand move
Notes	Each step references an existing entity (e.g. TELEPORTER:gate1). delay is in seconds and applies before that step.

---

7. TRIGGER

Operation	Syntax
Create	create trigger <name> <chainName> <time|weather> <param>
Notes	time: day or night  •  weather: clear, rain, thunder Polls every 10 ticks and will not fire again until the condition resets.

---

Putting it all together

1. Give yourself a selection wand:

   /gc-magic wand
   

   then punch a block to set the origin.
2. Create an entity with one of the commands above.
3. List your creations:

   /gc-magic list all
   

   (add simple for a concise view).
4. Link multiple effects with a CHAIN entity.
5. Save or reload at any time—everything lives in magicBlocks.json.

Happy building!