PixelWorks

** PixelWorks Plugin - Complete Documentation

🎆 Overview

```

---

| __ (_) | | / / | | | |__) |__ _____| | / / /__ _ __| | _____ | ___/ / / | / / / | '__| |/ / __| | | | |> < __/ | / / (_) | | | <__ || |/_/____|_| / / ___/|| ||____/ ```

Custom Particle Firework Shapes & Text for Minecraft

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

Perfect for: - 🎄 Announcements (Christmas, New Year, Halloween) - 🎉 Announcements (Anniversaries, Milestones) - 🏆 Announcements (Achievement unlocks, VIP perks) - 🎨 Announcements (Light shows, Decorations) - 📢 Announcements (Server messages in the sky)

| Specification | Details | |--------------|---------| | Dependencies | PixelWorks | | Dependencies | 1.0.0 | | Dependencies | Paper 1.21+ | | Dependencies | Minecraft 1.21.1 - 1.21.4 | | Dependencies | Java 21+ | | Dependencies | None (Standalone) |

---

✨ Key Features

🎨 Particle Rendering Engine

| Feature | Description | |---------|-------------| | Animated Display | Complete A-Z, 0-9, and punctuation rendered as 5×7 pixel characters | | Animated Display | Define custom shapes using simple grid patterns in config | | Animated Display | Precise 2D to 3D transformation with rotation matrices | | Animated Display | Patterns automatically rotate to face the launching player | | Animated Display | Automatic word wrapping for long messages | | Animated Display | Primary and secondary colors for detailed designs | | Animated Display | Particles persist for configurable duration |

🚀 Custom Firework Items

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

🛠️ Recipe System

| Feature | Description | |---------|-------------| | Hot Reload | Define exact ingredient positions | | Hot Reload | Any arrangement of ingredients works | | Hot Reload | Set how many fireworks each craft produces | | Hot Reload | Add new recipes without server restart |

📦 22 Pre-Built Patterns

| Category | Patterns | |----------|----------| | Text (4) | Skeleton, Zombie, Villager, Pillager, Enderman, Warden, Wither, Dragon | | Text (4) | Wolf, Cat, Axolotl, Panda, Reindeer | | Text (4) | Steve | | Text (4) | Christmas Tree, Gift Box, Cake | | Text (4) | Merry Christmas, Happy New Year, Happy New Year 2026, everETERNAL SMP |

⚡ Performance Optimized

| Feature | Description | |---------|-------------| | View Distance | Pattern points calculated once then cached | | View Distance | Non-blocking particle display | | View Distance | 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

```bash 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

```bash 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

```yaml 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 | |------|-------------| | SHAPELESS | Ingredients must be in specific positions | | SHAPELESS | Any arrangement of ingredients works |

Shaped Recipe Example

```yaml 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

```yaml 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 ```bash 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 ```bash Start or restart your server ./start.sh or java -jar paper-1.21.4.jar ```

Step 4: Verify ```bash Check console for success message [PixelWorks] PixelWorks has been enabled! [PixelWorks] Loaded 22 patterns.

In-game verification /pw list ```

Step 5: Configure (Optional) ```bash 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) ```bash /pw create my_birthday text Happy Birthday! ```

Method 2: Config (Full Control) ```yaml 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 ```yaml 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) ```yaml recipes: my_tree: type: SHAPELESS ingredients: - GUNPOWDER - PAPER - OAK_SAPLING result-amount: 3 ```

Step 4: Reload and test ```bash /pw reload /pw test my_tree /pw get my_tree ```

Shape Design Tips

| Tip | Explanation | |-----|-------------| | Consistent width | Begin with 7×7 or smaller grids | | Consistent width | Spaces are transparent (no particle) | | Consistent width | Centered shapes look better | | Consistent width | Use `/pw test` to preview | | Consistent width | Use O for details (eyes, patterns) | | Consistent width | Pad lines with spaces for alignment |

Multi-line Text

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