offerings v1.4.3

Requirements​

• Server: Paper or Spigot
• Minecraft: 26.2
• Java: 25

Soft dependencies (optional)​

• PlaceholderAPI — %offerings_*% expansion for scoreboards, chat, kit lore. Plugin loads and runs safely without it.
• LuckPerms — recommended for tier, kit, and table permission gates.

Terminology​

Install​

1. Download offerings-plugin-1.1.0.jar
2. Place in your server plugins/ folder
3. Remove any older offerings-plugin-*.jar versions
4. Start or restart the server
5. Bundled loot/ catalog, milestones/, and achievements.yml extract on first run

First launch checklist​

1. Grant players offerings.use (default: true)
2. Open /offerings admin as an operator
3. Review Content Health — fix any errors before going live
4. Tune Tier Rarity weights if defaults don't match your economy
5. Set Claim Cadence (rolls per claim, cooldown, streak grace)
6. Configure Crate Policy (identification on/off, key locking, smelt timing)
7. Optionally enable Roll Modes penalties for risk/reward servers
8. Place an Identification Forge for players (craft recipe in /offerings guide) or /offerings giveforge

Five-minute setup path​

1. Simple survival: leave bundled catalog, set cooldown to 24h in Claim Cadence, done
2. VIP legendary band: Tier Permission Gates → set Legendary view/roll nodes → assign in LuckPerms
3. High-risk daily: Roll Modes → enable penalties, set penalty roll count
4. Instant rewards: Crate Policy → disable identification required
5. Custom prizes only: add kits to loot/kits/custom.yml with custom_ prefix

Opening the hub​

• /offerings — primary command (aliases: /offer, /rewards, /offering)
• /stipend — alternate hub command (aliases: /pay, /salary)
• Configurable aliases: /daily, /gamble, /slots, /gamba (server-defined)
• Requires offerings.use

Claiming your daily draw​

1. Open the hub when your cooldown is clear (spyglass header shows Ready to claim or time remaining)
2. Click Claim Draw (center chest) when eligible
3. Each claim runs rolls-per-claim reward rolls (default 3) plus optional penalty rolls if enabled
4. You receive unidentified physical crates by default — contents are hidden until you work through the crate pipeline
5. Streak, milestones, and achievements update automatically

Hub buttons​

Reward catalog & previews​

• /offerings catalog (aliases: preview, pools, browse)
• Browse by tier — only content you pass view permission checks for appears
• Drill into kit detail and loot table previews with entry weights
• Gated tiers and kits are hidden, not shown as locked — ungated content stays visible alongside gated content

Crate pipeline — step by step​

Identification Forge​

• Craft via shaped recipe — see Crafting Guide in hub or /offerings guide
• Place the forge block → right-click to open smoker UI
• /offerings identify opens the nearest forge within 6 blocks
• Cook time scales by tier (Common ~10s default → Mythic ~30 min default with curve enabled)
• Tier is determined when smelting starts — each crate cooks at the correct speed for its roll

Crafting guide screens​

• Crafting Guide Hub — index of all recipes
• Identification Forge — shaped craft for portable forge item
• Crate Keys — per-tier key recipes (Rare, Epic, Legendary, Mythic)
• Unlock Crates — shapeless key + identified crate crafts
• Crate Flow — four-step pipeline walkthrough with links to recipes

Opening crates​

• Right-click identified/unlocked crate in hand → reel scramble menu → payout delivers
• Shift + right-click → skip reel animation for that stack
• Hub » Open All Crates → processes every openable crate one reel at a time
• Payout = kit commands + custom items from loot/items/

Milestones​

• /offerings milestones (aliases: streak, streaks)
• 1,095 days of attendance rewards in bundled milestones/days-*.yml shards
• Fires once when your streak reaches each keyed day
• Rewards = console commands (%player%) + optional chat message

Achievements​

• /offerings achievements (alias: stats)
• 13 defaults — unlock automatically when stats cross thresholds; no manual claim
• Types: total claims, total kits, best streak, unique kits, tier rolls
• Optional commands on unlock; hidden: true for secret trophies

• First Offering — first daily claim
• Steady Hand — 3-day best streak
• Week of Faith — 7-day best streak
• Month of Devotion — 30-day best streak
• A Handful — 10 kits received
• Full Satchel — 50 kits
• Treasury — 200 kits
• Varied Taste — 5 unique kits
• Collector — 15 unique kits
• Rare Glimmer — first Rare tier roll
• Gilded Fortune — first Epic roll
• Legend Touched — first Legendary roll
• Mythic Whisper — first Mythic roll (hidden)

Player directory​

• Hub button or /offerings players (aliases: lookup, directory)
• Requires offerings.lookup (default: true)
• Paginated player heads — online or all known players
• Read-only profile: streak, milestones claimed, achievements earned

Menu navigation (every chest GUI)​

Three-level lottery​

1. Tier roll — weighted pick from tier-weights (only tiers you can roll with pool content)
2. Pool roll — every enabled kit + loot table at that tier competes on its own weight
3. Payout — if a table wins, roll inside entries; if kit has loot-table: ref, delegate to sub-pool; then deliver commands + items

Default tier weights (10,000-point pool)​

Loot table — two roles​

• Pool entry — table has its own tier + weight; competes with kits on the daily roll
• Payout delegate — kit loot-table: ref rolls that table when the kit wins for the final payout

Personalized hub odds​

Streaks & cooldowns​

• cooldown-hours — time between claims (default 1 hour in bundled config; tune for your server)
• streak-grace-hours — how long a missed period before streak resets (default 48 hours)
• rolls-per-claim — reward rolls per claim (default 3)

Roll modes​

• Reward rolls — main daily kit draws (roll-modes.rewards.enabled)
• Penalty rolls — separate curse draws per claim (roll-modes.penalties.enabled, default off)
• penalty rolls-per-claim — how many curse rolls when enabled (default 1)
• Configure in Admin » Roll Modes or /offerings rollmodes

Penalty kit features​

• outcome-type: penalty — toggle in kit editor
• Debuff categories: Mobility, Combat, Survival, Visual, Resource, Curse
• Potion effects — slowness, mining fatigue, weakness, nausea, blindness, darkness, glowing, poison, wither, levitation, hunger, bad omen (preset templates in editor)
• Damage hearts — direct heart damage (floored at one heart remaining)
• Hunger drain — food level reduction
• Commands — economy drain, item taxes, etc.

Penalty loot tables​

• pool-type: penalty on loot tables
• Bundled loot/tables/penalties.yml and per-tier *-curses.yml kits
• Kit catalog admin filter: Rewards vs Penalties toggle

Reward Kits​

Loot Tables​

• Cycle tier, adjust weight, enabled toggle
• Toggle reward / penalty pool type
• Edit name (chat), add weighted entries (chat: kit_id weight)
• View / roll permission (chat)
• Delete with chat confirmation

Custom Items​

• Browse all loot/items/ definitions
• Create by id (chat) or held-item /give import (chat paste, 256 char limit)
• Delete with confirmation
• Items support material, amount, name, lore, enchants, give-command

Tier Rarity​

• Live edit tier-weights for all six tiers
• Increment/decrement controls with shift-click for larger steps
• Live percentage odds display

Tier Permission Gates​

• Per tier: set view and roll LuckPerms nodes via chat (clear to remove)
• Persists to config.yml → tier-permissions

Claim Cadence​

• Rolls per claim — reward roll count
• Cooldown hours — time between draws
• Streak grace hours — missed-day forgiveness window

Roll Modes​

• Toggle reward rolls on/off
• Toggle penalty rolls on/off
• Adjust penalty rolls per claim with increment/decrement/reset

Crate Policy​

• Identification required — toggle unidentified vs identified crates on claim
• Locking enabled — global key-lock switch
• Per-tier locking — toggle key requirement per tier (default: Rare+ locked, Common/Uncommon open)
• Smelt Timing — opens Identification Smelt Timing sub-menu

Identification Smelt Timing​

• Automatic curve — geometric scale from lowest tier base to highest tier anchor
• Base cook ms — lowest tier duration (default 10,000 ms / 10 seconds)
• Top-tier cook ms — highest tier anchor (default 1,800,000 ms / 30 minutes)
• Per-tier manual — when curve off, edit each tier individually
• Snapshot from curve — populate manual overrides when disabling curve
• Reset curve — restore default base and anchor values
• New tiers added to the enum pick up curve or manual values automatically

Give Items​

• Player head lookup → grant menu per player
• Give Identification Forge item
• Give tier crate keys (Rare / Epic / Legendary / Mythic)
• Give unidentified reward or penalty crates (quantity control)

Player Cooldowns​

• Player head lookup → view cooldown status
• Reset one player's draw cooldown
• Server-wide reset (/offerings resetall equivalent)

Hub Aliases​

• View active and configured hub-opening commands
• Add alias via chat (registers as a live command)
• Remove aliases
• Default bundled aliases include gamba, slots, gamble, daily

Chat Reminder​

• Toggle recurring broadcast for players whose draw is ready
• Set interval (minutes)
• Customize message, player clickable link, admin link (all via chat prompts)

Content Health​

• Invalid or unknown materials
• Broken cross-references (missing kit ids in table entries, missing item refs)
• PlaceholderAPI tokens when PAPI is off or missing
• Command dependency issues

Reload & Save​

Chat prompt system​

• Kit: search, create id, name, lore, commands, loot-table ref, delete confirm, view/roll perms
• Table: create id, name, add entry, delete confirm, view/roll perms
• Item: create id, held import, /give parse, delete confirm
• Tier: view/roll perm nodes
• Broadcast: message, interval, player link, admin link
• Hub alias: add new command label

Player commands​

Admin commands​

Permission nodes​

LuckPerms examples​

lp group default permission set offerings.use true
lp group default permission set offerings.lookup true
lp group admin permission set offerings.admin true
lp group admin permission set offerings.bypass true

lp group vip permission set offerings.legendary.view true
lp group vip permission set offerings.legendary.roll true

view-permission: offerings.mythic.preview
roll-permission: offerings.mythic.roll

File map​

plugins/Offerings/
├── config.yml
├── achievements.yml
├── milestones/days-*.yml
├── loot/kits/          (classic, *-supplies, *-gear, *-curses, keys, custom.yml)
├── loot/items/         (per-tier enchanted blueprints)
├── loot/tables/        (per-tier, curated.yml, penalties.yml)
├── players.yml         (yaml backend)
└── data.db             (sqlite backend)

config.yml sections​

Kit YAML example​

kits:
  my_kit_id:
    tier: uncommon
    weight: 10
    enabled: true
    icon: CHEST
    name: "&aDisplay Name"
    lore:
      - "&7Tooltip line"
    commands:
      - "give %player% minecraft:diamond 1"
      - "eco give %player% 50"
    items:
      - example_fortune_pick
    loot-table: mixed_supplies
    view-permission: ""
    roll-permission: ""
    outcome-type: reward
    debuff-category: mobility
    effects:
      - type: slowness
        duration: 30
        amplifier: 0

Loot table YAML example​

tables:
  mixed_supplies:
    tier: uncommon
    weight: 8
    name: "Mixed Supply Crate"
    icon: CHEST
    enabled: true
    pool-type: reward
    entries:
      fieldhand_rations: 12
      kindling_bundle: 10
    view-permission: ""
    roll-permission: ""

Custom item YAML example​

items:
  example_fortune_pick:
    material: IRON_PICKAXE
    amount: 1
    name: "&5Fortune Miner's Pick"
    enchants:
      fortune: 3
    give-command: "give %player% minecraft:iron_pickaxe 1 fortune:3"

Server-specific kits​

Config recipes​

• Flat pool: put kits in loot/kits/ with tiers + weights; minimal tables
• Mystery crate: create table with kit entries; give table tier + weight in daily pool
• VIP legendary: tier gates + LuckPerms; legendary kits at tier: legendary
• Secret kit: per-kit view/roll permission in editor
• Kit delegates payout: kit loot-table: ref rolls sub-pool on win
• Economy hook: eco give %player% in kit/milestone/achievement commands