Developer wiki

---

title: MinigamesMod API description: Learn how to create your own minigames using the MinigamesMod API.

MinigamesMod API

Installation

Maven Repository

repositories {
    maven {
        url "https://api.modrinth.com/maven"
    }
}

Dependency

implementation "maven.modrinth:minigamesmod:${project.minigamesmod_version}+mc-${project.minecraft_version}"

fabric.mod.json

{
  "depends": {
    "...": "...",
    "minigamesmod": "*"
  }
}

---

Creating a Minigame

A minigame usually consists of four classes:

1. The minigame class
2. The game screen
3. A hidden configuration
4. A visible configuration

The following examples use 2048 as a reference implementation.

---

1. Minigame Class

Your minigame should extend AbstractMinigame.

Example:

public class Game2048 extends AbstractMinigame {

    public Game2048() {
        super(
            "2048",
            Component.literal("2048"),
            Identifier.fromNamespaceAndPath(
                MinigamesMod.MOD_ID,
                "textures/minigame/2048_icon.png"
            )
        );
    }

    @Override
    public Class<? extends ConfigData> getConfigClass() {
        return Game2048Config.class;
    }

    @Override
    public Class<? extends ConfigData> getVisibleConfigClass() {
        return Game2048VisibleConfig.class;
    }

    @Override
    public @Nullable Leaderboard getLeaderboard() {
        return new Leaderboard(
            "Game2048",
            List.of(Component.translatable("minigame.2048.condition"))
        );
    }

    @Override
    public Screen createScreen(Screen parent) {
        return new Game2048Screen(this, parent);
    }

    @Override
    public void onLose() {
        PlayingSoundManager.playSound(
            SoundEvents.VILLAGER_NO,
            1,
            vol()
        );
    }

    @Override
    public void onWin() {
        PlayingSoundManager.playSound(
            SoundEvents.FIREWORK_ROCKET_BLAST,
            1,
            vol()
        );
    }

    private float vol() {
        return PlayingSoundManager.vol(
            MinigameRegistry.getConfig(TetrisVisibleConfig.class).volume
        );
    }
}

The class extends AbstractMinigame, which already implements most of the required functionality.

The MinigameDefinition interface contains all API methods available for a minigame.

Leaderboards

Addon mods cannot create their own online leaderboards by default.

If you would like leaderboard support for your minigame, please open an issue on GitHub.

---

2. Game Screen

The game screen contains the actual implementation of your minigame.

This is where rendering, input handling, game logic, animations, and update code should be implemented.

---

3. Hidden and Visible Configurations

Both configuration classes use Cloth Config API together with Auto Config.

The hidden configuration is typically used to store internal data such as the player's best score.

@Config(name = "minigames/2048")
public class Game2048Config implements ConfigData {

    public long bestScore = 0;

}

The visible configuration contains settings that players can change from the configuration screen.

@Config(name = "minigames/2048_ui")
public class Game2048VisibleConfig implements ConfigData {

    @ConfigEntry.BoundedDiscrete(min = 3, max = 8)
    public int gridSize = 4;

    @ConfigEntry.BoundedDiscrete(min = 0, max = 100)
    public int volume = 100;

}

---

4. API Functions

Getting a configuration

Use MinigameRegistry.getConfig() to retrieve a configuration instance.

Game2048Config config = MinigameRegistry.getConfig(Game2048Config.class);

---

Playing sounds

To simplify sound playback, use PlayingSoundManager.

PlayingSoundManager.playSound(soundEvent);

PlayingSoundManager.playSound(soundEvent, pitch, volume);

Utility class:

public class PlayingSoundManager {

    public static void playSound(SoundEvent soundEvent, float pitch, float volume) {
        Minecraft.getInstance().getSoundManager().play(
            SimpleSoundInstance.forUI(soundEvent, pitch, volume)
        );
    }

    public static void playSound(SoundEvent soundEvent) {
        Minecraft.getInstance().getSoundManager().play(
            SimpleSoundInstance.forUI(soundEvent, 1, 1)
        );
    }

    public static float vol(int volumeConfig) {
        return 5 * ((float) volumeConfig / 100);
    }
}

---

Opening the visible configuration

To open the visible configuration screen (for example from a button), call:

MinigameRegistry.openVisibleConfig(minigame, parentScreen);

Where:

• minigame is your MinigameDefinition
• parentScreen is the screen that should be returned to after closing the configuration

---

5. Registering Your Minigame

Register your minigame during client initialization.

For example, inside onInitializeClient():

MinigameRegistry.register(new ExampleMinigame());

After registration, your minigame will automatically appear in the MinigamesMod menu.