JJRacesGuard

A small server-side addon for the JJRaces Port by Noradith (NeoForge 1.21.1), which is itself a port of the original JJ Races mod by JdiJack_.

Credits first

• JdiJack_ created the original JJ Races mod and all the race models, textures, and customization system. All credit for the core concept and assets goes to them: https://www.curseforge.com/minecraft/mc-mods/jj-races
• Noradith ported JJ Races to NeoForge 1.21.1 as JJRaces Port, which JJRacesGuard depends on and patches: https://www.curseforge.com/minecraft/mc-mods/jjraces-port

JJRacesGuard does not replace, modify the files of, or redistribute either of those mods. It's a separate addon that patches JJRaces Port's behavior at runtime via Mixin, and requires it installed to work.

Why this exists

While setting up JJRaces Port for our own roleplay server, we found that the race-change confirmation on the server side had a gap: when the customization menu is opened with the keybind instead of the Mirror/Comb items, the server approved the race change unconditionally — no item requirement, no permission check, no cooldown. Any player could open the menu with the key and switch races freely, as many times as they wanted.

On top of that, the port doesn't generate any configuration file, so there was no way to restrict specific races, add a cooldown, or make the Mirror/Comb consumable — they're reusable indefinitely out of the box.

JJRacesGuard fixes the keybind gap and adds the configuration options that were missing, without touching JJRaces Port's own files.

What it adds

1. Fixes the free keybind race change Changing race via the key now requires operator permission (level 2) by default - configurable, and bypassable per player/group if you use LuckPerms (see below). Changes made with the Mirror or Comb items are unaffected by this rule.

2. Server config (generated on first launch, at config/jjracesguard-server.toml)

• blockedRaces: list of races players cannot pick (server-wide).
• cooldownSeconds: minimum time between approved race changes.
• Separate toggles to let operators bypass the blocked-race list and/or the cooldown.
• Optional logging of every approved race change to the server console.

3. Optional LuckPerms integration JJRacesGuard registers its permission nodes through NeoForge's own Permission API — it does not require LuckPerms to compile or run.

• Without LuckPerms: every node falls back to "operator level 2", identical behavior to using the config alone.
• With LuckPerms: it takes over automatically (same as any NeoForge mod using the Permission API), and you get per-group / per-player control via /lp, including a dedicated node per race (jjracesguard.race.use.<race>) so you can restrict, say, Orc to a specific rank without blocking it server-wide.

4. Consumable Mirror & Comb In the original port, both items are stackable to 1 but never consumed — they stay in your inventory forever. JJRacesGuard makes them consume 1 use per successful race change. Keybind changes and Creative-mode players are unaffected (nothing gets consumed there).

5. RCON commands, for external tools/websites Meant to be run from console/RCON (permission level 4), for an external backend (e.g. a server website) to read or force a player's race:

• /jjracesguard race get <player> → replies raza:<race>
• /jjracesguard race set <player> <race> → replies ok:<race>, or error:... if it fails (invalid race name, or not enough space for the new race's hitbox)
• /jjracesguard race list → replies with one name:race line per online player

Useful if you want to show each player's race on a web profile, or let admins manage it outside the game.

Compatibility

Currently built and tested against NeoForge 21.1.234, which is the exact build the JJRaces Port itself targets - since the Port only supports that build, JJRacesGuard hasn't been tested on other NeoForge versions either. It's not intentionally locked to 21.1.234 though; if JJRaces Port ever gets updated to a newer NeoForge/Minecraft version, JJRacesGuard is likely to follow without needing much (if any) rework, since it only patches a handful of specific classes.

Installation

1. Install JJRaces Port by Noradith (NeoForge 1.21.1).
2. Drop jjracesguard-1.0.0.jar into your server's mods/ folder, alongside it.
3. (Optional) Install LuckPerms if you want per-group/per-player permission control. Not required.
4. Start the server once to generate config/jjracesguard-server.toml, edit it to your liking, restart.

This is a server-side only mod. Players do not need to install it on their client to join.

Source / feedback

This was built for a personal roleplay server; if you run into issues or want a feature added, feel free to leave a comment.

A personal thank you

JJ Races has been one of my favorite mods for a long time, and I'd honestly given up hope of ever seeing it updated to a modern version. So a huge thank you to Noradith for porting it to NeoForge 1.21.1 and making it possible to keep using it  this addon wouldn't exist without that port. And of course, thank you to JdiJack_ for creating such a great mod in the first place.