Queue and Matching

Queue and Matching

Wonder’s main loop is simple:

1. A player queues one Pokemon into a channel.
2. Wonder validates the Pokemon and the channel rules.
3. The match coordinator tries to pair that entry with another queued player.
4. If no valid player match exists, Wonder can fall back to the configured trade pool for that channel.

Queue Submission

When a player queues a Pokemon, Wonder:

• checks the channel exists and is enabled
• enforces maxQueuedPerPlayerPerChannel
• checks queue capacity for that channel
• applies any active cooldown
• extracts and removes the Pokemon from party or PC
• rejects untradeable Pokemon
• rejects duplicates already queued in the same channel
• applies the channel’s level, species, shiny, legendary, mythical, and aspect rules

If validation succeeds, the queue entry is written into the event stream and persisted.

Cooldowns

Wonder resolves queue cooldowns through WonderCooldownPolicy:

1. the channel’s cooldown-meta-channel-key-format
2. the channel’s cooldown-meta-global-key
3. the channel’s numeric cooldown-seconds

That means a channel can ship a normal cooldown but still let LuckPerms meta override it for ranked players.

Matching Order

The match coordinator only performs matches when Wonder is not in WORKER mode.

For each enabled channel:

1. take the oldest queued entry
2. look for a different player in the same channel who still passes that channel’s rules
3. if one exists, exchange the two payloads
4. if none exists and the channel references an enabled pool-id, draw a Pokemon from that trade pool instead

Banding

channels.conf supports:

• banding = "none" for unrestricted matching
• banding = "rarity" for rarity-aware pairing

With rarity banding, Wonder groups entries into:

• mythical
• legendary
• shiny
• standard

Two queued players only match if they land in the same band.

Trade Pool Fallback

If a player match cannot be made, Wonder checks the channel’s pool-id.

When a pool match happens:

• Wonder removes one entry from the pool at random
• Wonder inserts the submitted Pokemon back into that pool
• Wonder returns the selected pool Pokemon as the ready result

This keeps the pool cycling over time instead of acting like a one-way reward table.

Cancellation

If allow-cancel-queued = true, players can cancel their own queued Pokemon before it gets matched:

/wonder cancel

Wonder restores the Pokemon to the player’s party and removes the queue entry.