Plasmid

Plasmid is a specialized library for creating server-side minigames in Minecraft on the Fabric platform. The main goal of this tool is to handle all the routine work associated with the technical implementation of game mechanics, allowing developers to fully focus on the creative aspects of their projects.

This library serves as the fundamental component of the Nucleoid project - a large-scale initiative to create an open ecosystem for server-side minigames in Minecraft. On the Nucleoid GitHub organization, you can find numerous ready-made examples of games implemented using Plasmid.

Getting Started

For a quick start, it's recommended to clone the plasmid-starter repository, run the init.py script, and then remove the service files .git, README.md, and init.py. You can also study already implemented projects in the Nucleoid Organisation repositories to better understand the library's capabilities.

Adding to Gradle Project

After setting up the Fabric working environment, you need to add Plasmid to the gradle build file. You need to specify the maven repository and plasmid dependency, replacing PLASMID_VERSION with the current version from the Maven repository.

repositories {
  maven { url = 'https://maven.nucleoid.xyz/' }
}

dependencies {
  // ...
  modImplementation 'xyz.nucleoid:plasmid:PLASMID_VERSION'
}

Creating Game Type

The key concept in Plasmid is "game type" (GameType) - this is the main entry point for creating minigames. Each GameType has a unique identifier and contains all the necessary information to launch the game logic.

The library is built around the concept of game configurations - JSON files that define specific variations of a game type. This allows easy creation of different versions of the same game with different maps or mechanics without code duplication.

GameType registration is performed by calling GameType.register() in the ModInitializer class:

GameType.register(
        new Identifier("plasmid_example", "example"),
        ExampleGameConfig.CODEC,
        ExampleGame::open
);

Game Configuration

Configuration files should be located at data//games/.json. The mandatory field is "type", which points to the registered GameType. Additionally, you can define the game name, description, and icon.

Example configuration:

{
  "type": "plasmid_example:example",
  "name": "Hello World Example!",
  "description": ["Look at my cool game!", "It greets you when you join."],
  "icon": "minecraft:apple"
}

Game Logic

The main game logic is implemented through a game class that handles player addition events, world setup, and game rules. Plasmid provides convenient APIs for working with game space (GameSpace), player management, and event handling.

Example implementation of a basic game with a welcome message:

public final class ExampleGame {
    private final ExampleGameConfig config;
    private final GameSpace gameSpace;
    private final ServerWorld world;

    public ExampleGame(ExampleGameConfig config, GameSpace gameSpace, ServerWorld world) {
        this.config = config;
        this.gameSpace = gameSpace;
        this.world = world;
    }

    public static GameOpenProcedure open(GameOpenContext<ExampleGameConfig> context) {
        ExampleGameConfig config = context.config();

        MapTemplate template = MapTemplate.createEmpty();
        template.setBlockState(new BlockPos(0, 64, 0), Blocks.STONE.getDefaultState());

        TemplateChunkGenerator generator = new TemplateChunkGenerator(context.server(), template);

        RuntimeWorldConfig worldConfig = new RuntimeWorldConfig()
                .setGenerator(generator)
                .setTimeOfDay(6000);

        return context.openWithWorld(worldConfig, (activity, world) -> {
            ExampleGame game = new ExampleGame(config, activity.getGameSpace(), world);

            activity.deny(GameRuleType.FALL_DAMAGE);
            activity.listen(GamePlayerEvents.OFFER, game::onPlayerOffer);
            activity.listen(GamePlayerEvents.ADD, game::onPlayerAdd);
        });
    }

    private PlayerOfferResult onPlayerOffer(PlayerOffer offer) {
        ServerPlayerEntity player = offer.player();
        return offer.accept(this.world, new Vec3d(0.0, 64.0, 0.0))
                .and(() -> {
                    player.changeGameMode(GameMode.ADVENTURE);
                });
    }

    private void onPlayerAdd(ServerPlayerEntity player) {
        LiteralText message = new LiteralText(this.config.greeting);
        this.gameSpace.getPlayers().sendMessage(message);
    }
}

Testing

After successful project compilation, you can launch Minecraft and test the game using the /game open command, where corresponds to the configuration JSON file name. Other players can join using the /game join command or via the link in the chat.

Plasmid significantly simplifies the process of creating server-side minigames by providing powerful tools for working with game worlds, player management, and event handling, allowing developers to focus on creating engaging gaming experiences.