Wheel of Gifts

Wheel of Gifts is a server-side Fabric 1.21.11 mod for small survival servers. Every player receives five free spins per day, unlocks permanent powers through a transparent rarity system, and equips exactly one power at a time.

The first release contains 25 powers, pity protection, duplicate-to-Essence conversion, an optional physical shrine, solo-player messages, persistent cooldowns, and crash-safe spin results.

What players get

• Five free spins per calendar day in Asia/Jakarta.
• Up to 35 banked spins, so missing a day does not erase progress.
• Permanent ownership of every new Gift.
• Exactly one equipped Gift at a time.
• A two-minute opportunity to equip a newly rolled Gift immediately.
• A normal 15-minute cooldown between later Gift changes.
• Active abilities through /gift use; no client keybind or client mod is needed.
• Published odds and visible pity progress.
• Essence when a duplicate is rolled.
• Optional quiet quotes, tips, and mini-missions when only one player is online.

Default odds

Pity is checked before a result is chosen:

• Spin 25 without an Epic+ result is guaranteed Epic or better.
• Spin 100 without a Legendary+ result is guaranteed Legendary or better.
• Spin 250 without a Mythic result is guaranteed Mythic.
• A pity result selects an unowned power of its rolled rarity when one is available.

The Wheel never consumes money, and the animation does not change the result after it has been selected.

Player commands

Administrator commands

/giftadmin requires vanilla gamemaster permission level or higher.

Optional Power Shrine

1. Build any wheel, altar, beacon, or shrine at spawn.
2. Look directly at its center block.
3. Run /giftadmin shrine set.
4. Interacting with that block starts a spin.
5. After the first server start, edit config/wheel-of-gifts.json and set requireShrineToSpin or requireShrineToEquip to true if commands should work only near a shrine.
6. Run /giftadmin reload.

Configuration and saved data

The mod generates:

• config/wheel-of-gifts.json — odds, reset timezone, bank size, pity, announcements, shop prices, shrine rules, and solo messages.
• <world>/data/wheel-of-gifts.json — player collections, equipped Gifts, cooldowns, pity, balances, pending spins, and shrine locations.

Both files use atomic replacement where the host supports it. A spin is deducted and its result is saved before the animation begins. If a player disconnects or the server restarts, the same pending result is revealed later instead of being rerolled or lost.

Back up the world before updating or changing mods. Never edit the world data file while the server is running.

Aternos

Aternos does not allow a private JAR to be uploaded directly. Publish the built JAR on Modrinth or CurseForge, then submit its project URL through Aternos' suggestion page. After Aternos accepts it, install both Fabric API and Wheel of Gifts from the Aternos Mods page.

See docs/ATERNOS_INSTALL.md for the full checklist and docs/MODRINTH_RELEASE.md for ready-to-copy project metadata.

Build from source

Requirements: Java 21 and an internet connection for the first dependency download.

./gradlew build

The distributable file is:

build/libs/wheel-of-gifts-1.0.0.jar

Do not install the -sources.jar file on a server.

Performance design

• No custom entities, dimensions, chunk loaders, databases, mixins, or continuously spawned display entities.
• Idle players are not scanned every tick.
• Passive effects refresh every two seconds.
• Wavewalker checks locally four times per second only while equipped.
• Chronos stores six tiny in-memory snapshots only for players who equip it.
• Player data flushes periodically and immediately after important transactions.
• Timekeeper uses temporary status effects rather than persistent AI changes.

More documentation

• Power catalog
• Balance and safety design
• Aternos installation
• Modrinth release text

Licensed under MIT.