Styles & chances

A "style" is a set of firework effects plus a weight. You can define as many styles as you want, and every confetti explosion draws one of them at random.

Style schema

Styles live under firework_styles. The key is the style name — pick anything, including spaces if you quote it:

firework_styles:
  <style name>:
    type: BALL              # shape
    flicker: true           # twinkle
    trail: false            # trail
    colors:                 # main colours, at least one
      - RED
      - "#FFD700"
    fade-colors:            # fade colours, optional
      - ORANGE

Field	Required	Default	Notes
`type`	no	`BALL`	Firework shape — configurable per style; unknown values fall back to `BALL`
`flicker`	no	`false`	Vanilla "twinkle"
`trail`	no	`false`	Vanilla "trail"
`colors`	yes	—	Main colour list; a single value is also accepted
`fade-colors`	no	empty	Colours the burst fades into

Accepted key spellings

The parser is forgiving, so old configs and snippets copied from other servers just work:

Canonical	Also accepted
`colors`	`color`
`fade-colors`	`fade_colors`, `fade`
`colors: [RED, BLUE]`	`colors: RED` (plain string)

Firework shapes

The shape is not a fixed list baked into the plugin — it is a per-style setting. Whatever you put in type is handed to Bukkit's FireworkEffect.Type, so each style can use a different shape, and you can mix them freely in one config.

Value	In game	Works well for
`BALL`	Classic small sphere	Anything; best with several colours
`BALL_LARGE`	Large sphere, wider spread	Viewing from a distance, big celebrations
`STAR`	Star with spikes	Paired with flicker
`BURST`	Burst that scatters outward	Multi-colour fades
`CREEPER`	Creeper face	Themed easter eggs, green palettes

Want a different look per situation? Give each style its own shape — e.g. CREEPER for the rare one, BALL_LARGE for the common one. The plugin picks the shape with the style, not globally.

CREEPER is a valid FireworkEffect.Type even though vanilla only produces it from specific rockets, so it can be used directly in the config.

Colour formats

Three formats, freely mixed inside one list.

1. Colour names

Name	Hex	Name	Hex
`RED`	#FF0000	`AQUA`	#00FFFF
`ORANGE`	#FFA500	`TEAL`	#008080
`YELLOW`	#FFFF00	`BLUE`	#0000FF
`LIME`	#00FF00	`NAVY`	#000080
`GREEN`	#008000	`PURPLE`	#800080
`OLIVE`	#808000	`FUCHSIA`	#FF00FF
`MAROON`	#800000	`SILVER`	#C0C0C0
`GRAY` / `GREY`	#808080	`WHITE`	#FFFFFF
`BLACK`	#000000	Names are case-insensitive: `red` = `RED`

2. Hex

colors:
  - "#FFD700"    # six digits, # optional
  - "#f00"       # three digits = #FF0000
  - "1E90FF"     # without # also works

Six digits are read as RRGGBB, three as RGB with each digit duplicated. In YAML a value starting with # must be quoted, otherwise it becomes a comment.

3. RGB map

colors:
  - RED: 255
    GREEN: 100
    BLUE: 0

All three channels are required and must be 0–255, otherwise the colour is dropped. Shorthand keys work too:

colors:
  - rgb: "#FF6400"
  - value: 16737843   # decimal integer, same as #FF6403

Invalid colours are dropped silently. A typo in a colour name does not raise an error — it just does not apply. If every colour in an effect is invalid the effect is skipped, and if every effect in a style is skipped the style never loads: it will not show up in /cc effect list and takes no share of the chances.

Several effects in one style

A style value can be a list. Each entry is a complete effect, and they all play in the same explosion — handy for a main burst plus accents.

firework_styles:
  grand_finale:
    - type: BALL_LARGE
      flicker: true
      trail: true
      colors:
        - "#FFD700"
        - WHITE
      fade-colors:
        - ORANGE
    - type: STAR
      colors:
        - "#00E5FF"
      fade-colors:
        - BLUE
    - type: BURST
      trail: true
      colors:
        - FUCHSIA
        - PURPLE

Each list entry is an effect, not a style. All effects in the list share the style's single weight — they are not drawn separately.

Weights & auto-compensation

Numbers in firework_chances are weights, not percentages. On load the plugin normalises them so the total is always exactly 100%.

firework_chances:
  classic: 4      # 4/10 = 40%
  starburst: 3    # 3/10 = 30%
  rainbow: 2      # 2/10 = 20%
  creeper: 1      # 1/10 = 10%

Situation	What the plugin does
Weights do not total 100	Scales them proportionally back to 100%
A style has no weight	Gets the average of the defined weights
No weights at all	Every style gets an equal share
All weights are 0	Falls back to uniform random
Rounding leaves 99.99 or 100.01	The difference is added to the largest style
An unknown style name is listed	That line is ignored

Pinning one style with a command

/cc effect chance <style> <percent> pins that style to an exact value and redistributes the rest proportionally:

/cc effect chance classic 50

Starting from 40 / 30 / 20 / 10 the result is 50 / 25 / 16.67 / 8.33 — the other three keep their relative proportions and the total stays at 100.

To go back to an even split use /cc effect chance reset.

Chances are displayed with two decimals. Anything changed through a command or the GUI is written back to config.yml immediately — no reload needed.

Capture a style in game

Writing colours by hand works, but it is easier to build the firework you like with vanilla items and let the plugin read it.

Get a rocket that has an effect

The plugin reads the FireworkMeta of the item in your main hand, so the rocket must carry at least one explosion effect — a plain flight-duration rocket does not count. NBT form for 1.20.4 and older:
```
/give @s firework_rocket{Explosion:{Type:3,Colors:[I;16711680,16777215],Flicker:1,Trail:0}} 1
```
From 1.20.5 on, the component form:
```
/give @s firework_rocket[firework_explosion={shape:"star",colors:[16711680,16777215],has_twinkle:true}] 1
```
The syntax changes between versions; if neither line works, use an item generator for your version. The plugin only cares that the held rocket has an effect — not how it was made.
Hold it and run the command
```
/cc effect add my_style      # add; a duplicate name is rejected
/cc effect set my_style      # overwrite an existing style
```
On success it immediately previews the style at your feet and writes it to the config. Without a name it becomes style1, style2, …
Check the result
```
/cc effect list
```
The list shows each style's effect count and current chance.

All of this is also doable in the GUI: /cc gui → click the nether star to import the rocket in your hand; right-click any style to preview it.

烟花样式与概率

一个「样式」就是一组烟花效果加一个出现权重。样式数量不限，每次苦力怕变成烟花时按权重随机抽一个播放。

样式结构

样式写在 firework_styles 下，键名就是样式名（可随意起名，含空格时加引号即可）：

firework_styles:
  <样式名>:
    type: BALL              # 形状
    flicker: true           # 是否闪烁
    trail: false            # 是否带尾迹
    colors:                 # 主色，至少一个
      - RED
      - "#FFD700"
    fade-colors:            # 渐变色，可选
      - ORANGE

字段	必填	默认	说明
`type`	否	`BALL`	烟花形状，每个样式单独配置；写错时回退为 `BALL`
`flicker`	否	`false`	闪烁效果（原版的「闪烁」）
`trail`	否	`false`	拖尾效果（原版的「踪迹」）
`colors`	是	—	主色列表。写成单值也行
`fade-colors`	否	空	爆炸后的渐变色列表

兼容写法

解析器对键名比较宽容，下列写法都等价，老配置或别人分享的片段可以直接粘贴：

标准写法	同样接受
`colors`	`color`
`fade-colors`	`fade_colors`、`fade`
`colors: [RED, BLUE]`	`colors: RED`（单色直接写字符串）

烟花形状

形状不是插件里写死的固定清单，而是每个样式各自的配置项。type 的值会直接交给 Bukkit 的 FireworkEffect.Type，因此同一份配置里每个样式都可以用不同的形状，随意混搭。

值	游戏内表现	适合
`BALL`	小球形，最经典	通用，颜色多时最好看
`BALL_LARGE`	大球形，扩散范围更大	远距离观赏、大型庆典
`STAR`	星形，带尖角	配合闪烁效果
`BURST`	爆裂形，向四周散射	多色渐变
`CREEPER`	苦力怕脸形状	主题彩蛋，绿色系最搭

想让不同场合有不同观感？给每个样式配自己的形状即可——比如稀有样式用 CREEPER，常见样式用 BALL_LARGE。形状跟着样式走，不是全局设定。

CREEPER 形状的烟花在原版里只由特定烟花火箭产生，但它属于 FireworkEffect.Type 的合法枚举值，因此可以直接在配置里使用。

颜色写法

颜色有三种写法，同一个列表里可以混用。

1. 颜色名称

名称	色值	名称	色值
`RED`	#FF0000	`AQUA`	#00FFFF
`ORANGE`	#FFA500	`TEAL`	#008080
`YELLOW`	#FFFF00	`BLUE`	#0000FF
`LIME`	#00FF00	`NAVY`	#000080
`GREEN`	#008000	`PURPLE`	#800080
`OLIVE`	#808000	`FUCHSIA`	#FF00FF
`MAROON`	#800000	`SILVER`	#C0C0C0
`GRAY` / `GREY`	#808080	`WHITE`	#FFFFFF
`BLACK`	#000000	名称不区分大小写，`red` 与 `RED` 等价

2. 十六进制

colors:
  - "#FFD700"    # 六位，# 可省略
  - "#f00"       # 三位简写 = #FF0000
  - "1E90FF"     # 不带 # 也可以

六位按 RRGGBB 解析，三位按 RGB 逐位复制成 RRGGBB。注意在 YAML 里以 # 开头的值必须加引号，否则会被当成注释。

3. RGB 映射

colors:
  - RED: 255
    GREEN: 100
    BLUE: 0

三个分量都必须存在且落在 0–255，否则这个颜色会被判为无效。也支持简写键：

colors:
  - rgb: "#FF6400"
  - value: 16737843   # 十进制整数，等价于 #FF6403

无效颜色会被静默丢弃。拼错的颜色名不会报错，只是不生效；如果一个效果里所有颜色都无效，这个效果就会被整个跳过；如果一个样式的所有效果都被跳过，这个样式就不会被加载——它不会出现在 /cc effect list 里，也不参与概率分配。

一个样式包含多个效果

样式值可以是一个列表，列表里每个元素都是一份完整的效果定义。它们会在同一次爆炸中同时播放，适合做「主花 + 副花」的层次感。

firework_styles:
  grand_finale:
    - type: BALL_LARGE
      flicker: true
      trail: true
      colors:
        - "#FFD700"
        - WHITE
      fade-colors:
        - ORANGE
    - type: STAR
      colors:
        - "#00E5FF"
      fade-colors:
        - BLUE
    - type: BURST
      trail: true
      colors:
        - FUCHSIA
        - PURPLE

注意列表里的每一项都是「效果」，不是「样式」。写在列表里的多个效果共享同一个权重，不会分别抽签。

概率权重与自动补偿

firework_chances 里填的数字不是百分比，而是权重。插件加载时会做一次归一化，保证所有样式的概率之和恒等于 100%。

firework_chances:
  classic: 4      # 4/10 = 40%
  starburst: 3    # 3/10 = 30%
  rainbow: 2      # 2/10 = 20%
  creeper: 1      # 1/10 = 10%

情况	插件的处理
权重之和不是 100	按比例缩放，总和强制归到 100%
某样式没写权重	取其它已定义权重的平均值
一个权重都没写	所有样式平均分配
全部权重为 0	退化为等概率随机
四舍五入导致总和 99.99 或 100.01	差额补到当前概率最大的那个样式上
写了不存在的样式名	忽略该行

用指令精确设定某个样式的概率

/cc effect chance <样式名> <百分比> 会把指定样式钉死在给定值，剩下的百分比按原有比例分配给其它样式：

/cc effect chance classic 50

假设原来是 40 / 30 / 20 / 10，执行后变成 50 / 25 / 16.67 / 8.33——其余三个保持原来的相对比例，总和仍是 100。

想回到平均分配，用 /cc effect chance reset。

概率显示保留两位小数。任何通过指令或 GUI 的修改都会立刻写回 config.yml，不需要再执行 reload。

从游戏内采集样式

手写颜色固然可以，但更省事的做法是先用原版烟花调出满意的效果，再让插件读取它。

准备一支带效果的烟花火箭

插件读取的是主手物品的 FireworkMeta，所以这支烟花必须至少带有一个爆炸效果（纯飞行时间的烟花不算）。1.20.4 及以前的 NBT 写法：
```
/give @s firework_rocket{Explosion:{Type:3,Colors:[I;16711680,16777215],Flicker:1,Trail:0}} 1
```
1.20.5 之后改用组件写法：
```
/give @s firework_rocket[firework_explosion={shape:"star",colors:[16711680,16777215],has_twinkle:true}] 1
```
语法在版本间有变化，如果上面两条都不生效，用对应版本的道具生成器生成一支带效果的烟花即可——插件只关心「手里这支烟花有没有效果」，不关心它是怎么来的。
手持烟花执行添加指令
```
/cc effect add my_style      # 新增，名字重复会提示已存在
/cc effect set my_style      # 覆盖同名样式
```
成功后会在你脚下立刻放一次预览，同时写入配置。省略名字时会自动取 style1、style2…
确认结果
```
/cc effect list
```
列表会显示每个样式的效果数量与当前概率。

也可以完全在图形界面里完成：/cc gui → 点「添加烟花样式」（下界之星）→ 手持烟花即可入库；在样式上右键可以随时预览。