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

Rarity	Chance	Duplicate Essence
Basic	45%	1
Classic	32%	2
Advanced	17%	5
Epic	5%	15
Legendary	0.8%	50
Mythic	0.2%	200

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

Command	Purpose
/gift	Show quick help
/gift status	Spins, Essence, collection size, equipped Gift, and cooldown
/gift spin	Consume one spin and turn the wheel
/gift collection [page]	Show unlocked Gifts
/gift powers [page]	Show all powers and descriptions
/gift equip <power_id>	Equip one unlocked Gift
/gift use	Activate the equipped Gift, if it has an active ability
/gift pity	Show remaining spins until each guarantee
/gift odds	Show the configured rarity chances
/gift shop	Show Essence purchases
/gift shop buy spin	Buy one spin for 50 Essence
/gift shop buy epic <power_id>	Unlock an unowned Epic for 250 Essence
/gift shop buy legendary <power_id>	Unlock an unowned Legendary for 1,000 Essence
/whisper [quote|tip|mission]	Request an optional solo message

Administrator commands

/giftadmin requires vanilla gamemaster permission level or higher.

Command	Purpose
/giftadmin reload	Reload config/wheel-of-gifts.json
/giftadmin give_spins <player> <amount>	Add spins
/giftadmin set_essence <player> <amount>	Set Essence
/giftadmin grant <player> <power_id>	Unlock a Gift
/giftadmin equip <player> <power_id>	Force-equip a Gift
/giftadmin reset_daily <player>	Grant the current daily refill again
/giftadmin shrine set	Make the block being looked at a Power Shrine
/giftadmin shrine remove	Remove the targeted shrine
/giftadmin shrine list	List all configured shrines

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.