Configuration
The config lives at plugins/CreeperConfettiPro/config.yml. Every key can also be changed with /cc commands; after hand-editing, run /cc reload.
Config structure
| Key | Type | Default | Purpose |
|---|---|---|---|
config-version | int | 6 | Migration marker — do not edit |
debug | bool | false | Verbose logs: style list, chances, GeoIP details |
confetti_chance | 0–100 | 100 | Overall chance for a creeper to become a firework |
command-aliases | section | all on | Switches for /cc and /confetti |
update-checker | section | enabled | GitHub release check, OP notices, optional token |
language | string | auto | Plugin language, auto or a language code |
firework_styles | section | 4 built-in styles | Style definitions |
firework_chances | section | 40/30/20/10 | Per-style weights, normalised to 100% on load |
confetti_chance
The overall trigger chance, 0 to 100, decimals allowed. On every creeper explosion the plugin rolls a random 0–100 value and only converts the blast when the roll is below this number.
# every creeper becomes a firework
confetti_chance: 100
# roughly one in four
confetti_chance: 25
# one in ten thousand — a rare easter egg
confetti_chance: 0.01The in-game equivalent is /cc chance 25. The command clamps to 0–100 and rejects anything else; the file itself is not validated, so 150 behaves like 100 and a negative value like 0.
This is the overall chance and is independent of the per-style weights: first the plugin decides whether this explosion becomes a firework at all, then it draws a style from firework_chances.
command-aliases
The plugin registers /cc and /confetti at runtime through the server's CommandMap rather than in plugin.yml — Bukkit has no way to toggle aliases declared in the plugin file after startup.
command-aliases:
enabled: true # master switch
cc: true # /cc
confetti: true # /confetti| Situation | Behaviour |
|---|---|
| Alias already taken by another plugin | Skipped with a console warning; everything else keeps working |
| Alias disabled here | Silently skipped; the reason is logged when debug: true |
enabled: false | Neither alias is registered; only /creeperconfetti works |
/cc reload | All aliases are unregistered and re-registered from the new config, so conflicts are re-checked |
If the "already registered" warning is noise on your server, set that alias to false. The warning never affects functionality — it just tells you the alias is redundant.
language
Controls every player-facing message and the console banner.
# pick a language from the server's IP region
language: auto
# pin English
language: en_us
# legacy codes still work and are converted
language: enValues and the country mapping are listed under Languages. An unrecognised code logs a warning and falls back to en_us.
debug
When enabled the plugin also logs:
- the number of styles loaded plus their full name list;
- the chances after normalisation;
- GeoIP details (which endpoints were queried, which country was detected, which language that maps to);
- why an alias registration was skipped.
Debugging "why did no firework appear" or "why is it still English" starts here — turn debug on and restart; the log usually answers it directly.
Update checker
On enable the plugin asks the GitHub Releases API for the newest published version and prints a console notice when a newer one exists. The check runs asynchronously about five seconds after startup (Bukkit: a task delayed 100 ticks; Folia: an async scheduler), so it never blocks the server.
| Key | Default | Purpose |
|---|---|---|
enabled | true | Switch the whole check off |
notify-ops | true | Send operators a one-time in-game notice when they join and an update is available |
github-token | "" | Optional classic token with only the public_repo scope |
Anonymous GitHub requests are limited to 60 per hour per IP. Shared hosting and cloud IPs often exhaust that quota, which shows up in the log as [Update] GitHub returned HTTP 403. A token raises the limit to 5000 per hour. Instead of putting it in the config, set the CREEPERCONFETTI_GITHUB_TOKEN environment variable (or GITHUB_TOKEN) — that keeps the token out of config.yml and out of the backups/ folder. Resolution order is the config value, then CREEPERCONFETTI_GITHUB_TOKEN, then GITHUB_TOKEN.
The in-game notice is sent once per server session per operator, and only when notify-ops is on. A 403 or 429 is logged once per session with the rate-limit reset time; it never affects the plugin's behaviour.
Config version & migration
config-version at the top of the file drives migration. The current value is 6. It is only checked on enable — /cc reload does not migrate.
-
Same version → nothing happens
If the stored version is 6 or higher the migrator returns immediately without reading or writing.
-
Older version → back up first
The existing file is copied to
backups/config-backup-<yyyyMMdd-HHmmss>.ymlbefore anything changes. -
Convert the old format
Version 0 (a config with no
config-versionkey at all) has its old single-effect listconfetti_effectturned into a style nameddefault, keeping every colour and shape. -
Merge new keys
Keys added by newer versions are merged in. Existing values are never overwritten. The new version number is then written.
Migration only runs at startup. If you lower config-version by hand, the next restart migrates again — and this time the "old" values come from your current file, which is rarely what you want. Leave the number alone.
Full example
A complete, ready-to-use config with four preset styles:
# config version — do not edit
config-version: 6
# verbose logging
debug: false
# overall chance for a creeper to become a firework (0-100)
confetti_chance: 100
# command aliases
command-aliases:
enabled: true
cc: true
confetti: true
# update checker (GitHub Releases)
update-checker:
enabled: true
notify-ops: true
github-token: ""
# language: auto / en_us / zh_cn / ...
language: auto
# firework styles: any number, one is picked at random per explosion
firework_styles:
classic:
type: BALL
flicker: true
trail: false
colors:
- RED
- YELLOW
- WHITE
fade-colors:
- ORANGE
starburst:
type: STAR
flicker: true
trail: false
colors:
- AQUA
- WHITE
- BLUE
fade-colors:
- PURPLE
rainbow:
type: BURST
flicker: false
trail: true
colors:
- RED
- ORANGE
- YELLOW
- GREEN
- AQUA
fade-colors:
- WHITE
creeper:
type: CREEPER
flicker: true
trail: true
colors:
- GREEN
- LIME
fade-colors:
- GREEN
# per-style weights, normalised to 100%
firework_chances:
classic: 40
starburst: 30
rainbow: 20
creeper: 10After using commands, the file looks different
Once you change styles through /cc effect add, /cc effect chance or the GUI, the plugin rewrites the firework_styles and firework_chances sections. Styles are then stored in Bukkit's serialised form:
firework_styles:
classic:
- ==: org.bukkit.FireworkEffect
type: BALL
flicker: true
trail: false
colors:
- ==: org.bukkit.Color
RGB: 16711680
fade-colors:
- ==: org.bukkit.Color
RGB: 16755200This is normal, not corruption — it loads fine, it is just unpleasant to hand-edit. To get the readable form back:
- run
/cc effect resetto restore the four built-in styles (still serialised); - or stop the server and replace the whole
firework_stylesblock with the hand-written example above, then start again.
Suggested workflow: capture styles in game with /cc effect add or the GUI (it reads the firework in your hand), and only touch the YAML for bulk edits or version control.