Common Rules

IDs

Every content ID has the form <mod id>:<path>. When you declare content, you give only the path. Poly Mod Loader adds the mod ID.

• Use only lowercase letters, digits, _, ., /, and - in a path.
• A duplicate or invalid name fails with POLY-CONTENT-001.
• In code, you handle IDs as ResourceId. It validates the name when you create it.

ResourceId mine = ResourceId.of("ruby_mod", "ruby_block");
ResourceId vanilla = ResourceId.minecraft("stone");
ResourceId parsed = ResourceId.parse("ruby_mod:ruby");

Most declaration methods return a handle (BlockHandle, ItemHandle, EntityHandle …). Use handle.id() to get the ID and handle.isRegistered() to check whether it is registered in the game.

Declaration timing

Declare content, commands, channels, generators, reload listeners, permission nodes, and tests inside an entrypoint.

• Poly Mod Loader registers blocks, block items, and items, in that order, just before the game freezes the registries.
• A declaration after that fails with the area's "registration is closed" error (POLY-CONTENT-002, POLY-COMMAND-002, POLY-WORLDGEN-002, and so on).
• A mod only declares in its entrypoint. Poly Mod Loader validates the declaration immediately, regardless of game version. The game layer turns the declaration into real game objects once the game is ready.

Both sides must match

The client and the server must declare the same content in the same order. The game syncs block states by number. Put content declarations in the common entrypoint.

Threads and view lifetime

• Use views (WorldView, EntityView, PlayerView …) on that world's thread, and only while the callback holds them. Do not store them in fields.
• The thread each callback runs on is listed in each page and in the table in API stability.

Server and client

• Methods that change the world work only on the server. Calling them on the client throws IllegalStateException.
• Behavior callbacks (BlockBehavior, ItemBehavior, and so on) can be called on both sides. Check world.isClientSide() and change state only on the server.

public InteractionResult onUse(BlockUse use) {
    if (!use.world().isClientSide()) {
        use.player().give(SPARK, 1);
    }
    return InteractionResult.SUCCESS;
}

• Returning PASS falls back to the game's default behavior.

Resources

Put models, textures, translations (assets/), and recipes, loot, tags, and world generation (data/) in the mod jar in the vanilla 26.2 format. See Resources and data.

Failures

An invalid declaration fails on the spot with a POLY-area-number code. An exception in a callback at run time is either logged and ignored (for example POLY-SCHEDULE-001) or disables only that feature (for example POLY-CLIENT-003 for a HUD layer). See Error codes.