StellarCrates

StellarCrates is a server-authoritative virtual crate platform for Minecraft 1.21.1, NeoForge, and Pixelmon.

Instead of relying on physical crate keys that can be duplicated, lost, copied, or mishandled, StellarCrates uses persistent virtual credits stored securely by the server. Players can open configurable crates containing items, Pokémon, currencies, permissions, commands, composite bundles, and custom rewards.

Every reward is selected and permanently committed by the server before its opening animation begins. Disconnecting, restarting the server, clicking repeatedly, running out of inventory space, or filling Pixelmon storage cannot reroll or duplicate the reward.

Players without the optional client companion retain access through a complete vanilla chest-menu fallback. The optional companion adds 30 animated crate interfaces, 10 full catalog themes, custom opening ceremonies, sounds, accessibility settings, Pixelmon previews, claims, history, and detailed reward pages.

Features

• Secure virtual universal and crate-specific credits
• Server-authoritative reward selection
• Deterministic and recoverable crate openings
• Weighted and tier-first reward pools
• Without-replacement selection
• Independent reward categories
• Choice-based reward support
• Soft and hard pity
• Finite network-wide reward stock
• Duplicate reward protection
• Items, Pokémon, currency, commands, permissions, and composite rewards
• Pending claims for undelivered rewards
• Persistent opening history
• Signed one-time vouchers
• Player-to-player credit transfers
• Protected world crate blocks
• SQLite, MySQL, MariaDB, and PostgreSQL storage
• Shared balances across multi-server networks
• Runtime validation and probability simulation
• Audit logging, metrics, reconciliation, and recovery
• Migration support for popular crate plugins
• Vanilla chest-menu fallback
• Optional animated client companion
• 30 custom crate themes
• 10 full catalog themes
• Custom theme and rarity sounds
• Reduced-motion and accessibility settings
• Pixelmon Pokémon previews and safe party/PC delivery
• StellarGTS credit marketplace integration
• NeoForge permission support
• Configurable schedules, limits, webhooks, security, and rewards

Virtual Credit System

StellarCrates replaces physical crate keys with secure virtual balances.

Two main types of credits are supported:

• stellarcredits, which can be used toward any compatible crate
• Crate-specific credits that can only be used for one configured crate

When a crate uses its own credit, StellarCrates spends matching crate-specific credits first and universal credits second.

For example, a player with three Astral Forge credits and two universal Stellar Credits can safely use both balances to complete five Astral Forge openings.

Virtual credits:

• Cannot be dropped
• Cannot be lost on death
• Cannot be cleared from an inventory
• Cannot be copied through item data
• Can persist across multiple connected servers
• Are recorded through an auditable balance ledger

Administrators can grant, remove, or set balances with optional required reasons.

Server-Authoritative Openings

The opening animation never chooses the reward.

Before the reveal begins, the server:

1. Verifies the player and crate

2. Checks permissions and availability

3. Checks cooldowns and daily limits

4. Verifies the player has sufficient credits

5. Reserves the required balance

6. Selects the reward using a deterministic seed

7. Updates pity and finite stock

8. Stores the complete reward result

9. Sends the committed result to the client

10. Delivers or safely stores the reward

The animation only presents the result the server has already committed.

Repeated clicks, packet replay, disconnects, server restarts, lag, proxy transfers, and interrupted animations cannot generate a different reward from the same opening.

Reward Selection

StellarCrates supports multiple configurable selection systems.

Weighted Rewards

Each eligible reward receives a configurable weight.

A reward with a weight of 20 is twice as likely to be selected as a reward with a weight of 10. Weights do not need to add up to 100.

Tier-First Selection

The system first selects a rarity tier and then selects an eligible reward from that tier.

This allows servers to preserve exact rarity distributions even when different tiers contain different numbers of rewards.

Supported rarities include:

• Common
• Uncommon
• Rare
• Epic
• Legendary
• Mythic
• Jackpot

Without Replacement

When a crate performs multiple rolls, selected rewards can be removed from the remaining candidate list.

This prevents the same reward from being selected multiple times within one opening.

Independent Categories

A crate can evaluate separate reward categories independently.

This can be used to provide combinations such as:

• One guaranteed item
• One random Pokémon
• One currency reward
• One bonus cosmetic roll

Choice Rewards

Compatible crate designs can allow players to choose between server-approved committed options without allowing the client to create or replace rewards.

Pity System

StellarCrates supports configurable soft and hard pity.

Soft Pity

After a configured number of unsuccessful openings, qualifying rewards receive an increasing probability boost.

Administrators can configure:

• The pity starting point
• The multiplier applied after each opening
• The maximum probability multiplier
• Which rarities qualify
• Whether pity progress is visible

Hard Pity

Hard pity guarantees a qualifying reward after the configured threshold, provided a valid eligible reward remains available.

Pity can be shared between multiple crates through a common pity group.

Pity never bypasses permissions, stock, eligibility rules, or disabled rewards.

Finite Reward Stock

Rewards may have unlimited or finite stock.

Finite stock is decremented atomically when the reward is selected, not when the animation finishes.

When multiple servers share the same database, all servers use the same live stock counter. Two players cannot receive the final copy of a limited reward at the same time.

Administrators can inspect and adjust live stock through audited recovery commands.

Reward Types

StellarCrates supports several built-in reward types.

Item Rewards

Item rewards can include:

• Vanilla items
• Modded items
• Custom names
• Lore
• Glint
• Data components
• Custom model data
• Enchantments
• Exact exported item data

Administrators can export a held item directly into a reward definition, preserving supported components and modded data.

Pokémon Rewards

Pokémon rewards can be created through Pixelmon specifications or exported from an administrator’s party.

Pokémon rewards can preserve or configure:

• Species
• Form
• Palette
• Shiny state
• Level
• Nature
• Ability
• Growth
• IVs
• EVs
• Moves
• Held item
• Poké Ball
• Other supported Pixelmon properties

Once rolled, the final Pokémon data is committed and cannot be rerolled during delivery retries.

Currency Rewards

Crates can grant internal virtual currencies through idempotent ledger entries.

External economy integrations can also be implemented through reviewed providers.

Command Rewards

Configured console commands can be executed as rewards.

For security, command roots must appear in the server’s command allowlist. Downloaded or migrated configuration cannot gain unrestricted console access simply because it parses correctly.

Permission Rewards

Permission rewards can grant ranks, temporary permissions, or other permission-provider benefits through configured and allowlisted commands.

Composite Rewards

Composite rewards contain multiple child rewards.

Each child is delivered and tracked independently. If one component cannot be delivered, it can become a pending claim without repeating components that were already successfully delivered.

Custom Rewards

Other mods can register custom reward providers while preserving StellarCrates’ server-authoritative and idempotent delivery requirements.

Claims and Safe Delivery

StellarCrates never throws an undelivered reward onto the ground as an unsafe overflow fallback.

If a reward cannot be safely delivered, it becomes a pending claim.

Common causes include:

• Full player inventory
• Full Pixelmon party
• Full Pixelmon PC storage
• External reward requiring manual review
• Uncertain command delivery
• Temporary integration failure

Players can open their Claims page, make space, and retry delivery.

Every claim includes a support reference that administrators can use to inspect the original committed opening.

Delivered components are receipted individually, preventing a retry from duplicating rewards that have already been received.

Signed Vouchers

Administrators and external store integrations can issue signed one-time voucher tokens.

Vouchers can contain:

• Credit type
• Credit amount
• Expiration time
• Optional player restriction
• Unique voucher identity
• Cryptographic signature

A voucher cannot be altered or redeemed twice.

Players redeem vouchers using:

/crates redeem <token>

Unredeemed voucher tokens should be treated like passwords.

Protected Crate Blocks

Administrators can attach a configured crate to an existing world block.

The attached block receives:

• Protection from normal player breaking
• Protection from common explosions
• Protection from piston movement
• Protection from fluid replacement
• Protection from common tool and entity destruction
• A floating crate title
• A short description
• A visible interaction prompt

Left-clicking or right-clicking the block opens its attached crate.

The original block is preserved. StellarCrates does not replace it with a custom registry block.

Player Catalog

Players can open the crate catalog with:

/crates

Aliases include:

/crate

/stellarcrates

The catalog displays crates the player is allowed to view.

Each crate has dedicated pages for:

• Overview
• Rewards
• Claims
• Opening history

The Overview page can display the crate description, cost, balance, stock, pity, availability, and opening controls.

The Rewards page shows eligible rewards and configured odds when the server allows them to be displayed.

The Claims page contains rewards waiting for safe delivery.

The History page displays recent openings and their committed results.

Optional Client Interface

The server contains the complete crate engine and does not require players to install the optional client companion.

Players without the companion can use the vanilla chest-menu fallback when enabled.

The optional client companion adds:

• Animated crate catalogs
• Dedicated crate screens
• Opening ceremonies
• Pixelmon Pokémon previews
• Reward odds and rarity displays
• Claims and history pages
• Scrolling interfaces
• Custom theme sounds
• Rarity win sounds
• Reduced-motion mode
• Compact display mode
• Per-channel volume controls
• Opening tick controls
• Transition controls
• Local theme previewing

The server remains authoritative over credits, rolls, pity, stock, delivery, permissions, exact odds, and crate availability.

Local client settings can reduce presentation but cannot alter server rules.

Crate Themes

StellarCrates includes 30 custom crate themes:

• event_horizon
• nebula_conservatory
• astral_forge
• celestial_orrery
• quantum_vault
• supernova_theatre
• wormhole_transit
• cosmic_aquarium
• starship_bridge
• lunar_archive
• meteor_museum
• aurora_cathedral
• pulsar_radio
• zodiac_bazaar
• infinity_garden
• chronos_paradox
• dreamweaver_loom
• leviathan_sanctum
• prism_masquerade
• atlas_memory_engine
• team_rocket_hq
• pokemon_center
• indigo_league
• professor_lab
• fossil_resurrection
• safari_expedition
• contest_spectacular
• eeveelution_nexus
• ultra_space
• legendary_shrine

Each theme has its own scene geometry, interface structure, controls, ambient movement, and reward reveal choreography.

Main Menu Themes

The crate catalog includes 10 server-selected themes:

• grand_hotel
• stellar_crown
• chronorail_terminal
• galactic_arcade
• abyssal_sonar
• dream_auction
• botanical_helix
• quantum_detective
• origami_atelier
• mythic_planetarium

The server controls the active catalog theme.

Players may preview themes locally where allowed, but they cannot override the server’s configured theme for normal use.

Sound System

Each catalog theme can define sounds for:

• Entering the catalog
• Changing selection
• Starting an opening
• Locking the committed result
• Revealing the final reward

Separate rarity sounds are supported for:

• Common
• Uncommon
• Rare
• Epic
• Legendary
• Mythic
• Jackpot

Players can independently configure master, interface, catalog, opening, and rarity volume channels.

The final rarity cue plays only when the authoritative committed result is revealed.

Storage

StellarCrates supports:

• SQLite
• MySQL
• MariaDB
• PostgreSQL

SQLite is intended for one server using local disk.

Multi-server networks should use MySQL, MariaDB, or PostgreSQL with:

• The same shared database
• The same network scope
• Coordinated crate definitions
• Synchronized system clocks
• Compatible mod and schema versions

StellarCrates does not use an unsafe memory-only authoritative fallback.

If storage is unavailable, new openings fail closed rather than risking free rewards, lost balances, or duplicate delivery.

Security

StellarCrates includes configurable security for:

• Voucher signatures
• Voucher expiration
• Player-bound vouchers
• Command reward allowlists
• Webhook host allowlists
• HTTPS webhook requirements
• Required administrator reasons
• Player address hashing
• Request debounce
• Concurrent opening limits
• Pending claim limits
• Audit logging
• Bounded storage and webhook queues

Administrative balance, pity, stock, voucher, transfer, claim, repair, and recovery operations can be permanently audited.

Recovery and Reliability

Interrupted openings are reconciled after startup, login, and during scheduled recovery passes.

Depending on the stored state, an interrupted opening will:

• Release an unused pre-roll reservation
• Resume delivery of the committed reward
• Create a pending claim
• Enter administrative review when external delivery cannot be proven

The same opening is never intentionally rerolled during recovery.

Commands and external integrations can create uncertainty if another system performs an action before StellarCrates records the result. These operations enter an administrative hold instead of being repeated blindly.

Migration Support

StellarCrates includes migration tools for:

• PhoenixCrates
• EnvyCrates
• ExcellentCrates
• CrazyCrates
• Aquatic Crates

Migration tools convert supported crate definitions, pools, rewards, costs, commands, permissions, and presentation settings.

Imported crates remain disabled until an administrator:

1. Reviews the migration report

2. Fixes incompatible IDs or commands

3. Validates the generated configuration

4. Simulates reward probabilities

5. Tests reward delivery

6. Enables the approved crate

Player balances, physical keys, history, and proprietary runtime databases are not silently duplicated from the original crate plugin.

Validation and Simulation

Administrators can validate an entire candidate configuration before activating it.

A failed reload does not partially replace the active crate catalog.

Probability simulations can perform up to one million test rolls using an optional fixed seed.

Simulation does not:

• Spend credits
• Change pity
• Decrease stock
• Deliver rewards
• Create history

Administrators can use the same seed and iteration count to compare probability changes between crate revisions.

StellarGTS Integration

StellarCrates supports secure marketplace integration with StellarGTS.

Players can list:

• Universal Stellar Credits
• Individual crate-specific credits

Credits are not converted into physical key items.

Instead, StellarCrates creates atomic marketplace escrow and removes the listed amount from the seller’s available balance before the listing becomes active.

The integration protects against:

• Credit duplication
• Double purchases
• Packet replay
• Repeated clicks
• Concurrent proxy servers
• Restart retries
• Duplicate seller payouts

StellarCrates remains the source of truth for every credit movement while StellarGTS handles marketplace presentation and payment.

Player Commands

/crates

Opens the crate catalog.

/crates open <crate> [amount]

Requests one or more crate openings.

/crates preview <crate>

Opens a crate’s detail and reward view.

/crates balance

Displays available credit balances.

/crates claims

Opens pending reward claims.

/crates history

Displays recent opening history.

/crates redeem <voucher>

Redeems a signed voucher.

/crates transfer <player> <credit> <amount>

Transfers virtual credits when the server allows player transfers.

Administrator Tools

Administrators can:

• Create starter crate definitions
• Export held items
• Export party Pokémon
• Validate all content
• Reload content transactionally
• Grant, remove, or set credits
• Inspect and modify pity
• Inspect and modify finite stock
• Simulate crate probabilities
• Generate odds reports
• Issue and invalidate vouchers
• Inspect interrupted openings
• Reconcile pending transactions
• Reassign claims
• Inspect storage health
• Create SQLite backups
• Attach protected crate blocks
• Import supported third-party crate configurations
• Review metrics and system health

Server-Authoritative Design

All credits, rewards, probabilities, pity, stock, claims, history, vouchers, storage, eligibility, and delivery are controlled by the server.

The optional client companion only displays validated catalog data and committed opening results.

Installing or modifying the client companion does not allow players to:

• Create credits
• Select rewards
• Change probabilities
• Advance or reset pity
• Restore finite stock
• Bypass limits
• Reroll openings
• Duplicate claims
• Change delivery results

The StellarCrates Team