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:

Verifies the player and crate
Checks permissions and availability
Checks cooldowns and daily limits
Verifies the player has sufficient credits
Reserves the required balance
Selects the reward using a deterministic seed
Updates pity and finite stock
Stores the complete reward result
Sends the committed result to the client
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:

Reviews the migration report
Fixes incompatible IDs or commands
Validates the generated configuration
Simulates reward probabilities
Tests reward delivery
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