LuckyDraws

A server-authoritative daily draw for Minecraft.

Forge 1.20.1 / 1.21.1 · NeoForge 1.20.4 / 1.21.1 · Optional client presentation · Chat fallback

Project page · Releases · 中文文档

---

What It Does

LuckyDraws runs one daily, server-owned draw for every eligible player. The result is determined and persisted before any animation is shown. Players with the client mod receive the item when the reveal finishes, with a server-side timeout fallback; everyone else receives it immediately with a localized chat result.

Choose Your Loader

Platform	Minecraft	Java	Download	Client features
Forge	1.20.1	17	Forge 2.1.6	Carousel, MINI, history, replay, admin GUI
Forge	1.21.1	21	Forge 2.1.6	Carousel, MINI, history, replay, admin GUI
NeoForge	1.20.4	17	NeoForge 2.1.6	Carousel, MINI, history, replay, admin GUI
NeoForge	1.21.1	21	NeoForge 2.1.6	Carousel, MINI, history, replay, admin GUI

Install only the matching jar on the server. Install the same jar on a client for the visual UI. A vanilla or unmodded client is still supported through chat fallback.

NeoForge did not publish a Minecraft 1.20.1 line, so the supported NeoForge 1.20 release is Minecraft 1.20.4. Fabric and Minecraft 26.x remain out of scope. Forge 1.20.1 is compatible with Forge 47.3.22 and newer. The 2.1.5 Forge 1.20.1 jar requires 47.4.10 or newer; use 2.1.6 for older 47.3.x packs.

Feature Set

Area	Included
Daily draw	Configurable trigger time, per-player result, normal-distribution quantity
Special results	Enchants, custom attributes, potion effects, optional nearby mob events
Player controls	One daily reroll, seven-entry history, click-to-skip, read-only replay
Presentation	Near-miss carousel with exact centering, compact MINI while busy, reduced-motion option
Administration	Searchable item list, blacklist/whitelist, benefit draws, revision-safe GUI
Recovery	TOML hot reload, atomic persistence, field-level validation, chat/command fallback

Quick Start

Install a release

1. Pick the jar matching your loader and Minecraft version from the table above.
2. Put it in the server mods directory.
3. Start the server once to generate config/luckydraws-common.toml.
4. Install the same jar on clients that should see the carousel or admin GUI.

Build locally

.\scripts\build-release.ps1

The release script requires JDK 17 and JDK 21, builds each loader in an isolated Gradle environment, and writes the four production jars plus checksums to release/<version>/.

Commands

Command	Who	Purpose
/luckydraws reroll	Player	Use the one daily reroll after a normal draw
/luckydraws history	Player	Open the client history screen or print chat history
/luckydraws help	Everyone	Show localized command help
/luckydraws show	Operator	Print the current server configuration
/luckydraws admin	Level 2	Request the in-game admin configuration screen
/luckydraws grant <targets>	Level 2	Issue benefit draws without consuming daily eligibility
/luckydraws config reload	Level 2	Validate and atomically reload TOML
/luckydraws mobspawn on|off|status	Level 2	Toggle the world-scoped mob event

Configuration

The common file is .minecraft/config/luckydraws-common.toml (or the server's config/ directory).

drawTime = 1000
drawMean = 32.0
drawStdDev = 12.0
potionChance = 0.20
mobSpawnChance = 0.01
drawItemBlacklist = ["minecraft:bedrock", "minecraft:command_block"]
itemListMode = "BLACKLIST"
presentationPolicy = "AUTO"

The admin screen validates a full draft before writing. A stale revision cannot overwrite another operator's change. Invalid TOML or a failed write keeps the last-known-good runtime state and reports the affected fields.

How It Stays Safe

server roll -> persist drawId/history -> client carousel / MINI -> release reward
                         |                                  |
                  chat + immediate grant             10s timeout fallback

• A completion signal can only release that player's already persisted pending reward.
• Replay reads a saved snapshot and never consumes a reroll.
• Optional payloads are sent only to compatible clients.
• Client-only installs stay inert when the connected server has no compatible LuckyDraws channel.
• History entries survive missing registry items as textual records.

Project Layout

common/             Loader-independent rules, config, protocol, client state
forge-1.20.1/       Forge 47.x server and optional client jar
forge-1.21.1/       Forge 52.x server and optional client jar
neoforge-1.20.4/    NeoForge 20.4.x server and optional client jar
neoforge-1.21.1/    NeoForge 21.1.x server and optional client jar
docs/               GitHub Pages project showcase
docs/superpowers/   Version research, design, and delivery plans

Migration Notes

Existing LuckyDraws 1.20.1 config keys and world state are read by current Forge builds. New history entries store full item snapshots; old entries without a snapshot can fall back to text when an item is no longer registered. Back up worlds before changing loader or Minecraft versions.

License

MIT

Made for servers where the reward matters more than the reveal.