PixelWorks

** PixelWorks Plugin - Complete Documentation

🎆 Overview

  _____ _          _  __          __        _       
 |  __ (_)        | | \ \        / /       | |       
 | |__) |__  _____| |  \ \  /\  / /__  _ __| | _____ 
 |  ___/ \ \/ / _ \ |   \ \/  \/ / _ \| '__| |/ / __|
 | |   | |>  <  __/ |    \  /\  / (_) | |  |   <\__ \
 |_|   |_/_/\_\___|_|     \/  \/ \___/|_|  |_|\_\___/

Custom Particle Firework Shapes & Text for Minecraft

PixelWorks is a premium-quality Paper plugin that revolutionizes fireworks in Minecraft. Instead of standard firework explosions, PixelWorks displays stunning custom shapes and readable text made entirely of colored particles in the sky!

Perfect for:

• 🎄 Holiday Events (Christmas, New Year, Halloween)
• 🎉 Server Celebrations (Anniversaries, Milestones)
• 🏆 Player Rewards (Achievement unlocks, VIP perks)
• 🎨 Creative Builds (Light shows, Decorations)
• 📢 Announcements (Server messages in the sky)

Specification	Details
Plugin Name	PixelWorks
Version	1.0.0
API Version	Paper 1.21+
Compatibility	Minecraft 1.21.1 - 1.21.4
Java Version	Java 21+
Dependencies	None (Standalone)

---

✨ Key Features

🎨 Particle Rendering Engine

Feature	Description
Bitmap Font System	Complete A-Z, 0-9, and punctuation rendered as 5×7 pixel characters
ASCII Art Shapes	Define custom shapes using simple grid patterns in config
Vector Mathematics	Precise 2D to 3D transformation with rotation matrices
Player-Facing Display	Patterns automatically rotate to face the launching player
Multi-line Text	Automatic word wrapping for long messages
Dual Color Support	Primary and secondary colors for detailed designs
Animated Display	Particles persist for configurable duration

🚀 Custom Firework Items

Feature	Description
PDC Storage	Pattern data stored using PersistentDataContainer (survives server restarts)
Custom Display Names	Beautiful formatted names with icons
Detailed Lore	Shows pattern type, content, and dimensions
Stack-friendly	Items stack properly like vanilla fireworks
No NBT Issues	Uses modern PDC system, not deprecated NBT tags

🛠️ Recipe System

Feature	Description
Shaped Recipes	Define exact ingredient positions
Shapeless Recipes	Any arrangement of ingredients works
Configurable Results	Set how many fireworks each craft produces
Hot Reload	Add new recipes without server restart

📦 22 Pre-Built Patterns

Category	Patterns
Mob Faces (12)	Skeleton, Zombie, Villager, Pillager, Enderman, Warden, Wither, Dragon
Animals (6)	Wolf, Cat, Axolotl, Panda, Reindeer
Players	Steve
Objects (3)	Christmas Tree, Gift Box, Cake
Text (4)	Merry Christmas, Happy New Year, Happy New Year 2026, everETERNAL SMP

⚡ Performance Optimized

Feature	Description
Cached Calculations	Pattern points calculated once then cached
Async Particle Spawning	Non-blocking particle display
Configurable Limits	Control particle count and spawn rate
View Distance	Only spawn particles for nearby players

---

🔧 How It Works

The Process Flow

┌─────────────────┐
│  Player crafts  │
│  or receives    │
│  PixelWorks     │
│  Firework       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Firework has   │
│  PDC data with  │
│  pattern_id     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Player launches│
│  firework       │
│  (right-click)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Firework flies │
│  up and         │
│  explodes       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Plugin cancels │
│  vanilla        │
│  explosion      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  ParticleEngine │
│  loads pattern  │
│  from config    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Calculate      │
│  rotation to    │
│  face player    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Transform 2D   │
│  points to 3D   │
│  world coords   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Spawn DUST     │
│  particles at   │
│  each point     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Beautiful      │
│  pattern        │
│  displayed!     │
└─────────────────┘

Vector Mathematics Explained

The plugin uses rotation matrices to transform 2D grid coordinates into 3D world positions:

Given:
- Origin point (explosion location)
- 2D grid point (x, y)
- Yaw angle (direction to face)
- Scale factor

Calculate:
1. Right vector = (cos(yaw), 0, sin(yaw))
2. Up vector = (0, 1, 0)
3. World position = Origin + (Right × x × scale) + (Up × y × scale)

This ensures the pattern always faces the correct direction regardless of where the firework explodes.

---

💻 Commands

Main Command: /pw (aliases: /pixelworks, /fireworkart)

Command	Description	Permission
/pw get <pattern_id> [amount]	Give yourself a custom firework	pixelworks.get
/pw create <id> text <content>	Create a new text pattern	pixelworks.create
/pw list [text|shape]	List all available patterns	pixelworks.command
/pw info <pattern_id>	View detailed pattern information	pixelworks.command
/pw test <pattern_id>	Test-render a pattern above your head	pixelworks.admin
/pw reload	Reload all configurations	pixelworks.reload
/pw help	Show command help	pixelworks.command

Command Examples

 Get 16 skeleton face fireworks
/pw get skeleton_face 16

 Create a custom birthday message
/pw create birthday text Happy Birthday!

List only shape patterns
/pw list shapes

 View info about the dragon pattern
/pw info dragon

Test the christmas tree pattern
/pw test christmas_tree

 Reload after editing config
/pw reload

---

🔐 Permissions

Permission	Description	Default
pixelworks.command	Access to base /pw command	OP
pixelworks.get	Use /pw get to obtain fireworks	OP
pixelworks.create	Create new patterns via command	OP
pixelworks.reload	Reload plugin configuration	OP
pixelworks.use	Craft and use custom fireworks	Everyone
pixelworks.admin	Full access to all features	OP

Permission Hierarchy

pixelworks.admin
├── pixelworks.command
├── pixelworks.get
├── pixelworks.create
├── pixelworks.reload
└── pixelworks.use

LuckPerms Examples

 Give players access to use fireworks
/lp group default permission set pixelworks.use true

Give VIPs ability to get fireworks
/lp group vip permission set pixelworks.get true

 Give admins full access
/lp group admin permission set pixelworks.admin true

---

⚙️ Configuration

Settings Section

settings:
  Spacing between particles (smaller = denser, larger = spread out)
  Recommended: 0.3 - 0.5
  default-scale: 0.35
 
   Maximum distance players can see particles
  Higher values may impact performance
  view-distance: 64
 
   Should patterns rotate to face the launching player?
   true = faces player, false = always faces south
  face-player: true
 
  Size of each dust particle
   1.0 = normal, 0.5 = small, 2.0 = large
  particle-size: 1.0
 
   How many particles spawn per game tick
   Higher = faster display, more lag
  particles-per-tick: 100
 
   How long the pattern stays visible (20 ticks = 1 second)
  display-duration: 40
 
   Enable smooth color transitions
  use-color-transition: false

Scale Visual Guide

Scale Value	Effect	Best For
0.2	Very dense, compact	Small detailed shapes
0.35	Default, balanced	Most patterns
0.5	Spread out, large	Text, simple shapes
0.75	Very large	Giant displays
1.0	Maximum spread	Huge sky writing

Color Format Support

Format	Example	Description
Hex	FF5500	Standard hex color
Hex (no hash)	FF5500	Also works
RGB	(255, 85, 0)	RGB tuple
RGB (no parens)	255, 85, 0	Also works
Named	red	Predefined color names
Minecraft	dark_purple	MC color names
Custom	christmas_red	Plugin custom colors

Available Named Colors

Standard:          Minecraft:          Custom:
- white            - dark_red          - christmas_red
- silver           - gold              - christmas_green
- gray/grey        - dark_green        - snow
- black            - dark_aqua         - gold_star
- red              - dark_blue
- maroon           - dark_purple
- yellow           - light_purple
- olive            - dark_gray
- lime
- green
- aqua
- teal
- blue
- navy
- fuchsia
- purple
- orange

---

🎨 Preset Patterns

Text Patterns (4)

ID	Display Text	Colors
merry_christmas	Merry Christmas	Red + Green
happy_new_year	Happy New Year	Gold + White
happy_new_year_2026	Happy New Year 2026	Gold + Red
evereternal_smp	everETERNAL SMP	Purple + Blue

Shape Patterns (18)

Mob Faces

ID	Description	Colors	Size
skeleton_face	Skeleton skull	White + Black	11×11
zombie_face	Zombie head	Green + Black	11×11
villager	Villager face with nose	Tan + Green	11×11
pillager	Pillager with angry eyes	Gray + Black	11×11
enderman	Enderman with purple eyes	Black + Magenta	11×11
warden	Deep dark Warden	Dark Cyan + Cyan	13×12
wither	Three-headed Wither	Black + Gray	19×10
dragon	Ender Dragon	Purple + Magenta	17×12

Animals

ID	Description	Colors	Size
wolf	Wolf/Dog face	Silver + White	11×11
cat	Orange tabby cat	Orange + Black	11×10
axolotl	Pink axolotl	Pink + Hot Pink	11×10
panda	Panda with eye patches	White + Black	11×10
reindeer	Reindeer with antlers	Brown + Red	11×11

Players & Objects

ID	Description	Colors	Size
steve	Steve player head	Tan + Brown	11×11
christmas_tree	Decorated tree	Green + Gold	13×15
gift_box	Present with ribbon	Red + Gold	11×10
cake	Birthday cake with candles	Cream + Red	11×9

Visual Previews (ASCII)

Skeleton Face

  XXXXXXX 
 XXXXXXXXX 
XXXXXXXXXXX
XXX OOO XXX  ← Black eyes
XXX OOO XXX
XXXXXXXXXXX
XXXXXXXXXXX
XX XXXXX XX
XXX     XXX  ← Mouth
 XX X X XX 
  XXXXXXX 

Christmas Tree

      O       ← Gold star
     XXX     
    XXXXX   
   XXXXXXX   
  XXXXXXXXX 
    XXXXX   
   XXXXXXX   
  XXXXXXXXX 
 XXXXXXXXXXX 
   XXXXXXX   
  XXXXXXXXX 
 XXXXXXXXXXX 
XXXXXXXXXXXXX
     OOO      ← Trunk
     OOO     

Dragon

 X             X   ← Wing tips
XX   XXXXX   XX
 X  XXXXXXX  X 
   XXX O XXX       ← Eye
   XXXXXXXXX   
  XXXXXXXXXXX 
 XXXXXXXXXXXXX 
  XX XXXXX XX 
     XXXXX     
    XX   XX   
   XX     XX   
  XXX     XXX      ← Claws

---

🔨 Custom Recipes

Recipe Types

Type	Description
SHAPED	Ingredients must be in specific positions
SHAPELESS	Any arrangement of ingredients works

Shaped Recipe Example

recipes:
  skeleton_face:
    type: SHAPED
    pattern:
      - " S "      Row 1: Skull in middle
      - "GPG"       Row 2: Gunpowder, Paper, Gunpowder
      - " F "       Row 3: Firework Star in middle
    ingredients:
      S: SKELETON_SKULL
      G: GUNPOWDER
      P: PAPER
      F: FIREWORK_STAR
    result-amount: 3

Crafting Grid Visualization:

┌───┬───┬───┐
│   │ 💀│   │  💀 = Skeleton Skull
├───┼───┼───┤
│ 💥│ 📄│ 💥│  💥 = Gunpowder, 📄 = Paper
├───┼───┼───┤
│   │ ⭐│   │  ⭐ = Firework Star
└───┴───┴───┘
        ↓
   3× Skeleton Fireworks

Shapeless Recipe Example

recipes:
  merry_christmas:
    type: SHAPELESS
    ingredients:
      - GUNPOWDER
      - PAPER
      - RED_DYE
      - GREEN_DYE
    result-amount: 3

All Default Recipes

Pattern	Recipe Type	Key Ingredients	Amount
skeleton_face	Shaped	Skeleton Skull, Gunpowder, Paper	3
zombie_face	Shaped	Zombie Head, Gunpowder, Paper	3
santa_face	Shaped	Red Wool, White Wool, Gunpowder	3
christmas_tree	Shaped	Oak Leaves, Oak Log, Gunpowder	3
gift_box	Shapeless	Red Wool, Gold Nugget, Gunpowder	3
reindeer	Shaped	Leather, Gunpowder, Paper	3
dragon	Shaped	Ender Eye, Dragon Breath, Gunpowder	1
warden	Shaped	Sculk, Echo Shard, Gunpowder	1
wither	Shaped	Wither Skull ×3, Nether Star	1
villager	Shaped	Emerald, Gunpowder, Paper	3
pillager	Shaped	Crossbow, Gunpowder, Paper	3
wolf	Shaped	Bone, Gunpowder, Paper	3
axolotl	Shaped	Tropical Fish, Gunpowder, Paper	3
cat	Shaped	Cod, String, Gunpowder, Paper	3
enderman	Shaped	Ender Pearl, Gunpowder, Paper	3
panda	Shaped	Bamboo, Gunpowder, Paper	3
steve	Shaped	Player Head, Gunpowder, Paper	3
cake	Shaped	Cake, Egg, Gunpowder, Paper	3
merry_christmas	Shapeless	Red Dye, Green Dye, Gunpowder, Paper	3
happy_new_year	Shapeless	Gold Nugget, Clock, Gunpowder, Paper	3
happy_new_year_2026	Shapeless	Gold Ingot, Clock, Gunpowder, Paper	3

---

🔬 Technical Specifications

System Requirements

Requirement	Minimum	Recommended
Java Version	21	21+
Server Software	Paper 1.21.1	Paper 1.21.4
RAM	2GB	4GB+
CPU	2 cores	4+ cores

API Usage

Bukkit/Paper API	Usage
PersistentDataContainer	Store pattern IDs on items
NamespacedKey	Unique identifiers for PDC and recipes
Particle.DUST	Colored particle display
Particle.DustOptions	RGB color configuration
Adventure API	Modern text components
ShapedRecipe / ShapelessRecipe	Custom crafting
FireworkExplodeEvent	Intercept explosions

Data Storage

Data Type	Storage Method
Pattern definitions	config.yml (YAML)
Item pattern IDs	PDC on ItemStack
Recipe definitions	config.yml + Bukkit RecipeManager

Performance Metrics

Scenario	Particle Count	Performance Impact
Simple text (10 chars)	~350 particles	Minimal
Complex shape (15×15)	~150 particles	Minimal
Large text (50 chars)	~1,750 particles	Low
Multiple simultaneous	Varies	Medium

Particle Calculations

Text Pattern:
- Each character = 5×7 grid = up to 35 particles
- Character spacing = 1 pixel
- Line spacing = 2 pixels
- "Hello" = 5 chars × ~25 avg = ~125 particles

Shape Pattern:
- Depends on grid size and density
- 11×11 skeleton = ~80 particles
- 13×15 tree = ~100 particles

---

📥 Installation Guide

Step 1: Download Download PixelWorks-1.0.0.jar from the releases page.

Step 2: Install

Navigate to your plugins folder
cd /path/to/server/plugins/

 Place the JAR file
mv ~/Downloads/PixelWorks-1.0.0.jar ./

Step 3: Start Server

 Start or restart your server
./start.sh
 or
java -jar paper-1.21.4.jar

Step 4: Verify

Check console for success message
[PixelWorks] PixelWorks has been enabled!
[PixelWorks] Loaded 22 patterns.

 In-game verification
/pw list

Step 5: Configure (Optional)

 Edit configuration
nano plugins/PixelWorks/config.yml

 Reload in-game
/pw reload

File Structure After Installation

plugins/
└── PixelWorks/
    └── config.yml    # Main configuration file

---

🎨 Creating Custom Patterns

Creating a Text Pattern

Method 1: Command (Quick)

/pw create my_birthday text Happy Birthday!

Method 2: Config (Full Control)

texts:
  my_birthday:
    display: "Happy Birthday!"
    color: "#FF69B4"
    secondary-color: "#FFD700"
    scale: 0.35
    max-line-width: 20
    centered: true

Creating a Shape Pattern

Step 1: Design your ASCII art

Plan on paper or text editor:

   XXX      (3 wide)
  XXXXX     (5 wide)
 XXXXXXX    (7 wide)
XXXXXXXXX   (9 wide - max width)
   XXX      (trunk)

Step 2: Add to config

shapes:
  my_tree:
    color: "#228B22"
    secondary-color: "#8B4513"
    scale: 0.4
    primary-char: "X"
    secondary-char: "O"
    centered: true
    grid:
      - "   XXX   "
      - "  XXXXX  "
      - " XXXXXXX "
      - "XXXXXXXXX"
      - "   OOO   "

Step 3: Add a recipe (optional)

recipes:
  my_tree:
    type: SHAPELESS
    ingredients:
      - GUNPOWDER
      - PAPER
      - OAK_SAPLING
    result-amount: 3

Step 4: Reload and test

/pw reload
/pw test my_tree
/pw get my_tree

Shape Design Tips

Tip	Explanation
Start simple	Begin with 7×7 or smaller grids
Use spaces	Spaces are transparent (no particle)
Symmetry helps	Centered shapes look better
Test often	Use /pw test to preview
Two colors	Use O for details (eyes, patterns)
Consistent width	Pad lines with spaces for alignment

Multi-line Text

texts:
  server_rules:
    display: "Welcome to\\nMy Server\\nHave Fun!"
     Results in:
     Welcome to
    My Server
     Have Fun!

---

❓ FAQ

General Questions

Q: Does this work with Spigot?

A: PixelWorks is designed for Paper 1.21+. It may work on Spigot but is untested and unsupported.

Q: Can players grief with fireworks?

A: PixelWorks fireworks are purely visual (particles only). They don't cause damage or place blocks.

Q: Do patterns persist after server restart?

A: Yes! Pattern data is stored using PersistentDataContainer which persists across restarts.

Q: Can I use custom colors?

A: Yes! Use hex codes (#FF5500), RGB (255, 85, 0), or named colors.

Technical Questions

Q: Why don't I see the pattern?

Check:

• Pattern ID is correct (/pw list)
• View distance settings
• Particle settings in video options
• You have permission to use the firework

Q: How do I make patterns bigger?

Increase the scale value in config (e.g., 0.5 instead of 0.35)

Q: Can I disable vanilla firework explosions for all fireworks?

A: No, PixelWorks only affects its own custom fireworks. Vanilla fireworks work normally.

Q: Performance with many fireworks?

A: Each firework spawns 50-200 particles. With display-duration: 40, that's 2 seconds of particles. For large events, consider lower duration or fewer simultaneous fireworks.

Customization Questions

Q: Can I add my own shapes?

A: Yes! Add them to the shapes: section in config.yml. See "Creating Custom Patterns" above.

Q: What characters are supported for text?

A: A-Z, 0-9, and: . , ! ? - : ' # @ * / & (space)

Q: Can I use lowercase letters?

A: Letters are converted to uppercase for display. Lowercase in config works fine.

Q: Maximum text length?

A: No hard limit, but long text will wrap to multiple lines. Keep under 50 characters for best results.

---

📝 Changelog

Version 1.0.0 (Initial Release)

Features

• ✅ Particle rendering engine with vector mathematics
• ✅ Complete bitmap font (A-Z, 0-9, punctuation)
• ✅ 18 pre-built shape patterns
• ✅ 4 pre-built text patterns
• ✅ Custom shaped and shapeless recipes
• ✅ PersistentDataContainer item storage
• ✅ Full command system with tab completion
• ✅ Adventure API text components
• ✅ Player-facing rotation
• ✅ Multi-line text support
• ✅ Dual color system (primary + secondary)
• ✅ Configurable display duration
• ✅ Hot reload support

Included Patterns Shapes: Skeleton, Zombie, Santa, Christmas Tree, Gift Box, Reindeer, Dragon, Warden, Wither, Villager, Pillager, Wolf, Axolotl, Cat, Enderman, Panda, Steve, Cake

Texts: Merry Christmas, Happy New Year, Happy New Year 2026,

---

---


**Made with ❤️ for Minecraft servers everywhere**
**