Focus Items

Focus items are wand attachments that determine what spell or effect a wand casts. They can be upgraded with various upgrades that modify their behavior.

ItemFocusBasic

thaumcraft.api.wands.ItemFocusBasic

Base class for all focus items. Extend this class to create a custom focus.

Key Methods

Method	Description
`getVisCost(ItemStack)`	Returns the AspectList cost per activation. Return `null` for free foci.
`isVisCostPerTick(ItemStack)`	If `true`, cost is consumed continuously while held, not per activation.
`getActivationCooldown(ItemStack)`	Milliseconds between activations. Default 0 (no cooldown).
`getMaxAreaSize(ItemStack)`	For architect-mode foci (e.g. Equal Trade). Max block radius. Default 1.
`getFocusColor(ItemStack)`	RGB color of the focus orb rendered on the wand. Default 0 (no color).
`getOrnament(ItemStack)`	IIcon for ornamentation rendered as a cross around the focus. Return `null` for none.
`getFocusDepthLayerIcon(ItemStack)`	IIcon rendered inside the focus itself. Return `null` for none.
`getAnimation(ItemStack)`	`WandFocusAnimation.WAVE` or `CHARGE`. Default WAVE.
`onFocusRightClick(ItemStack, World, EntityPlayer, MovingObjectPosition)`	Called when player right-clicks with the wand/focus. Return the focus ItemStack.
`onUsingFocusTick(ItemStack, EntityPlayer, int)`	Called every tick while player is holding right-click with the wand.
`onPlayerStoppedUsingFocus(ItemStack, World, EntityPlayer, int)`	Called when player releases right-click.
`onFocusBlockStartBreak(ItemStack, int x, int y, int z, EntityPlayer)`	Return `true` to prevent the block from being broken.
`getSortingHelper(ItemStack)`	Two-character string prefix used for sorting focus items in the inventory.

Upgrade System

Foci support up to 5 upgrade slots. Each slot can hold one FocusUpgradeType.

Method	Description
`getPossibleUpgradesByRank(ItemStack, int rank)`	Returns upgrades available for a specific slot rank (1–5). Return `null` for all available.
`canApplyUpgrade(ItemStack, EntityPlayer, FocusUpgradeType, int rank)`	Custom logic for upgrade eligibility (e.g. research requirements). Default always `true`.
`applyUpgrade(ItemStack, FocusUpgradeType, int rank)`	Apply an upgrade to a specific slot. Returns `false` if slot is occupied or rank invalid.
`getAppliedUpgrades(ItemStack)`	Returns array of 5 short IDs (or -1 for empty).
`isUpgradedWith(ItemStack, FocusUpgradeType)`	Whether the focus has the given upgrade type.
`getUpgradeLevel(ItemStack, FocusUpgradeType)`	Number of times the upgrade type is applied (for stackable upgrades).

FocusUpgradeType

thaumcraft.api.wands.FocusUpgradeType

Represents a single upgrade type that can be applied to a focus. Registered in a static array indexed by ID.

Fields

Field	Type	Description
`id`	`short`	Unique upgrade identifier (0–19 for vanilla).
`icon`	`ResourceLocation`	Icon displayed in the upgrade tooltip.
`name`	`String`	Localization key for the upgrade name.
`text`	`String`	Localization key for the upgrade description.
`aspects`	`AspectList`	Aspects used to calculate vis cost of the upgrade (amounts ignored, types matter).

Constructor

new FocusUpgradeType(int id, ResourceLocation icon, String name, String text, AspectList aspects)

Built-in Upgrades

ID	Name	Localization Key	Cost Aspects
0	Potency	`focus.upgrade.potency.name`	WEAPON
1	Frugal	`focus.upgrade.frugal.name`	HUNGER
2	Treasure	`focus.upgrade.treasure.name`	GREED
3	Enlarge	`focus.upgrade.enlarge.name`	TRAVEL
4	Alchemist’s Fire	`focus.upgrade.alchemistsfire.name`	ENERGY, SLIME
5	Alchemist’s Frost	`focus.upgrade.alchemistsfrost.name`	COLD, TRAP
6	Architect	`focus.upgrade.architect.name`	CRAFT
7	Extend	`focus.upgrade.extend.name`	EXCHANGE
8	Silk Touch	`focus.upgrade.silktouch.name`	GREED

Upgrade Effects

Potency: Increases spell damage or effectiveness.
Frugal: Reduces vis cost per activation.
Treasure: Increases loot quality/rarity from foci that produce items.
Enlarge: Increases spell area of effect radius.
Alchemist’s Fire: Adds fire damage to applicable spells.
Alchemist’s Frost: Adds cold/slow effect to applicable spells.
Architect: Increases the area size for architect-mode foci.
Extend: Extends spell duration on applicable effects.
Silk Touch: Causes applicable spells to preserve block contents (e.g. silk-touch mining).

WandFocusAnimation

public enum WandFocusAnimation {
    WAVE, CHARGE;
}

Animation played when the focus is activated:

WAVE: Swings outward (default).
CHARGE: Charges up in place.

Registration

To register a focus item, create an instance in your mod’s initialization code:

// Example focus registration (in your mod's init)
ItemFocusBasic myFocus = new ItemFocusBasic() {
    @Override
    public AspectList getVisCost(ItemStack focusstack) {
        return new AspectList().add(Aspect.FIRE, 10);
    }
    
    @Override
    public int getFocusColor(ItemStack focusstack) {
        return 0xFF4400; // Orange
    }
};