Prism Relay

Prism Relay is a server-authoritative Pixelmon type-chain minigame for Minecraft 1.21.1, NeoForge 21.1.200+, and Pixelmon 9.3.16+.

Players carry a Pokemon type as a baton through a timed route of unique dual-type catches. The server owns every rule, score, reward, save, permission check, and leaderboard record. An optional client companion adds responsive animated interfaces, Pixelmon sprites, accessibility controls, and a dedicated Top 10 display.

Mod suite

Prism Relay is distributed as two independent jars:

prism_relay-1.0.0.jar is the required server mod. It contains the game, commands, configuration, rewards, persistence, permissions, chest interfaces, and networking.
prism_relay_client-1.0.0.jar is the optional client companion. It contains the 30 custom interfaces and visual settings.

The server jar works without the client companion. Players without it use protected vanilla chest menus. Keep the server jar on the dedicated server and install only the companion jar on player clients.

Both jars require Pixelmon. The companion protocol is version 4; update the server and client jars together when replacing a build.

Gameplay

Starting a run assigns one of the 18 standard Pokemon types as the first baton. To create a link:

Catch a unique dual-type Pokemon containing the active baton type.
The Pokemon's other type becomes the next baton.
Continue until the configured number of links is complete, time expires, or monotype grace is exceeded.

Example:

Water -> Lotad -> Grass -> Bulbasaur -> Poison -> Zubat -> Flying

By default, a run requires eight links within thirty minutes. Species cannot be reused during the same run.

Monotype grace

A matching monotype Pokemon does not advance the route and never awards points. It consumes one grace strike instead. With the default game.monotype-grace-strikes: 2:

The first matching monotype records strike 1 of 2 and warns the player.
The second records strike 2 of 2 and warns that one more will end the run.
The third immediately changes the run to FAILED.

Set the allowance from 0 to 10. A value of 0 makes the first matching monotype fatal.

Capture sources

Wild captures, raid captures, and hatches can be enabled independently. Defaults:

Source	Enabled
Wild capture	Yes
Raid capture	Yes
Egg hatch	No

Default scoring and speed multiplier

Valid-link component	Raw points
Valid relay link	100
First visit to the destination type	40
Shiny capture	500
Legendary or mythical capture	150
Raid capture	50

The raw total is multiplied according to how much run time remains. By default, a link caught at the start receives 2.00x, halfway through receives 1.50x, and at the deadline receives 1.00x. The multiplier eases linearly and applies to the base link plus new-type, shiny, legendary, and raid bonuses. Final points are rounded to the nearest whole number.

All point values and the minimum/maximum time multipliers are configurable.

Installation

Dedicated server

Install Minecraft 1.21.1, NeoForge 21.1.200 or newer, and Pixelmon 9.3.16 or newer.
Put server/build/libs/prism_relay-1.0.0.jar in the server mods directory.
Start the server once to create config/PrismRelay/config.yml and messages.yml.
Edit the generated files and run /relay reload or restart the server.

Optional client companion

Install the matching Minecraft, NeoForge, and Pixelmon versions on the client.
Put client/build/libs/prism_relay_client-1.0.0.jar in the client mods directory.
Do not install the main server jar on the client.

The companion identifies itself with an optional handshake. A missing companion never prevents the server mod from loading unless ui.require-client is enabled.

Player commands

Aliases: /relay, /prismrelay, and /pr.

Command	Purpose
`/relay`	Open the preferred interface
`/relay start`	Start a new timed run
`/relay status`	Show baton, timer, score, links, grace strikes, and records in chat
`/relay abandon`	End the active run without completing it
`/relay top`	Open the custom Top 10 screen or chest fallback
`/relay chest`	Force the server-only relay chest interface
`/relay client`	Open the companion interface when installed
`/relay help`	Display the short game rules and commands

Administrative commands

Command	Purpose
`/relay reload`	Reload `config.yml` and `messages.yml`
`/relay reset <player>`	Delete the player's active run and lifetime record
`/relay forcecomplete <player>`	Complete an active run through the normal reward path
`/relay settype <player> <type>`	Replace the active baton; standard type IDs are suggested

Administrative permission defaults use commands.admin-permission, which defaults to operator level 2.

Permissions

Prism Relay registers native NeoForge permission nodes. LuckPerms and other compatible permission providers can override them.

Player nodes default to allowed. Administrative nodes default to the configured operator level.

Permission node	Controls	Default
`prism_relay.prismrelay.play`	Run participation and capture progression	Everyone
`prism_relay.prismrelay.open`	`/relay`	Everyone
`prism_relay.prismrelay.help`	`/relay help`	Everyone
`prism_relay.prismrelay.start`	Starting runs from commands or interfaces	Everyone
`prism_relay.prismrelay.status`	`/relay status`	Everyone
`prism_relay.prismrelay.abandon`	Abandoning runs	Everyone
`prism_relay.prismrelay.top`	Top 10 rankings	Everyone
`prism_relay.prismrelay.chest`	The server chest interface	Everyone
`prism_relay.prismrelay.client`	The optional client interface	Everyone
`prism_relay.prismrelay.reload`	Configuration reloads	Operators
`prism_relay.prismrelay.reset`	Resetting player data	Operators
`prism_relay.prismrelay.forcecomplete`	Force-completing runs	Operators
`prism_relay.prismrelay.settype`	Changing a player's baton	Operators

Permissions are checked independently by commands, server menus, client action packets, and capture progression. A modified client cannot bypass server rules.

Interfaces

Server-only chest interfaces

The server provides two protected six-row vanilla menus:

Relay console: run state, baton, route, score, monotype grace, speed scoring, controls, help, and UI selection.
Top 10 leaderboard: podium, ranks 4-10, best scores, fastest times, completions, personal placement, refresh, and navigation.

Display slots reject placement, pickup, quick-move, drag, and pick-all actions.

Client companion

The companion displays server-authoritative snapshots. It can request actions, but it cannot change a run, score, reward, or leaderboard locally.

Common controls:

Input	Action
`R`	Refresh the relay snapshot
Arrow keys	Inspect the previous or next route link
Mouse wheel	Scroll through route links
`M`	Toggle reduced motion when server animations are enabled
`S`	Toggle local UI sounds when server sounds are enabled
`L`	Toggle compact leaderboard visibility

Local preferences are stored in config/prism_relay_client.json.

Both flagship themes honor the server animation setting and the player's reduced-motion preference. Reduced motion resolves all transitions immediately without removing information or controls.

UI themes

Staff select one theme through ui.theme in config/PrismRelay/config.yml. Players cannot override the server-selected theme.

Theme ID	Interface concept
`constellation`	Celestial chain navigator and telemetry dossier
`field_journal`	Two-page naturalist logbook and field notes
`wanted_poster`	Frontier bounty wall and central baton poster
`radar_sweep`	Tactical acquisition scope and live contact feed
`dna_lab`	Dual-type genome workstation and helix route
`pokedex_handheld`	Physical dual-screen Pokedex relay device
`guild_board`	Cork-and-string contract wall with pinned assignments
`orbital_holo`	Volumetric observatory with moving Pokemon orbits
`biome_atlas`	Parchment topographic survey and expedition waypoints
`minimal_bento`	Quiet modular operations dashboard
`clockwork_relay`	Brass escapement engine and gear-train route
`arcade_cabinet`	CRT score cabinet, scanlines, and high-score rail
`train_signal`	Railway departure board and dispatch manifest
`weather_station`	Meteorological workstation and moving type front
`crystal_cavern`	Geode chamber and faceted signal crystals
`deep_sea_sonar`	Abyssal sonar sweep and depth contact log
`volcanic_forge`	Brick foundry, molten baton furnace, and conveyor
`royal_tapestry`	Heraldic succession court and royal baton crest
`postal_route`	Registered parcel map, routing, and stamps
`cassette_mixer`	Physical tape deck, reels, meters, and waveform
`noir_casefile`	Detective evidence board, red string, and case notes
`dream_cloud`	Pastel dream sky, clouds, and floating route bubbles
`circuit_board`	PCB routing mainboard, chips, buses, and registers
`temporal_archive`	Clock-face chronology and timeline archive
`festival_lanterns`	Night-market procession and hanging lanterns
`skyship_navigation`	Aerial chart table, compass, and flight path
`mosaic_temple`	Tiled pilgrimage chamber and prism altar
`quantum_terminal`	Entangled particle processor and telemetry

Top 10 leaderboard

/relay top and interface Top 10 buttons open a dedicated menu instead of printing rankings in chat.

Companion players receive a themed custom leaderboard screen.
Other players receive the protected chest leaderboard.
Each player appears once, using their personal best completion.
Higher score ranks first.
Equal scores use the faster completion time.
ui.leaderboard-cooldown-seconds limits menu reopening and refresh spam per player.

The custom leaderboard supports R to refresh and Backspace to return to the relay interface.

Configuration

The server creates:

config/PrismRelay/config.yml: game rules, scoring, capture sources, rewards, interface behavior, all theme IDs, reward placeholders, cooldowns, and administrator defaults.
config/PrismRelay/messages.yml: player-facing text, help, status output, errors, and leaderboard messages.
config/PrismRelay/data/players/<uuid>.properties: player saves and leaderboard records.

Run /relay reload after editing either YAML file.

Existing active runs retain the target length and deadline assigned when they started. Reloading configuration does not silently rewrite an in-progress objective.

Important game settings

Setting	Purpose
`enabled`	Master game switch
`game.target-links`	Required route length, clamped from 3 to 14
`game.duration-seconds`	Run time limit
`game.restart-cooldown-seconds`	Minimum time between run starts for one player
`game.monotype-grace-strikes`	Forgiven matching monotypes before the next one fails the run; `0`-`10`
`game.require-unique-species`	Rejects repeat species during one run
`game.notify-invalid-captures`	Displays rejected-capture explanations
`scoring.time-scaling.minimum-percent`	Link multiplier at the deadline; defaults to `100` (`1.00x`)
`scoring.time-scaling.maximum-percent`	Link multiplier at run start; defaults to `200` (`2.00x`)
`ui.prefer-client`	Opens the companion interface first when detected
`ui.allow-chest-fallback`	Allows server-only fallback menus
`ui.require-client`	Requires the companion for the primary relay interface
`ui.theme`	Staff-selected interface theme
`ui.sounds`	Allows companion UI sound controls
`ui.animations`	Allows companion animations and reduced-motion controls
`ui.leaderboard-cooldown-seconds`	Top 10 open/refresh cooldown

Set either cooldown to 0 to disable it.

Rewards

Reward commands run from the server console and may call vanilla, Pixelmon, economy, permissions, crates, or other installed command systems.

Three reward triggers are supported:

rewards.link-commands: after every valid dual-type link.
rewards.completion-commands: once when a run completes.
rewards.score-ranges: one matching final-score band when a run completes.

Base completion commands and the matching score band both execute.

Example:

rewards:
  broadcast-completion: true
  link-commands:
    - "experience add %player% 2 points"
    - "give %player% minecraft:amethyst_shard 1"
  completion-commands:
    - "experience add %player% 100 points"
    - "give %player% minecraft:diamond 3"
  score-ranges:
    0-999:
      - "give %player% minecraft:iron_ingot 8"
    1000-1499:
      - "give %player% minecraft:gold_ingot 8"
    1500-1999:
      - "give %player% minecraft:diamond 5"
    2000+:
      - "give %player% minecraft:netherite_ingot 1"

Score ranges are inclusive. Supported keys:

0-999
0..999
0_to_999
500 for an exact score
2000+ for an open-ended range

Keep ranges non-overlapping. If configured ranges overlap, only the first match in ascending score order is awarded.

Reward placeholders

These placeholders are available to link, completion, and score-range commands:

Category	Placeholders
Player	`%player%`, `%uuid%`
Run	`%state%`, `%state_colored%`, `%links%`, `%target%`, `%score%`, `%points%`, `%raw_points%`
Monotype grace	`%grace_strikes%`, `%grace_limit%`, `%grace_remaining%`, `%monotypes_until_failure%`
Time and speed	`%remaining%`, `%duration%`, `%time_bonus%`, `%time_multiplier%`, `%time_multiplier_percent%`, `%speed_percent%`
Lifetime record	`%best_score%`, `%best_duration%`, `%completions%`, `%attempts%`
Starting type	`%starting_type%`, `%starting_type_id%`, `%starting_type_colored%`
Current type	`%current_type%`, `%current_type_id%`, `%current_type_colored%`
Link origin	`%from_type%`, `%from_type_id%`, `%from_type_colored%`
Link destination	`%to_type%`, `%to_type_id%`, `%to_type_colored%`
Captured Pokemon	`%pokemon%`, `%dex%`, `%shiny%`, `%legendary%`, `%source%`

Score-range commands additionally receive %reward_range%, %reward_min%, and %reward_max%.

Commands may begin with /, but it is optional.

Messages

messages.yml supports:

Legacy & formatting codes.
Hex colors such as <#8B5CF6>.
Two-color gradients such as <gradient:#8B5CF6:#22D3EE>Prism Relay</gradient>.
The same contextual placeholders supplied by the relevant game event.

Persistence and leaderboard safety

Each player is saved independently in a UTF-8 properties file. Saves include:

Active run state and deadline.
Starting and current baton types.
Exact route links and used species.
Monotype grace strikes and the terminal FAILED state.
Time-scaled link scores.
Attempts and completions.
Personal best score and fastest matching completion time.

Writes use a temporary file and atomic replacement where supported. Malformed individual route records are skipped instead of preventing the remaining profile from loading.