Prerequisites

You need to have ≥ JDK 21 installed and be able to create Minecraft Forge mods. I recommend using the API template. You'll need to add the CensorCraft API library as a dependency (found in the releases of this repo), along with the simple voice chat and CensorCraft mods as runtime dependencies. Please refer to the API template for example code to get you started.

What can a plugin do?

A CensorCraft plugin is a Forge mod that uses the CensorCraft API. Plugins can define custom punishments and hook into CensorCraft events!

Registering Punishments

To register custom events, you'll hook into the server configuration event, and they'll appear in the server config file just like the built-in punishments, allowing server admins to configure it to their liking with parameters you define.

The plugin template defines an example punishment that depletes your hunger bar, which ends up looking like this in the server config file:

[hunger](/FreshSupaSulley/CensorCraft/wiki/hunger)
	enable = true
	# List of punishment-specific forbidden words and phrases (case-insensitive)
	taboo = [""]
	# Global taboos don't trigger this punishment
	ignore_global_taboos = false
	# The amount of food exhaustion to inflict onto the player
	exhaustion = 500

Notice that the exhaustion parameter is unique to this punishment. When your custom punishment is called to punish a player, you'll be able to retrieve these values set by the server admin as inputs.

Client-side punishments

Usually, you just need the ServerLevel Minecraft object for everything punishment-related. However, if your punishment requires you to run code on the client instead of the server, I recommend hooking into the ClientAcknowledgePunish event. This fires when the client receives the list of punishments that they caused (and resets their audio buffer), and will allow you to check if your punishment was called and do something on the client accordingly (this is how the Crash punishment works).

Getting started

CensorCraft plugins work very similarly to simple voice chat plugins. You'll need to create a class that implements CensorCraftPlugin with an @ForgeCensorCraftPlugin and a default no-arg constructor:

@ForgeCensorCraftPlugin
public class MyCCPlugin implements CensorCraftPlugin {
	
	// Constructor must take no args!
	public MyCCPlugin()
	{
	}
	
	// magic method to hook into CensorCraft events
	@Override
	public void registerEvents(EventRegistration registration)
	{
		registration.registerEvent(ServerConfigEvent.class, this::onServerConfig);
	}
	
	public void onServerConfig(ServerConfigEvent event)
	{
		event.registerPunishment(HungerPunishment.class);
	}

HungerPunishment.class:

public class HungerPunishment extends Punishment {
	
	@Override
	public String getName()
	{
		return "hunger";
	}
	
	@Override
	protected void buildConfig()
	{
		define("exhaustion", 500, "The amount of food exhaustion to inflict onto the player");
	}
	
	@Override
	public void punish(Object serverPlayer)
	{
		((ServerPlayer) serverPlayer).causeFoodExhaustion(((Number) config.get("exhaustion")).floatValue());
	}
}

Events

Here's the list of events you can hook into. Most (but not all) events are cancellable, and you can check with the inherited isCancellable getters. The javadoc for each event has more in-depth descriptions as well.

Event	Side	Description
ServerConfigEvent	Server	Use this to register your own punishments.
PunishEvent	Server	The server is about to punish a player.
ClientAcknowledgePunish	Client	The client received a packet containing the punishments they triggered.
SendTranscriptionEvent	Client	The client is about to send a packet containing their transcription results to the server.

Testing

On macOS, you may have trouble testing this mod in the IDE because simple voice chat is unable to pick up your microphone input due to permission issues. If that's the case, a good alternative approach would be to build the jar file for your mod and test it in CurseForge.

Publishing

When your plugin is battle-tested and works as expected, you're ready to publish it! Run ./gradlew build to generate your mod to build/libs and you're good to publish it (you probably already know that). If you decide to distribute it through CurseForge, make sure to add CensorCraft as a mod dependency.