World

How to add custom biomes and their arenas, arena environment themes, campaigns, between-level events, and Village / Bartering Station scenes to Craftics.

Biomes

Biomes are the arenas players fight through. Each biome has a grid size, floor and obstacle blocks, an environment theme, an enemy pool, and a loot table. The active campaign determines the order biomes are played in. A biome's order value sequences biomes that are not placed by the active campaign and acts as a tiebreaker, so an addon biome with "order": 50 sorts after any built-in biome with a lower order and before any with a higher one.

Biomes can be added two ways: through a JSON datapack file (no code required) or programmatically through CrafticsAPI.registerBiome(). The JSON path is simpler for pure content; the code path is needed when you want to share a BiomeTemplate object built entirely in Java.

A biome works with the JSON alone: Craftics generates its arenas from the grid size and floor blocks. To give it arenas you built yourself, add schematics as described in Arenas for a biome.

Biome card art

The title screen and the level-select screen show a square cover image per biome. Craftics looks for it by biome id, in your own namespace:

Your namespace rather than a shared folder under Craftics', so you ship art without coordinating a directory layout with anyone, and two addons that both name a biome route_1 cannot overwrite each other's cards.

Ship nothing and the screens draw a flat backdrop tinted with the biome's region color instead. That is a supported outcome, not a broken one - art is optional.

JSON Datapack

Place a JSON file at data/<namespace>/craftics/biomes/<biome_id>.json. Craftics discovers every file at that path automatically on resource reload. Use /reload to hot-reload biome JSON without restarting the server.

{
  "id": "mymod:cavern",
  "name": "Cavern",
  "order": 20,
  "levels": 5,
  "grid": {
    "base_width": 10,
    "base_height": 10,
    "width_growth": 1,
    "height_growth": 1
  },
  "floor_blocks": ["minecraft:stone_bricks", "minecraft:mossy_stone_bricks"],
  "obstacle_blocks": ["minecraft:cobblestone_wall"],
  "obstacle_density": 0.1,
  "obstacle_density_growth": 0.02,
  "environment": "cave",
  "night": true,
  "enemies": {
    "passive": [
      {"type": "minecraft:bat", "weight": 3, "hp": 2, "attack": 0, "defense": 0, "range": 1}
    ],
    "hostile": [
      {"type": "minecraft:skeleton", "weight": 8, "hp": 10, "attack": 3, "defense": 0, "range": 3},
      {"type": "minecraft:spider",   "weight": 6, "hp": 8,  "attack": 3, "defense": 0, "range": 1},
      {"enemy": "mymod:cave_witch", "weight": 3}
    ],
    "boss": {"type": "minecraft:warden", "hp": 50, "attack": 8, "defense": 4, "range": 2}
  },
  "loot": [
    {"item": "minecraft:diamond",   "weight": 5},
    {"item": "minecraft:iron_ingot","weight": 15}
  ],
  "enchantment_loot": [
    {"enchantment": "minecraft:sharpness", "weight": 3}
  ]
}

Field Reference

Java API

To register a biome from code, build a BiomeTemplate and pass it to CrafticsAPI.registerBiome(). You can also call CrafticsAPI.getTotalLevels() at any time to query the total level count across all registered biomes.

// In your CrafticsAddon.onCrafticsInit():
CrafticsAPI.registerBiome(myBiomeTemplate);

// Query total level count
int totalLevels = CrafticsAPI.getTotalLevels();

The Biome Atlas page

Every registered biome gets a guide book page automatically, under the Biome Atlas category. You do not register it, and there is nothing to keep in sync: the page is built from your BiomeTemplate at the moment the server sends it, so retuning a loot weight or swapping a mob into a pool changes the page with it.

Each page shows the biome's level count, whether it is fought at night, its environmental effect and the level that effect starts on, the boss, and both sources of loot. Item names and icons are resolved on the client, so an item your addon adds shows its own name and texture.

An Enemies & Drops page lists every creature in the biome by its mob head, with its role and its own drop table. A creature with no drop table still appears, saying so, rather than being left out.

Pages are gated on discovery. Until the island has run the biome, its page exists but is empty, and the contents are not merely hidden on the client - the server does not send them. Discovery is recorded against the island (the party leader's record), so party members share one atlas.

Environments

An environment defines the visual theme of an arena: which block covers the floor, which block forms the border light-posts, which block sits on top of each post as a light source, and which built-in decoration style is used for flavor obstacles. Biomes select an environment with their "environment" field.

Craftics ships built-in environments for plains, forest, desert, jungle, river, mountain, snowy, cave, nether_wastes, end, and deep_dark. Addons can register new ones via a JSON datapack or the Java API.

JSON Datapack

Place a JSON file at data/<namespace>/craftics/environments/<env_id>.json. Only id is required; the block fields fall back to plains defaults (grass block floor, oak fence posts, lantern lights) when omitted.

{
  "id": "mymod:aether",
  "floor_block": "minecraft:quartz_block",
  "post_block":  "minecraft:quartz_pillar",
  "light_block": "minecraft:sea_lantern",
  "decor_style": "forest"
}

Field Reference

Java API

Use EnvironmentDef.builder(id) for a fluent build, then pass the result to CrafticsAPI.registerEnvironment(). You can verify registration with CrafticsAPI.hasEnvironmentStyle(id).

import com.crackedgames.craftics.api.EnvironmentDef;
import net.minecraft.block.Blocks;

// In your CrafticsAddon.onCrafticsInit():
CrafticsAPI.registerEnvironment(
    EnvironmentDef.builder("mymod:aether")
        .floorBlock(Blocks.QUARTZ_BLOCK)
        .postBlock(Blocks.QUARTZ_PILLAR)
        .lightBlock(Blocks.SEA_LANTERN)
        .decorStyle("forest")
        .build()
);

// Check registration
boolean exists = CrafticsAPI.hasEnvironmentStyle("mymod:aether");

EnvironmentDef builder methods

Arenas for a biome

The biome JSON says what is fought. A schematic says where. Every level is played in an arena, which comes from a schematic when the biome has one and is generated from the JSON when it does not. Building a schematic, placing its marker blocks and testing it are covered in Custom Arena Maps. This section is how the two files find each other.

Where a biome's arenas live

The folder is worked out from the biome's id. A built-in biome has no namespace and lives under Craftics' own. A biome you add lives under yours, so two addons that both name a biome cavern cannot overwrite each other.

Inside the folder go 1.schem to 10.schem, numbered from 1 with no gaps, and boss.schem. A biome with "levels": 5 plays four ordinary levels and then the boss. The ordinary levels cycle through the numbered files and the boss uses boss.schem. With no boss.schem, the boss is fought in one of the numbered arenas.

data/
  mymod/
    craftics/
      biomes/
        cavern.json        "id": "mymod:cavern"
    arenas/
      cavern/
        1.schem
        2.schem
        boss.schem

While you are building, the same files can sit loose in the game folder instead, at craftics_arenas/mymod/cavern/.

What each file decides

A biome with no schematics at all is complete as it stands. Add them when you want a place that looks like somewhere.

Replacing a built-in biome's arenas

No JSON is needed for this. Use the built-in folder name: a data pack holding data/craftics/arenas/desert/1.schem replaces Desert arena 1. Custom Arena Maps lists the folder names and the rules for loose files, and the Example_Arena_Addon folder in the repository is a data pack that does exactly this for Plains.

Campaigns

A campaign is a full custom playthrough: an ordered list of regions, each holding an ordered list of biome nodes. The campaign is what actually drives the run, deciding which biomes the player fights through and in what order. Craftics ships a built-in craftics:vanilla campaign with three regions (Overworld, Nether, End).

Campaigns use full-replace semantics. A registered campaign replaces the vanilla progression entirely, rather than appending to it. Only one campaign is active per world: the most-recently-registered non-vanilla campaign wins, and vanilla is the default when no addon campaign is registered. This makes a campaign the right tool for a total-conversion playthrough, not for adding a few biomes alongside the base game.

The last node of the last region is the final boss. Beating it completes the campaign and triggers New Game+. This is count-agnostic, so a single-region campaign with one biome completes on that biome's boss, and a five-biome campaign completes on the fifth biome's boss.

JSON Datapack

Place a JSON file at data/<namespace>/craftics/campaigns/<id>.json. Craftics discovers every file at that path on resource reload. The canonical worked example is the built-in vanilla campaign at data/craftics/craftics/campaigns/vanilla.json.

{
  "id": "mymod:descent",
  "display_name": "The Descent",
  "regions": [
    {
      "id": "surface",
      "display_name": "Surface",
      "color": "§a",
      "icon": "",
      "map_color": "FF6BBF59",
      "nodes": [
        { "biome": "mymod:village" },
        { "biome": "mymod:wildwood", "label": "The Wildwood" }
      ]
    }
  ],
  "branch": {
    "region": "surface",
    "swap": ["mymod:village", "mymod:wildwood"]
  }
}

Top-level fields

Region fields

Node fields

Branch fields

The optional branch lets a single region present a choice. When the player picks branch choice 1, the two named biomes (or two named segments) are swapped. The two biomes or segments must be contiguous in the named region; an invalid swap falls back to a linear region and is logged.

Java API

Build a campaign with Campaign.builder(id) and its CampaignRegion.builder(id) regions, then pass the result to CrafticsAPI.registerCampaign(). Use CampaignBranch.of(region, a, b) for the single-biome swap convenience, or construct a CampaignBranch directly with two lists for a segment swap.

import com.crackedgames.craftics.level.campaign.Campaign;
import com.crackedgames.craftics.level.campaign.CampaignRegion;
import com.crackedgames.craftics.level.campaign.CampaignBranch;
import java.util.List;

// In your CrafticsAddon.onCrafticsInit():
CrafticsAPI.registerCampaign(
    Campaign.builder("mymod:descent")
        .displayName("The Descent")
        .region(
            CampaignRegion.builder("surface")
                .displayName("Surface")
                .color("§a")
                .icon("")
                .mapColor(0xFF6BBF59)
                .node("mymod:village")
                .node("mymod:wildwood", "The Wildwood")
                .build()
        )
        // Single-biome swap convenience
        .branch(CampaignBranch.of("surface", "mymod:village", "mymod:wildwood"))
        // Segment swap: new CampaignBranch("surface", List.of("a", "b"), List.of("c", "d"))
        .build()
);

Events

Between-level events fire after a combat level completes. Craftics rolls through all registered events by probability and triggers one when the roll succeeds. Events are code-only for now: there is no JSON datapack loader for events. Register them through CrafticsAPI.registerEvent().

EventEntry fields

Construct an EventEntry record directly and pass it to CrafticsAPI.registerEvent().

import com.crackedgames.craftics.api.registry.EventEntry;
import com.crackedgames.craftics.api.EventHandler;

CrafticsAPI.registerEvent(new EventEntry(
    "mymod:treasure_chest",  // unique event id
    "Treasure Chest",        // display name shown in the event popup
    0.15f,                   // probability per level (0.0 to 1.0)
    2,                       // minBiomeOrdinal: earliest biome (0-indexed) where this can appear
    true,                    // isChoiceEvent: true if the player picks from multiple options
    myEventHandler           // EventHandler implementation
));

EventHandler interface

EventHandler is a functional interface. Its execute method receives the list of participating players, the server world, and the EventManager, which provides helpers for showing UI popups, giving items, applying effects, and managing event state.

@FunctionalInterface
public interface EventHandler {
    void execute(List<ServerPlayerEntity> participants,
                 ServerWorld world,
                 EventManager eventManager);
}

Turning an event into a fight

An event does not have to end in rewards. It can replace the level that follows it, which is how a trainer battle, a gym, or an ambush is built: the event is the encounter, and the level it queues is the fight.

Set the level on the EventManager your handler was handed. Craftics reads it back after your handler returns and builds that level instead of the one it had queued.

CrafticsAPI.registerEvent(new EventEntry(
    "mymod:trainer_battle",
    "Trainer Battle",
    0.15f,
    1,
    false,  // forced: no accept/decline prompt, it just happens
    (participants, world, eventManager) -> {
        for (ServerPlayerEntity p : participants) {
            p.sendMessage(Text.literal("§eA trainer blocks the road!"), false);
        }
        // The next "level" is the battle itself.
        eventManager.setPendingNextLevel(buildTrainerLevel());
    }
));

If your handler starts a fight itself rather than queuing one, leave the pending level alone. Craftics checks whether combat is already running and will not build a second arena on top of yours.

Forcing an event

During development or for scripted sequences you can force a specific event to trigger at the next between-level transition for a given player. Pass null to clear any forced event.

// Force the next event for a specific player
CrafticsAPI.forceNextEvent(player, "mymod:treasure_chest");

// Clear the forced event
CrafticsAPI.forceNextEvent(player, null);

Example: custom event

CrafticsAPI.registerEvent(new EventEntry(
    "mymod:healing_spring",
    "Healing Spring",
    0.10f,
    1,      // available from biome index 1 onwards
    false,  // not a choice event, it just fires
    (participants, world, eventManager) -> {
        for (ServerPlayerEntity player : participants) {
            player.heal(4.0f);
        }
    }
));

Village & Bartering Station scenes

The Village and Bartering Station are walk-around hub scenes the player teleports into from the level select. A scene is built from a schematic, like an arena, using three scene marker blocks: one that sets where the player appears, a pair that marks the clickable area of each merchant booth ("stand"), and one that places the booth's NPC. You build the layout in-world or in a schematic editor, drop the .schem in the scenes folder, and Craftics scans the markers when the scene loads.

The marker blocks

Building a scene, step by step

1. Build the booth structures and walkways however you like, using any blocks. This is the visible scene.
2. Place one craftics:scene_spawn on the floor where the player should appear, facing the booths.
3. At each booth, place two craftics:stand_marker blocks at opposite corners of the area you want to be clickable for that booth.
4. Place one craftics:npc_marker inside that rectangle, where the NPC should stand, facing the player's approach. This both positions the NPC and ties the two corners together into one booth.
5. Select the whole build (including the markers) and export it as a Sponge .schem (WorldEdit / Litematica / FAWE all produce this format, the same one arenas use).
6. Drop the file at data/craftics/scenes/village.schem or data/craftics/scenes/barter_station.schem in a datapack, or override it on disk by placing it in a craftics_scenes/ folder next to the server run directory. The disk copy wins if both exist, so you can iterate without rebuilding the jar.

Assigning booth occupants

A booth's occupant decides which merchant stands there, and it lives on the booth's npc_marker. Occupants are not baked into the schematic: schematic export saves block states but not a marker's stored data, so an NPC marker loaded from a .schem comes in blank. Instead the scene assigns occupants when it is built, keyed by booth index (the deterministic order the scanner produces, sorted by the rectangle's corner). This keeps "where the booths are" (the schematic) separate from "who staffs them" (live progression), so a booth can show its merchant for one player and sit empty for another who has not met them yet.

An occupant id is one of:

/data merge block ~ ~ ~ {Occupant:"craftics:weaponsmith"}

Reusing a scene as an addon

Because the scenes are loaded from data/<namespace>/craftics/scenes/<name>.schem via datapack, an addon can ship its own village.schem / barter_station.schem to replace the built-in layout, and the booth occupants resolve from the merchant registries at build time. A modded trader or barter category that has been met automatically appears at the matching overflow booth (villager:addon / piglin:addon) with no schematic change required.