** 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**
**

PixelWorks

📖About PixelWorks