** PixelWorks 插件 - 完整文档
? 概述
_____ _ _ __ __ _
| __ (_) | | \ \ / / | |
| |__) |__ _____| | \ \ /\ / /__ _ __| | _____
| ___/ \ \/ / _ \ | \ \/ \/ / _ \| '__| |/ / __|
| | | |> < __/ | \ /\ / (_) | | | <\__ \
|_| |_/_/\_\___|_| \/ \/ \___/|_| |_|\_\___/
Minecraft 自定义粒子烟花形状与文本
PixelWorks 是一款高品质的 Paper 插件,彻底革新了 Minecraft 中的烟花体验。它不再使用标准的烟花爆炸效果,而是在天空中展示由彩色粒子组成的精美 自定义形状 和 可读文本!
适用于:
- ? 节日活动(圣诞节、新年、万圣节)
- ? 服务器庆典(周年纪念、里程碑事件)
- ? 玩家奖励(成就解锁、VIP 特权)
- ? 创意建筑(灯光秀、装饰)
- ? 公告广播(在天空中显示服务器消息)
| 规格 |
详情 |
| 插件名称 |
PixelWorks |
| 版本 |
1.0.0 |
| API 版本 |
Paper 1.21+ |
| 兼容性 |
Minecraft 1.21.1 - 1.21.4 |
| Java 版本 |
Java 21+ |
| 依赖项 |
无(独立运行) |
✨ 核心功能
? 粒子渲染引擎
| 功能 |
描述 |
| 位图字体系统 |
完整的 A-Z、0-9 及标点符号渲染为 5×7 像素字符 |
| ASCII 艺术形状 |
在配置文件中通过简单的网格图案定义自定义形状 |
| 向量数学计算 |
使用旋转矩阵进行精确的 2D 到 3D 转换 |
| 面向玩家显示 |
图案会自动旋转以正对发射者 |
| 多行文本 |
自动为长消息进行换行处理 |
| 双颜色支持 |
主色和副色支持,实现更精细的设计 |
| 动画显示 |
粒子持续显示可配置的时长 |
? 自定义烟花物品
| 功能 |
描述 |
| PDC 存储 |
使用 PersistentDataContainer 存储图案数据(重启服务器后保留) |
| 自定义显示名称 |
带有图标的精美格式化名称 |
| 详细 Lore |
显示图案类型、内容和尺寸 |
| 堆叠友好 |
物品像原版烟花一样正确堆叠 |
| 无 NBT 问题 |
使用现代 PDC 系统,而非已弃用的 NBT 标签 |
?️ 合成配方系统
| 功能 |
描述 |
| 有形状配方 |
定义确切的原料位置 |
| 无形状配方 |
原料的任何排列均可生效 |
| 可配置结果 |
设置每次合成产出的烟花数量 |
| 热重载 |
添加新配方无需重启服务器 |
? 22 个预置图案
| 类别 |
图案 |
| 生物面部 (12) |
骷髅、僵尸、村民、掠夺者、末影人、监守者、凋灵、龙 |
| 动物 (6) |
狼、猫、美西螈、熊猫、驯鹿 |
| 玩家 |
史蒂夫 |
| 物体 (3) |
圣诞树、礼盒、蛋糕 |
| 文本 (4) |
Merry Christmas, Happy New Year, Happy New Year 2026, everETERNAL SMP |
⚡ 性能优化
| 功能 |
描述 |
| 缓存计算 |
图案点仅计算一次并缓存 |
| 异步粒子生成 |
非阻塞式粒子显示 |
| 可配置限制 |
控制粒子数量和生成速率 |
| 视距控制 |
仅为附近玩家生成粒子 |
? 工作原理
流程
┌─────────────────┐
│ 玩家合成或 │
│ 获得 │
│ PixelWorks │
│ 烟花 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 烟花包含 │
│ 带有 │
│ pattern_id │
│ 的 PDC 数据 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 玩家发射 │
│ 烟花 │
│ (右键点击) │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 烟花升空并 │
│ 爆炸 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 插件取消 │
│ 原版 │
│ 爆炸效果 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ ParticleEngine │
│ 从配置中 │
│ 加载图案 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 计算 │
│ 旋转角度以 │
│ 面向玩家 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 将 2D │
│ 点转换为 3D │
│ 世界坐标 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 在每个点 │
│ 生成 DUST │
│ 粒子 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 精美的 │
│ 图案 │
│ 展示完毕! │
└─────────────────┘
向量数学原理解析
插件使用 旋转矩阵 将 2D 网格坐标转换为 3D 世界位置:
已知:
- 原点(爆炸位置)
- 2D 网格点 (x, y)
- 偏航角(朝向方向)
- 缩放因子
计算:
1. 右向量 = (cos(yaw), 0, sin(yaw))
2. 上向量 = (0, 1, 0)
3. 世界位置 = 原点 + (右向量 × x × scale) + (上向量 × y × scale)
这确保了无论烟花在哪里爆炸,图案始终面向正确的方向。
? 命令
主命令: /pw (别名: /pixelworks, /fireworkart)
| 命令 |
描述 |
权限节点 |
/pw get <pattern_id> [amount] |
给自己一个自定义烟花 |
pixelworks.get |
/pw create <id> text <content> |
创建一个新的文本图案 |
pixelworks.create |
/pw list [text|shape] |
列出所有可用图案 |
pixelworks.command |
/pw info <pattern_id> |
查看详细的图案信息 |
pixelworks.command |
/pw test <pattern_id> |
在头顶测试渲染图案 |
pixelworks.admin |
/pw reload |
重新加载所有配置 |
pixelworks.reload |
/pw help |
显示命令帮助 |
pixelworks.command |
命令示例
获取16个骷髅脸烟花
/pw get skeleton_face 16
创建自定义生日祝福
/pw create birthday text Happy Birthday!
仅列出形状图案
/pw list shapes
查看关于龙形图案的信息
/pw info dragon
测试圣诞树图案
/pw test christmas_tree
编辑配置后重新加载
/pw reload
? 权限
| 权限 |
描述 |
默认值 |
pixelworks.command |
访问基础 /pw 命令 |
OP |
pixelworks.get |
使用 /pw get 获取烟花 |
OP |
pixelworks.create |
通过命令创建新图案 |
OP |
pixelworks.reload |
重载插件配置 |
OP |
pixelworks.use |
合成并使用自定义烟花 |
Everyone |
pixelworks.admin |
完全访问所有功能 |
OP |
权限层级
pixelworks.admin
├── pixelworks.command
├── pixelworks.get
├── pixelworks.create
├── pixelworks.reload
└── pixelworks.use
LuckPerms 示例
赋予玩家使用烟花的权限
/lp group default permission set pixelworks.use true
赋予 VIP 获取烟花的能力
/lp group vip permission set pixelworks.get true
赋予管理员完全访问权限
/lp group admin permission set pixelworks.admin true
⚙️ 配置
设置部分
settings:
粒子之间的间距(数值越小越密集,越大越分散)
推荐值:0.3 - 0.5
default-scale: 0.35
玩家可见粒子的最大距离
较高的值可能会影响性能
view-distance: 64
图案是否应旋转以朝向发射者?
true = 面向玩家,false = 始终朝北
face-player: true
每个尘埃粒子的大小
1.0 = 正常,0.5 = 小,2.0 = 大
particle-size: 1.0
每游戏刻生成多少粒子
数值越高显示越快,但可能导致卡顿
particles-per-tick: 100
图案保持可见的时间长度(20 刻 = 1 秒)
display-duration: 40
启用平滑的颜色过渡
use-color-transition: false
缩放视觉指南
| 缩放值 |
效果 |
最佳用途 |
| 0.2 |
非常密集、紧凑 |
小型精细形状 |
| 0.35 |
默认、平衡 |
大多数图案 |
| 0.5 |
分散、较大 |
文字、简单形状 |
| 0.75 |
非常大 |
巨型展示 |
| 1.0 |
最大分散 |
巨大的天空书写 |
颜色格式支持
| 格式 |
示例 |
描述 |
| 十六进制 |
FF5500 |
标准十六进制颜色 |
| 十六进制(无哈希) |
FF5500 |
同样有效 |
| RGB |
(255, 85, 0) |
RGB 元组 |
| RGB(无括号) |
255, 85, 0 |
同样有效 |
| 命名色 |
red |
预定义颜色名称 |
| Minecraft |
dark_purple |
MC 颜色名称 |
| 自定义 |
christmas_red |
插件自定义颜色 |
可用的命名颜色
标准: Minecraft: 自定义:
- 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
? 预设图案
文本图案 (4)
| ID |
显示文本 |
颜色 |
merry_christmas |
Merry Christmas |
红色 + 绿色 |
happy_new_year |
Happy New Year |
金色 + 白色 |
happy_new_year_2026 |
Happy New Year 2026 |
金色 + 红色 |
evereternal_smp |
everETERNAL SMP |
紫色 + 蓝色 |
形状图案 (18)
生物面部
| ID |
描述 |
颜色 |
大小 |
skeleton_face |
骷髅头骨 |
白色 + 黑色 |
11×11 |
zombie_face |
僵尸头部 |
绿色 + 黑色 |
11×11 |
villager |
带鼻子的村民脸 |
棕褐色 + 绿色 |
11×11 |
pillager |
带愤怒眼睛的掠夺者 |
灰色 + 黑色 |
11×11 |
enderman |
带紫色眼睛的末影人 |
黑色 + 品红 |
11×11 |
warden |
深暗之地的监守者 |
深青色 + 青色 |
13×12 |
wither |
三头凋灵 |
黑色 + 灰色 |
19×10 |
dragon |
末影龙 |
紫色 + 品红 |
17×12 |
动物
| ID |
描述 |
颜色 |
大小 |
wolf |
狼/狗脸 |
银色 + 白色 |
11×11 |
cat |
橙色虎斑猫 |
橙色 + 黑色 |
11×10 |
axolotl |
粉色美西螈 |
粉色 + 亮粉红 |
11×10 |
panda |
带黑眼圈的大熊猫 |
白色 + 黑色 |
11×10 |
reindeer |
带鹿角的驯鹿 |
棕色 + 红色 |
11×11 |
玩家与物体
| ID |
描述 |
颜色 |
大小 |
steve |
Steve 玩家头颅 |
棕褐色 + 棕色 |
11×11 |
christmas_tree |
装饰过的树 |
绿色 + 金色 |
13×15 |
gift_box |
系着丝带的礼物盒 |
红色 + 金色 |
11×10 |
cake |
带蜡烛的生日蛋糕 |
奶油色 + 红色 |
11×9 |
视觉预览 (ASCII)
骷髅脸
XXXXXXX
XXXXXXXXX
XXXXXXXXXXX
XXX OOO XXX ← 黑色眼睛
XXX OOO XXX
XXXXXXXXXXX
XXXXXXXXXXX
XX XXXXX XX
XXX XXX ← 嘴巴
XX X X XX
XXXXXXX
圣诞树
O ← 金色星星
XXX
XXXXX
XXXXXXX
XXXXXXXXX
XXXXX
XXXXXXX
XXXXXXXXX
XXXXXXXXXXX
XXXXXXX
XXXXXXXXX
XXXXXXXXXXX
XXXXXXXXXXXXX
OOO ← 树干
OOO
龙
X X ← 翅膀尖端
XX XXXXX XX
X XXXXXXX X
XXX O XXX ← 眼睛
XXXXXXXXX
XXXXXXXXXXX
XXXXXXXXXXXXX
XX XXXXX XX
XXXXX
XX XX
XX XX
XXX XXX ← 爪子
? 自定义配方
配方类型
| 类型 |
描述 |
| SHAPED |
原料必须放置在特定位置 |
| SHAPELESS |
原料的任何排列均可 |
有形状配方示例
recipes:
skeleton_face:
type: SHAPED
pattern:
- " S " 第 1 行:中间是骷髅头
- "GPG" 第 2 行:火药、纸、火药
- " F " 第 3 行:中间是烟火之星
ingredients:
S: SKELETON_SKULL
G: GUNPOWDER
P: PAPER
F: FIREWORK_STAR
result-amount: 3
合成网格可视化:
┌───┬───┬───┐
│ │ ?│ │ ? = 骷髅头颅
├───┼───┼───┤
│ ?│ ?│ ?│ ? = 火药, ? = 纸
├───┼───┼───┤
│ │ ⭐│ │ ⭐ = 烟火之星
└───┴───┴───┘
↓
3× 骷髅烟花
无形状配方示例
recipes:
merry_christmas:
type: SHAPELESS
ingredients:
- GUNPOWDER
- PAPER
- RED_DYE
- GREEN_DYE
result-amount: 3
所有默认配方
| 模式 |
配方类型 |
关键材料 |
数量 |
skeleton_face |
有形状 (Shaped) |
骷髅头颅, 火药, 纸 |
3 |
zombie_face |
有形状 (Shaped) |
僵尸头颅, 火药, 纸 |
3 |
santa_face |
有形状 (Shaped) |
红色羊毛, 白色羊毛, 火药 |
3 |
christmas_tree |
有形状 (Shaped) |
橡树叶, 橡木原木, 火药 |
3 |
gift_box |
无形状 (Shapeless) |
红色羊毛, 金粒, 火药 |
3 |
reindeer |
有形状 (Shaped) |
皮革, 火药, 纸 |
3 |
dragon |
有形状 (Shaped) |
末影之眼, 龙息, 火药 |
1 |
warden |
有形状 (Shaped) |
幽匿块, 回声碎片, 火药 |
1 |
wither |
有形状 (Shaped) 凋灵头颅 ×3, 下界之星 |
1 |
|
villager |
有形状 (Shaped) |
绿宝石, 火药, 纸 |
3 |
pillager |
有形状 (Shaped) |
弩, 火药, 纸 |
3 |
wolf |
有形状 (Shaped) |
骨头, 火药, 纸 |
3 |
axolotl |
有形状 (Shaped) |
热带鱼, 火药, 纸 |
3 |
cat |
有形状 (Shaped) |
鳕鱼, 线, 火药, 纸 |
3 |
enderman |
有形状 (Shaped) |
末影珍珠, 火药, 纸 |
3 |
panda |
有形状 (Shaped) |
竹子, 火药, 纸 |
3 |
steve |
有形状 (Shaped) |
玩家头颅, 火药, 纸 |
3 |
cake |
有形状 (Shaped) |
蛋糕, 鸡蛋, 火药, 纸 |
3 |
merry_christmas |
无形状 (Shapeless) |
红色染料, 绿色染料, 火药, 纸 |
3 |
happy_new_year |
无形状 (Shapeless) |
金粒, 时钟, 火药, 纸 |
3 |
happy_new_year_2026 |
无形状 (Shapeless) |
金锭, 时钟, 火药, 纸 |
3 |
? 技术规格
系统需求
| 需求 |
最低配置 |
推荐配置 |
| Java 版本 |
21 |
21+ |
| 服务端软件 |
Paper 1.21.1 |
Paper 1.21.4 |
| 内存 (RAM) |
2GB |
4GB+ |
| CPU |
2 核 |
4+ 核 |
API 用法
| Bukkit/Paper API |
用途 |
PersistentDataContainer |
在物品上存储模式 ID |
NamespacedKey |
PDC 和配方的唯一标识符 |
Particle.DUST |
彩色粒子显示 |
Particle.DustOptions |
RGB 颜色配置 |
Adventure API |
现代文本组件 |
ShapedRecipe / ShapelessRecipe |
自定义合成 |
FireworkExplodeEvent |
拦截爆炸事件 |
数据存储
| 数据类型 |
存储方式 |
| 模式定义 |
config.yml (YAML) |
| 物品模式 ID |
ItemStack 上的 PDC |
| 配方定义 |
config.yml + Bukkit RecipeManager |
性能指标
| 场景 |
粒子数量 |
性能影响 |
| 简单文本 (10 字符) |
~350 粒子 |
极小 |
| 复杂形状 (15×15) |
~150 粒子 |
极小 |
| 大文本 (50 字符) |
~1,750 粒子 |
低 |
| 多个同时存在 |
视情况而定 |
中等 |
粒子计算
文本模式:
- 每个字符 = 5×7 网格 = 最多 35 个粒子
- 字符间距 = 1 像素
- 行间距 = 2 像素
- "Hello" = 5 字符 × 平均 ~25 = ~125 个粒子
形状模式:
- 取决于网格大小和密度
- 11×11 骷髅 = ~80 个粒子
- 13×15 树 = ~100 个粒子
? 安装指南
步骤 1:下载
从发布页面下载 PixelWorks-1.0.0.jar。
步骤 2:安装
导航至你的插件文件夹
cd /path/to/server/plugins/
放置 JAR 文件
mv ~/Downloads/PixelWorks-1.0.0.jar ./
步骤 3:启动服务器
启动或重启服务器
./start.sh
或者
java -jar paper-1.21.4.jar
步骤 4:验证
检查控制台是否出现成功消息
[PixelWorks] PixelWorks has been enabled!
[PixelWorks] Loaded 22 patterns.
游戏内验证
/pw list
步骤 5:配置(可选)
编辑配置文件
nano plugins/PixelWorks/config.yml
在游戏内重载
/pw reload
安装后的文件结构
plugins/
└── PixelWorks/
└── config.yml # 主配置文件
? 创建自定义模式
创建文本模式
方法 1:命令(快速)
/pw create my_birthday text Happy Birthday!
方法 2:配置文件(完全控制)
texts:
my_birthday:
display: "Happy Birthday!"
color: "#FF69B4"
secondary-color: "#FFD700"
scale: 0.35
max-line-width: 20
centered: true
创建形状模式
步骤 1:设计你的 ASCII 艺术
在纸上或文本编辑器中规划:
XXX (宽 3)
XXXXX (宽 5)
XXXXXXX (宽 7)
XXXXXXXXX (宽 9 - 最大宽度)
XXX (树干)
步骤 2:添加到配置文件
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 "
步骤 3:添加配方(可选)
recipes:
my_tree:
type: SHAPELESS
ingredients:
- GUNPOWDER
- PAPER
- OAK_SAPLING
result-amount: 3
步骤 4:重载并测试
/pw reload
/pw test my_tree
/pw get my_tree
形状设计技巧
| 提示 |
说明 |
| 从简单开始 |
使用 7×7 或更小的网格起步 |
| 利用空格 |
空格是透明的(不生成粒子) |
| 对称更有美感 |
居中的形状看起来更好 |
| 频繁测试 |
使用 /pw test 进行预览 |
| 双色系统 |
使用 O 表示细节(如眼睛、图案) |
| 保持宽度一致 |
用空格填充行以确保对齐 |
多行文本
texts:
server_rules:
display: "欢迎来到\\n我的服务器\\n玩得开心!"
结果为:
欢迎来到
我的服务器
玩得开心!
❓ 常见问题
通用问题
问:它支持 Spigot 吗?
答:PixelWorks 专为 Paper 1.21+ 设计。它可能在 Spigot 上运行,但未经测试且不受支持。
问:玩家能用烟花造成破坏(griefing)吗?
答:PixelWorks 的烟花仅用于视觉效果(仅有粒子)。它们不会造成伤害或放置方块。
问:服务器重启后图案会保留吗?
答:是的!图案数据使用 PersistentDataContainer 存储,重启后依然保留。
问:我能使用自定义颜色吗?
答:可以!使用十六进制代码(#FF5500)、RGB(255, 85, 0)或命名颜色。
技术问题
问:为什么我看不到图案?
请检查:
- 图案 ID 是否正确(
/pw list)
- 视距设置
- 视频选项中的粒子设置
- 您是否拥有使用烟花的权限
问:我如何制作更大的图案?
增加配置中的 scale 值(例如,将 0.35 改为 0.5)
问:我可以禁用所有烟花的原版爆炸效果吗?
答:不可以,PixelWorks 仅影响其自定义烟花。原版烟花正常工作。
问:大量烟花时的性能表现如何?
答:每个烟花会生成 50-200 个粒子。如果 display-duration: 40,则持续 2 秒。对于大型活动,建议降低持续时间或减少同时存在的烟花数量。
自定义问题
问:我可以添加自己的形状吗?
答:可以!将它们添加到 config.yml 中的 shapes: 部分。参见上方的“创建自定义图案”。
问:文本支持哪些字符?
答:A-Z、0-9,以及:. , ! ? - : ' # @ * / & (空格)
问:我可以使用小写字母吗?
答:字母在显示时会自动转换为大写。配置中使用小写是可以的。
问:最大文本长度是多少?
答:没有硬性限制,但长文本会自动换行成多行。为了最佳效果,请保持在 50 个字符以内。
? 更新日志
版本 1.0.0(初始发布)
功能
- ✅ 基于向量数学的粒子渲染引擎
- ✅ 完整的位图字体(A-Z、0-9、标点符号)
- ✅ 18 种预构建形状图案
- ✅ 4 种预构建文本图案
- ✅ 自定义形状和无需形状的合成配方
- ✅ PersistentDataContainer 物品存储
- ✅ 完整的命令系统与 Tab 补全
- ✅ Adventure API 文本组件
- ✅ 面向玩家的旋转功能
- ✅ 多行文本支持
- ✅ 双色系统(主色 + 辅色)
- ✅ 可配置的显示持续时间
- ✅ 热重载支持
包含的图案
形状: Skeleton, Zombie, Santa, Christmas Tree, Gift Box, Reindeer, Dragon, Warden, Wither, Villager, Pillager, Wolf, Axolotl, Cat, Enderman, Panda, Steve, Cake
文本: Merry Christmas, Happy New Year, Happy New Year 2026,
---
**为世界各地的 Minecraft 服务器 ❤️ 打造**
** 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**
**
评论 0
登录后参与评分
还没有评论,来抢沙发吧