World

How to add custom biomes, 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.

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();

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

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);
}

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.