Items & Effects

Register consumables and special-use items, define custom combat status effects, and attach lifecycle combat effect handlers to equipment scanners.

Usable Items

A usable item is any item the player can activate during their Craftics turn: a consumable draught, a thrown explosive, a support item aimed at an ally, or any other in-combat action tied to an item. Registered items are checked before Craftics' built-in item handling, so an addon can introduce entirely new items or remap an existing vanilla item without touching combat code.

Call CrafticsAPI.registerUsableItem(item, entry) from your addon's onCrafticsInit().

API Method

CrafticsAPI.registerUsableItem(Item item, UsableItemEntry entry);

UsableItemEntry Builder

UsableItemEntry entry = UsableItemEntry.builder(myItem)
    .apCost(1)                       // action points spent per use
    .range(0)                        // max tile distance to target (0 = self / no range check)
    .targetType(TargetType.SELF)     // what the player must click
    .consumedOnUse(true)             // whether one of the item is consumed on success
    .handler(myHandler)              // the effect to run (required)
    .build();

CrafticsAPI.registerUsableItem(myItem, entry);

TargetType Values

Craftics uses the TargetType to validate the player's click and to highlight valid tiles before the handler runs.

UsableItemHandler Interface

UsableItemHandler is a @FunctionalInterface. Implement it directly for custom scripted logic, or compose built-in building blocks from ItemEffects. The handler receives a UsableItemContext and returns an ItemUseResult.

@FunctionalInterface
public interface UsableItemHandler {
    ItemUseResult use(UsableItemContext ctx);

    // Chain with another handler (second runs only if first succeeds):
    default UsableItemHandler and(UsableItemHandler next);
}

ItemUseResult

Return one of two factory values. On ok(), Craftics spends the AP cost and optionally consumes the item. On fail(reason), nothing is spent and the reason is shown to the player.

ItemUseResult.ok()              // item used successfully
ItemUseResult.fail("No target there.")  // item failed, keep AP

UsableItemContext

The context exposes the combat state and a set of typed operations so handlers never need to touch Craftics internals.

Built-in Effect Factories (ItemEffects class)

The ItemEffects class provides static factory methods that return composable UsableItemHandler building blocks. Chain them with .and(). Blocks that need a combatant on the targeted tile fail cleanly when the tile is empty, returning the AP to the player.

JSON Datapack Schema

Place usable item JSON files at data/<namespace>/craftics/items/*.json. The effects array is an ordered list of building blocks that run in sequence. Each block must succeed for the next to run. Items needing scripted logic must be registered through CrafticsAPI.registerUsableItem in Java.

Effect object kind values and their extra fields:

{
  "item": "minecraft:golden_apple",
  "ap_cost": 1,
  "range": 0,
  "target": "SELF",
  "consumed": true,
  "effects": [
    { "kind": "heal", "amount": 4 },
    { "kind": "apply_self", "effect": "ABSORPTION", "turns": 4, "amplifier": 0 }
  ]
}

Code Example

import com.crackedgames.craftics.api.CrafticsAPI;
import com.crackedgames.craftics.api.ItemEffects;
import com.crackedgames.craftics.api.TargetType;
import com.crackedgames.craftics.api.registry.UsableItemEntry;
import com.crackedgames.craftics.combat.CombatEffects;

// Healing draught: heal 8 HP and apply Absorption for 4 turns
CrafticsAPI.registerUsableItem(MyItems.HEALING_DRAUGHT,
    UsableItemEntry.builder(MyItems.HEALING_DRAUGHT)
        .apCost(1)
        .targetType(TargetType.SELF)
        .consumedOnUse(true)
        .handler(ItemEffects.heal(8)
            .and(ItemEffects.applyToSelf(CombatEffects.EffectType.ABSORPTION, 4, 0)))
        .build());

// Poison vial: deal 4 damage and apply Poison to a single enemy
CrafticsAPI.registerUsableItem(MyItems.POISON_VIAL,
    UsableItemEntry.builder(MyItems.POISON_VIAL)
        .apCost(1)
        .range(3)
        .targetType(TargetType.SINGLE_ENEMY)
        .consumedOnUse(true)
        .handler(ItemEffects.damageTarget(4)
            .and(ItemEffects.applyToTarget(CombatEffects.EffectType.POISON, 3, 0)))
        .build());

Custom Status Effects

Craftics has 23 built-in status effects keyed by the CombatEffects.EffectType enum. Custom effects extend that set with a string id instead of an enum constant, so addons can introduce their own debuffs and buffs without forking the mod. A custom effect ticks once per round for each combatant carrying it: the declarative hpChangePerTurn is applied first, then the optional CustomEffectTickHandler runs for scripted logic.

Call CrafticsAPI.registerEffect(def) from your addon's onCrafticsInit(). A registered effect ticks once per round on any combatant carrying it. UsableItemContext.applyCustomEffect, the planned way for an item to place a custom effect on a combatant, is currently a no-op reserved for a future SDK phase.

API Method

CrafticsAPI.registerEffect(CustomEffectDef def);

CustomEffectDef Builder

CustomEffectDef def = CustomEffectDef.builder("mymod:frostbite")
    .displayName("Frostbite")
    .description("-2 HP per turn")
    .colorCode("§b")
    .harmful(true)
    .hpChangePerTurn(-2)
    .tickHandler(myTickHandler)    // optional
    .build();

CrafticsAPI.registerEffect(def);

CustomEffectTickHandler Interface

CustomEffectTickHandler is a @FunctionalInterface. It runs once per round, per combatant carrying the effect, after hpChangePerTurn has already been applied. Effects that only need a flat HP change do not need a handler at all.

@FunctionalInterface
public interface CustomEffectTickHandler {
    void onTick(CombatEntity entity, int amplifier, int turnsRemaining);
}

JSON Datapack Schema

Place status effect JSON files at data/<namespace>/craftics/effects/*.json. Datapack effects are declarative: they support a flat per-turn HP change but no scripted tick logic. Effects needing a CustomEffectTickHandler must be registered through CrafticsAPI.registerEffect in Java.

{
  "id": "mymod:frostbite",
  "name": "Frostbite",
  "description": "-2 HP per turn",
  "color": "§b",
  "harmful": true,
  "hp_change_per_turn": -2
}

Code Example

import com.crackedgames.craftics.api.CrafticsAPI;
import com.crackedgames.craftics.api.CustomEffectDef;

// Frostbite: a simple damage-over-time debuff, registered from a datapack or in code
CrafticsAPI.registerEffect(CustomEffectDef.builder("mymod:frostbite")
    .displayName("Frostbite")
    .description("-2 HP per turn")
    .colorCode("§b")
    .harmful(true)
    .hpChangePerTurn(-2)
    .build());

// Festering Wound: a damage-over-time effect that flares up as it fades.
// A tick handler receives only the carrying entity, its amplifier, and the
// turns remaining, so it acts on that entity.
CrafticsAPI.registerEffect(CustomEffectDef.builder("mymod:festering_wound")
    .displayName("Festering Wound")
    .description("-1 HP per turn, with a burst of damage as it fades")
    .colorCode("§2")
    .harmful(true)
    .hpChangePerTurn(-1)
    .tickHandler((entity, amplifier, turnsRemaining) -> {
        // Scripted logic runs after the flat hpChangePerTurn is applied.
        if (turnsRemaining <= 1) {
            entity.takeDamage(3 + amplifier);
        }
    })
    .build());

Combat Effect Handlers

Combat effect handlers are lifecycle callbacks that fire at specific moments during a Craftics combat encounter. Unlike flat stat bonuses, they can react to events such as taking damage, killing an enemy, or moving on the grid, and they can intercept and modify combat values. They are the mechanism behind trinket effects, ring abilities, set bonuses from custom equipment, and any other dynamic in-combat behavior an addon needs.

Handlers are registered through StatModifiers.addCombatEffect(name, handler) inside an EquipmentScanner. The scanner runs at the start of each combat encounter and produces fresh handler instances, so instance fields reset naturally between fights.

Registration

There is no CrafticsAPI.registerCombatEffect method. Instead, combat effect handlers live alongside stat bonuses in a StatModifiers object returned by an EquipmentScanner. That scanner is registered once via CrafticsAPI.registerEquipmentScanner.

CrafticsAPI.registerEquipmentScanner("mymod", (player) -> {
    StatModifiers mods = new StatModifiers();

    ItemStack ring = getCustomSlot(player, "ring");
    if (ring.isOf(MY_THORNS_RING)) {
        mods.addCombatEffect("Thorns Ring", new ThornsCombatEffect());
    }

    return mods;
});

Multiple effects per scanner are allowed, each with its own name and handler instance. You can also mix stat bonuses and combat effects in the same StatModifiers.

CombatEffectHandler Interface

CombatEffectHandler is an interface with default no-op implementations for every method. Override only the callbacks your effect needs.

CombatResult

Callbacks that return CombatResult can intercept and modify the value in question. Three factory methods are available:

CombatResult.unchanged(originalValue)       // pass through with no change
CombatResult.modify(newValue, "message")    // change the value, add a combat log message
CombatResult.cancel("message")             // cancel the action entirely (e.g., prevent death)

CombatEffectContext

All callbacks receive a CombatEffectContext as their first argument. The context is created once at combat start and updated each turn.

ctx.getPlayer()         // ServerPlayerEntity, the player
ctx.getArena()          // GridArena, the active arena
ctx.getPlayerEffects()  // CombatEffects, active status effects on the player
ctx.getTrimScan()       // TrimEffects.TrimScan, the player's trim data
ctx.getAllEnemies()     // List<CombatEntity>, all living enemies
ctx.getAllAllies()      // List<CombatEntity>, all living allies

Statefulness

Handlers are per-combat instances. The EquipmentScanner is called at combat start, producing a fresh handler each time. Instance fields therefore reset automatically between fights, and you can safely use them to track per-combat state.

mods.addCombatEffect("One-Shot Shield", new CombatEffectHandler() {
    private boolean used = false; // resets each combat

    @Override
    public CombatResult onLethalDamage(CombatEffectContext ctx, CombatEntity attacker, int damage) {
        if (!used) {
            used = true;
            ctx.getPlayer().heal(10);
            return CombatResult.cancel("§dOne-Shot Shield absorbs the blow!");
        }
        return CombatResult.unchanged(damage);
    }
});

Code Examples

Thorns Ring (reflect incoming damage)

mods.addCombatEffect("Thorns Ring", new CombatEffectHandler() {
    @Override
    public CombatResult onTakeDamage(CombatEffectContext ctx, CombatEntity attacker, int damage) {
        if (attacker != null) {
            attacker.takeDamage(Math.max(1, damage / 4));
        }
        return CombatResult.modify(damage, "§6Thorns Ring reflects damage!");
    }
});

Fortune Amulet (bonus emeralds)

mods.addCombatEffect("Fortune Amulet", new CombatEffectHandler() {
    @Override
    public CombatResult onEmeraldGain(CombatEffectContext ctx, int amount) {
        return CombatResult.modify(amount + 2, "§6Fortune Amulet: +2 bonus emeralds!");
    }
});

Death Prevention (once per combat)

mods.addCombatEffect("Lucky Charm", new CombatEffectHandler() {
    private boolean used = false;

    @Override
    public CombatResult onLethalDamage(CombatEffectContext ctx, CombatEntity attacker, int damage) {
        if (!used) {
            used = true;
            ctx.getPlayer().heal(10);
            return CombatResult.cancel("§d Lucky Charm saves you from death!");
        }
        return CombatResult.unchanged(damage);
    }
});