SUNSHINE WHEEL

Setup Guide v1.2.0

Animated fortune wheels with a built-in web editor, chance-weighted slices, a left-click chance menu and custom item payouts. Paper 1.21+, Java 21+.

Setup in 3 steps

Install the plugin

Drop SunshineWheel-1.2.0.jar into your plugins/ folder and start the server once. Three sample wheels (daily, premium, vote) are created automatically.

Open one port

The editor runs on port 8770 by default. Open it in your firewall:

Linux:    ufw allow 8770/tcp        # or your host panel (Pterodactyl, Multicraft, ...)
Windows:  New-NetFirewallRule -DisplayName SunshineWheel -Direction Inbound -LocalPort 8770 -Protocol TCP -Action Allow

Prefer keeping the port closed? Serve it through nginx instead — see FAQ and the examples/nginx-wheel.conf file in the download.

Connect and edit

In-game, run /wheel web. You get either a ready link or an address + key. Open http://YOUR-SERVER-IP:8770/ in your browser and sign in with the key (valid 10 minutes, single use, session lasts 12 hours).

That's it — configure wheels, rewards, costs, effects and colors from the browser with live preview and test spins. Press Save & apply and the change is live in-game instantly.

Resource pack (required, tiny)

The wheel is drawn with a ~2 KB font pack. On startup the plugin builds it and serves it at /pack.zip. Copy the two lines printed in the console into your server.properties:

resource-pack=http://YOUR-SERVER-IP:8770/pack.zip
resource-pack-sha1=<printed at startup>

Restart the server. Done.

Already using a resource pack?

Minecraft supports one server pack at a time. Download the same pack.zip and copy its assets/sunshinewheel folder into your own pack (Oraxen, ItemsAdder, Nexo or a hand-built pack). The wheel then uses your existing pack — no second pack needed.

Using the editor

Wheels — create, delete, pick a wheel; place it in-game with /wheel move <id>
General — display name, enable/disable, spin permission, win broadcast
Rewards — names with live <chance>, weights, colors, commands, per-reward permission, enable/disable and an at-a-glance payout summary
Item source — pay out a vanilla material, a captured item copy (any custom item: Oraxen, ItemsAdder, heads, enchanted gear) or a plugin item id (Oraxen, ItemsAdder, MMOItems, Nexo, ExecutableItems) with id suggestions
Animation / Cost & Ticket / Cooldown — spin feel, tickets, Vault money, XP, wait time
Appearance — size, frame/hub/pointer colors and weighted slices (slice size follows the chance); Effects — fireworks, rockets, spirals, particles
The right panel is a live preview with the real slice sizes; Test spin shows the win flow before going live

Custom item rewards

Any item can be a reward, exactly as it looks in-game (name, lore, model, enchantments):

From the web editor:
  Rewards -> edit a reward -> Item source
    - "Captured item"               -> Use held item / Pick from inventory
    - Oraxen / ItemsAdder / ... id  -> pick one from the suggestions

From the game (hold the item in your main hand):
  /wheel setitem <wheel> <reward-number>              # exact copy of the held item
  /wheel setitem <wheel> <reward-number> oraxen:<id>  # plugin item id

Rewards without any payout (no item and no command) are flagged in the editor with a red NO PAYOUT badge, and the console logs a warning when one is won — no more silent empty wins.

Player commands

Action	How
Spin	Right-click the wheel (price/ticket/XP taken automatically)
Rewards & chances menu	Left-click the wheel — chest-style GUI with icons, chance percentages, permission locks and payouts (paginated)
Chat preview	Sneak + right-click the wheel (or `/wheel preview <id>`)
Placeholders	`%sunshinewheel_<id>_spins\|wins\|free\|cooldown%`

Admin commands (`/wheel`, permission `sunshinewheel.admin`)

Command	Description
`/wheel web`	One-time link/key for the web editor
`/wheel create\|move\|remove\|list`	Manage wheels (right-click a block to place)
`/wheel menu <id>`	Open the chance menu (same as players left-clicking)
`/wheel setitem <id> <n> [provider:id]`	Set a reward's payout from your hand or a plugin item id
`/wheel preview <id>`	Show rewards with chances in chat
`/wheel give\|take <player> <wheel> <n>`	Grant/revoke free spins
`/wheel ticket give\|take ...`	Give/take ticket items
`/wheel stats [player]`	Spins, wins and free spins
`/wheel resetcooldown <player> <wheel>`	Clear a cooldown
`/wheel set <id> <key> <value>`	Quick tweak (style, duration, revolutions, pixel-size, image-size, upright, item-scale, weighted-slices)
`/wheel reload`	Reload wheels.yml and custom item caches

FAQ

Players see boxes instead of the wheel

The resource pack isn't reaching players: check the resource-pack and resource-pack-sha1 lines in server.properties and that http://YOUR-SERVER-IP:8770/pack.zip opens in a browser. If the server is behind Velocity/BungeeCord, send the pack from the proxy or merge it into your existing pack instead.

I won a reward but received nothing

That reward has no payout configured. Edit it and turn on Give the item on win and/or add a console command — or set a captured/plugin item as its source. Payout-less rewards show a red NO PAYOUT badge in the editor and the console warns you when one is won.

Left-click doesn't open the chance menu

Make sure menu.enabled: true is set in config.yml and that you click the wheel itself. Players need no permission; the sneak + right-click chat preview still works as before.

My Oraxen / ItemsAdder item id isn't found

Check the id in the editor's suggestion list; if the plugin isn't installed the reward falls back to its vanilla icon and the console logs a warning. Captured item copies work with any item plugin, no ids needed.

I'd rather expose the editor over HTTPS

Keep web.bind: 127.0.0.1 in config.yml and proxy it with nginx — a ready example ships in examples/nginx-wheel.conf.

Nothing responds at http://IP:8770

Almost always the firewall (step 2), or the port was changed in config.yml. On managed hosts, allocate/open the port in your panel.

Support

Questions or bug reports: join the Discord — discord.gg/HZEu79G8m — include your server version and the console lines from startup.