FAQ

Organised as symptom → cause → fix. First step for any of them: set debug: true and restart once — the log usually answers it.

Behaviour

The creeper exploded but the terrain is intact

That is the design. When the roll hits, the plugin calls event.setCancelled(true) on EntityExplodeEvent, the event that controls block destruction — the ground stays untouched while the sound and the firework play.

To let the explosion affect blocks again, see Control which blocks break. Lowering confetti_chance also lets some creepers behave normally again.

I lit a creeper but no firework appeared

  • Check that confetti_chance is not 0;
  • check that the build matches the server (Folia → folia build, everything else → bukkit build);
  • check the console for errors other than [Alias] and confirm plugin enabled successfully appeared;
  • turn on debug: true: the log prints the loaded styles and chances — an empty list means the config is broken.

The firework is tiny, or it bursts at ground level

Flight time (power) is fixed at 0, so the firework bursts immediately one block above the creeper instead of climbing. That is deliberate: a rising rocket does not fit combat pacing and gets blocked by terrain.

To make it more visible, switch type to BALL_LARGE and enable flicker or trail.

Can it apply to only some worlds

There is no built-in world filter. The world name is available in the listener, so it is a one-line change — see Restrict to specific worlds.

Commands

/cc says unknown command

Three possibilities, in order:

  1. The alias is taken by another plugin. The console shows [Alias] /cc is already registered by another plugin - skipped. Use /creeperconfetti help, or set command-aliases.cc to false to silence it.
  2. The alias is disabled in the config. Check command-aliases.enabled and the per-alias flags, then run /creeperconfetti reload (the alias form is what you are trying to fix).
  3. Missing permission. That produces "You do not have permission", not an unknown command. Grant creeperconfetti.command.

Subcommands are listed but denied when run

Permissions are checked twice: first creeperconfetti.command, then the sub-permission. With only the base node the help list is populated but execution is refused. Add creeperconfetti.command.effect and friends.

/cc gui from the console fails

The GUI, effect add, effect set and effect preview need a player context (held item, open inventory), so the console gets "Only players can use this command". Expected behaviour.

/cc reload did not apply my change

Reload re-reads the config, styles, language and aliases, but it does not re-register the root command and does not run migration. A full restart is required when:

  • you replaced the jar;
  • you edited config-version;
  • you added a language file (new files are copied at startup).

Configuration

The chances do not add up to 100

firework_chances holds weights, not percentages, and they are normalised on load. What /cc effect chance shows is the effective value, and it always totals 100 (rounding drift of ±0.01 is pushed onto the largest entry).

If the total looks wrong, the usual cause is a style that was skipped because all its colours were invalid — its weight line still exists but the style does not, and such lines are ignored.

A style in the config is missing from the list

A style is dropped for exactly one reason: every effect inside it failed to parse. Typically a misspelled colour name (for example GOLD instead of ORANGE/YELLOW) or an RGB map with a missing channel. Turn on debug: true, restart, and compare the logged style names against the config.

The config changed after upgrading

That is the migration running. The old file is in plugins/CreeperConfettiPro/backups/config-backup-<timestamp>.yml, untouched. Migration only adds new keys and never overwrites existing values — but a very old config (version 0) has its confetti_effect converted into a style named default.

To roll back: stop the server, copy the backup over config.yml, start again. Note the version number is old too, so the next start migrates once more.

My styles turned into weird == maps

Normal. After any command or GUI edit the plugin rewrites that section using Bukkit's serialised format. It still loads correctly, it is just not pleasant to hand-edit. To go back to the readable form, stop the server and replace the block with the hand-written example — see Configuration.

Language

The plugin stays in English

language: auto relies on a GeoIP lookup of the server's public IP. These environments fail and fall back to English:

  • LAN-only or offline servers;
  • hosts that block outbound HTTP to foreign endpoints;
  • all six endpoints timing out (6 s total budget).

Fix: set language to zh_cn (or whatever you need) and restart, or run /cc language set zh_cn. If the log contains [GeoIP] All region APIs failed, falling back to English. that was the cause.

Console output is garbled

The language files are UTF-8. Garbled text almost always means the Windows console code page is not UTF-8. Add a line to the start script:

chcp 65001
java -Dfile.encoding=UTF-8 -jar server.jar nogui

On Linux make sure LANG is a *.UTF-8 locale. In-game chat is unaffected.

I want to translate or reword things

Edit plugins/CreeperConfettiPro/languages/<code>.yml and run /cc language reload. Missing keys fall back to English, so you can translate only what matters. Details in Languages.

Other

Does it hurt performance with many creepers

Barely. Each trigger spawns one firework entity and sets its FireworkMeta; there is no polling task, no repeating scheduler, no always-on listener cost. The style table is a LinkedHashMap and the draw is an O(n) scan with n typically single digits.

What actually costs performance is the fireworks themselves: a hundred simultaneous explosions is a client rendering problem far more than a server logic problem. Lowering confetti_chance is the effective lever.

Does the plugin phone home

It uses bStats (pluginId 29666), which collects anonymous data: server version, player count bracket, plugin version. No player names, IPs or chat. It can be disabled globally in plugins/bStats/config.yml.

Folia fails at startup

Check two things:

  1. you are using CreeperConfettiPro-4.2.0-folia.jar, not the bukkit one;
  2. Java is 17 or newer — the Folia build targets 17 and throws UnsupportedClassVersionError below that.

What happens if I install both jars

They share a plugin name, so the server loads one and ignores or overwrites the other — unpredictable either way. Install one. If you already mixed them up, delete the extra jar and remove plugins/CreeperConfettiPro/ before starting again.

v

Still stuck? Post the full startup log with debug enabled, your config.yml, and the server type and version — that is usually enough to pin it down.

常见问题

按「症状 → 原因 → 处理」组织。遇到问题的第一步：把 debug: true 打开重启一次，大部分答案会直接写在日志里。

行为相关

苦力怕炸了，但地面完好无损

这不是 bug，是设计。命中概率时插件对 EntityExplodeEvent 执行 event.setCancelled(true)，这个事件负责方块破坏，因此地形保持原样，只播放音效和烟花。

如果想让爆炸重新影响方块，见 控制哪些方块被破坏。降低 confetti_chance 也能让一部分苦力怕恢复原版行为。

点燃苦力怕了，但没有烟花

  • 确认 confetti_chance 不是 0；
  • 确认服务端类型与分支匹配（Folia 用 folia 分支，其它用 bukkit 分支）；
  • 确认控制台没有 [Alias] 之外的报错，并且 plugin enabled successfully 出现过；
  • 打开 debug: true，日志会打印加载到的样式列表与概率——样式列表为空说明配置被改坏了。

烟花很小，或者贴在地面上就炸了

烟花飞行时间（power）在插件里固定为 0，所以它会在苦力怕头顶一格的位置立刻炸开，不会升空。这是刻意的：升空的烟花跟不上战斗节奏，也容易被地形挡住。

想让观感更明显，把 type 换成 BALL_LARGE，并开启 flicker 或 trail。

能否只对某些世界生效

当前版本没有内置世界白名单。事件监听里可以直接按世界名过滤，改动只有一行，见 只对指定世界生效。

指令相关

/cc 提示未知指令或找不到命令

三种可能，按顺序排查：

  1. 别名被其它插件占用。控制台会有一条 [Alias] /cc is already registered by another plugin - skipped. 警告。此时用完整指令 /creeperconfetti help 即可，或者把 command-aliases.cc 设为 false 消除警告。
  2. 别名被配置关闭。检查 command-aliases.enabled 与对应项是否为 true，改完用完整指令执行 /creeperconfetti reload。
  3. 没有权限。缺权限时提示的是「您没有权限使用此命令」，不是未知指令。给玩家 creeperconfetti.command。

子命令能看到，但执行时提示没权限

权限是两级判断：先要有 creeperconfetti.command，再要有对应子权限。只给了前者时，帮助菜单里看得到条目，执行会被拒。补齐 creeperconfetti.command.effect 等子节点即可。

控制台执行 /cc gui 报错

界面、effect add、effect set、effect preview 都需要玩家上下文（要读主手物品、要打开背包），控制台执行会提示「只有玩家可以使用此命令」。这是预期行为。

/cc reload 之后改动没生效

重载会重新读取 config.yml、样式、语言与别名，但不会重新注册主指令、也不会执行配置迁移。以下情况必须完整重启：

  • 更换了 jar；
  • 手动修改了 config-version；
  • 新增了语言文件（新文件在启动时才会被复制）。

配置相关

概率加起来不是 100

firework_chances 里写的是权重，不是百分比，插件加载时会自动归一化。用 /cc effect chance 查看的才是最终生效值，它们一定是 100（±0.01 的四舍五入误差会被自动补到最大项上）。

如果你看到合计不对，通常是：firework_styles 里有样式因为颜色全部无效而被跳过，权重行还在但样式不存在——这类行会被忽略。

配置里写了样式，但列表里没有

整个样式被丢弃只有一种原因：它包含的所有效果都解析失败。常见于颜色名拼错（例如写成 GOLD 而不是 ORANGE/YELLOW），或 RGB 映射缺了某个分量。打开 debug: true 重启，日志会打印实际加载到的样式名，与配置逐个对照即可。

升级插件后配置文件变了

说明触发了配置迁移。旧文件已经备份在 plugins/CreeperConfettiPro/backups/config-backup-<时间戳>.yml，内容原样保留。迁移过程只补新键，不覆盖已有值，但如果你的配置结构非常老（版本 0），旧的 confetti_effect 会被转换成名为 default 的样式。

要回滚：停服 → 用备份覆盖 config.yml → 启动。注意回滚后版本号也是旧的，下次启动会再次迁移。

config.yml 里的样式变成了带 == 的奇怪格式

正常现象。用指令或 GUI 修改过样式后，插件会用 Bukkit 的序列化格式重写这一段。它仍然能被正确加载，只是不再适合手写。想恢复手写格式，停服后把整段替换成手写示例即可，详见 配置文件。

语言相关

语言一直是英文

language: auto 依赖 GeoIP 查询服务器公网 IP，以下环境会失败并回退到英文：

  • 内网或离线服务器；
  • 机房屏蔽了境外 HTTP 请求；
  • 6 个接口全部超时（整体上限 6 秒）。

解决办法很直接：把 language 改成 zh_cn（或你需要的代码），重启或 /cc language set zh_cn。日志里出现 [GeoIP] All region APIs failed, falling back to English. 就说明是这个原因。

控制台中文乱码

语言文件本身是 UTF-8。乱码几乎都出现在 Windows 服务端控制台，原因是终端代码页不是 UTF-8。启动脚本里加一行即可：

chcp 65001
java -Dfile.encoding=UTF-8 -jar server.jar nogui

Linux 下确认 LANG 环境变量是 *.UTF-8。游戏内聊天不受影响。

想自己翻译或改文案

直接编辑 plugins/CreeperConfettiPro/languages/<代码>.yml，保存后执行 /cc language reload。缺失的键会自动回退英文，所以可以只改你在意的部分。细节见 多语言。

其它

大量苦力怕同时爆炸会影响性能吗

开销很小：每次触发只生成一个烟花实体，样式只是设置 FireworkMeta，没有额外的调度循环、没有定时任务、没有常驻监听开销。样式表在内存里是 LinkedHashMap，随机抽取是 O(n) 的线性遍历（n = 样式数量，通常个位数）。

真正吃性能的是烟花本身：上百个烟花同时爆炸时，客户端渲染压力远大于服务端逻辑。这种情况下把 confetti_chance 调低更有效。

插件会上报数据吗

使用 bStats（pluginId 29666），收集的是匿名统计：服务端版本、在线人数区间、插件版本等，不含玩家名、IP 或聊天内容。可以在 plugins/bStats/config.yml 里全局关闭。

Folia 上启动就报错

检查两点：

  1. 用的是 CreeperConfettiPro-4.2.0-folia.jar，不是 bukkit 版；
  2. Java 版本 ≥ 17（Folia 分支以 Java 17 为目标编译，低版本会直接 UnsupportedClassVersionError）。

两个 jar 都放进去了会怎样

插件名相同，服务端只会加载其中一个，另一个会被忽略或覆盖，行为不可预测。只装一个。如果之前装错过，删掉多余的 jar 并删除 plugins/CreeperConfettiPro/ 后重新启动最稳妥。

v

以上都没解决？把 debug 打开后的完整启动日志、config.yml 内容、服务端类型与版本一起贴出来，基本能一眼定位。