API Reference

Full per-system reference for the Neo Vitae addon API on NeoForge 1.21.1. For setup, packaging notes, and quick examples see API Overview. For the player-facing side of these systems see Rituals, Sigils, and Sentient Armor.

The main entry point is NeoVitaeAPI.getInstance(), which returns an INeoVitaeAPI once Neo Vitae has finished common setup. Its top-level surface is:

Method	Return Type	Description
`getAnima(UUID uuid)`	`@Nullable IAnima`	Anima for a player by UUID
`getSentientArmorManager()`	`ISentientArmorManager`	Sentient Armor manager
`getRuneRegistry()`	`IAltarRuneRegistry`	Altar rune registry
`getTranquilityHandler()`	`ITranquilityHandler`	Tranquility lookup
`getSpiritusHandler()`	`ISpiritusHandler`	Chunk-based spiritus handler
`getPlayerWillHandler()`	`IPlayerSpiritusHandler`	Inventory-level spiritus handler
`getApiVersion()`	`String`	API version string

INeoVitaeAPI api = NeoVitaeAPI.getInstance();

IAnima anima = api.getAnima(player.getUUID());
if (anima != null) {
    int currentEV = anima.getCurrentEV();
}

ISentientArmorManager armor = api.getSentientArmorManager();
if (armor.hasFullSet(player)) {
    List<ISentientArmorManager.UpgradeInfo> upgrades = armor.getUpgrades(player);
}

Anima System

The Anima stores Essentia Vitae (EV) that powers Neo Vitae items, sigils, and rituals. Each player has their own Anima, keyed by their UUID.

IAnima

Package com.breakinblocks.neovitae.api.soul

Method	Return Type	Description
`getPlayerId()`	`UUID`	Owner UUID
`getCurrentEV()`	`int`	Current stored EV
`add(AnimaTicket ticket, int maximum)`	`int`	Adds EV up to `maximum`; returns amount added
`set(AnimaTicket ticket, int maximum)`	`int`	Sets EV to the ticket amount (clamped); returns value set
`syphon(AnimaTicket ticket)`	`int`	Drains EV; returns amount drained
`hurtPlayer(Player user, float syphon)`	`void`	Damages the player to compensate for an EV shortfall
`syphonAndDamage(Player user, AnimaTicket ticket)`	`SyphonResult`	Drains EV and damages the player if insufficient

IAnima anima = NeoVitaeAPI.getInstance().getAnima(player.getUUID());
if (anima == null) return;

SyphonResult result = anima.syphonAndDamage(player, AnimaTicket.create(100));
if (result.success()) {
    performSigilEffect();
}

int added = anima.add(AnimaTicket.create(500), 10000);

AnimaTicket

Package com.breakinblocks.neovitae.api.soul

Tracks the EV amount for a transaction. The type is retained for future logging hooks.

Method	Return Type	Description
`create(int amount)` (static)	`AnimaTicket`	Creates a ticket
`getAmount()`	`int`	Returns the EV amount

SyphonResult

Package com.breakinblocks.neovitae.api.soul

public record SyphonResult(boolean success, int amount) {
    public static SyphonResult of(boolean success, int amount);
    public static SyphonResult failure();
}

Spiritus System

Spiritus is a per-chunk aura with five aspects. The aspect enum SpiritusType is at com.breakinblocks.neovitae.common.datacomponent.SpiritusType.

`SpiritusType`	Display name
`RAW`	Raw
`RUINA`	Spiritus Ruina
`NIHILUM`	Spiritus Nihilum
`VINDICTA`	Spiritus Vindicta
`INVICTUS`	Spiritus Invictus

ISpiritusHandler

Package com.breakinblocks.neovitae.api.spiritus

All mutating methods are server-side only and no-op on the client.

Method	Return Type	Description
`getCurrentWill(Level, BlockPos, SpiritusType)`	`double`	Current aspect amount
`getTotalSpiritus(Level, BlockPos)`	`double`	Sum across aspects
`getMaxSpiritus(Level, BlockPos, SpiritusType)`	`double`	Effective maximum
`getBaseMaxSpiritus(SpiritusType)`	`double`	Base maximum from config
`getMaxBonus(Level, BlockPos, SpiritusType)`	`double`	Per-chunk bonus capacity
`setMaxBonus(Level, BlockPos, SpiritusType, double)`	`void`	Sets per-chunk bonus
`addMaxBonus(Level, BlockPos, SpiritusType, double)`	`double`	Adjusts per-chunk bonus; returns new value
`addSpiritus(Level, BlockPos, SpiritusType, double)`	`double`	Adds aspect to the chunk
`drainSpiritus(Level, BlockPos, SpiritusType, double)`	`double`	Drains aspect from the chunk
`fillWillToAmount(Level, BlockPos, SpiritusType, double)`	`double`	Fills aspect up to a target
`getDominantWillType(Level, BlockPos)`	`SpiritusType`	Aspect with the highest amount
`hasSpiritus(Level, BlockPos)`	`boolean`	Whether the chunk has any aspect
`getFillRatio(Level, BlockPos, SpiritusType)`	`double`	`current / max`
`queryWill(Level, BlockPos, double threshold)`	`SpiritusState`	Snapshot with batched usage tracking
`transferWill(Level, ChunkPos, ChunkPos, SpiritusType, double)`	`double`	Moves aspect between chunks

SpiritusHandler

Package com.breakinblocks.neovitae.api.spiritus

Default implementation; available as SpiritusHandler.INSTANCE. Addons should use the API accessor.

SpiritusState

Package com.breakinblocks.neovitae.api.spiritus

Per-aspect snapshot with batch draining; produced by ISpiritusHandler.queryWill.

Method	Return Type	Description
`get(SpiritusType)`	`double`	Snapshot amount
`has(SpiritusType)`	`boolean`	At or above threshold
`getRaw()` / `getRuina()` / `getNihilum()` / `getInvictus()` / `getVindicta()`	`double`	Per-aspect amount accessors; convenience over `get(SpiritusType.X)`.
`hasRaw()` / `hasRuina()` / `hasNihilum()` / `hasInvictus()` / `hasVindicta()`	`boolean`	Per-aspect threshold checks; convenience over `has(SpiritusType.X)`.
`use(SpiritusType, double)`	`void`	Records pending usage
`drain(ISpiritusHandler, Level, BlockPos)`	`void`	Applies all pending usage
`drain(Level, BlockPos)`	`void`	Same as above using `SpiritusHandler.INSTANCE`

ISpiritusHandler spiritus = NeoVitaeAPI.getInstance().getSpiritusHandler();
SpiritusState state = spiritus.querySpiritus(level, pos, 0.5);
if (state.hasDefault()) {
    state.use(SpiritusType.RAW, 0.1);
}
state.drain(level, pos);

IPlayerSpiritusHandler

Package com.breakinblocks.neovitae.api.spiritus

Inventory-level handler for spiritus items and spiritus gems.

Method	Return Type	Description
`getTotalSpiritus(SpiritusType, Player)`	`double`	Sum across inventory
`getLargestSpiritusType(Player)`	`SpiritusType`	Aspect with the highest total
`isSpiritusFull(SpiritusType, Player)`	`boolean`	Every gem of that aspect is full
`consumeSpiritus(SpiritusType, Player, double)`	`double`	Drains aspect from gems
`addSpiritus(Player, ItemStack)`	`ItemStack`	Pours a spiritus-item stack into gems; returns leftover
`addSpiritus(SpiritusType, Player, double)`	`double`	Adds aspect to gems
`addSpiritus(SpiritusType, Player, double, ItemStack ignored)`	`double`	Same but skips a stack

Ara Vitae System

The Ara Vitae is Neo Vitae's blood altar.

Accessing the Altar

import com.breakinblocks.neovitae.api.capability.NVCapabilities;
import com.breakinblocks.neovitae.api.altar.IAraVitae;

IAraVitae altar = level.getCapability(NVCapabilities.ARA_VITAE, pos, null);
if (altar != null) {
    int blood = altar.getCurrentBlood();
    int capacity = altar.getCapacity();
    int tier = altar.getTier();
}

IAraVitae

Package com.breakinblocks.neovitae.api.altar

State

Method	Return Type	Description
`getTier()`	`int`	Altar tier (0 = no structure, 1-5 built)
`getCurrentBlood()`	`int`	Current EV in the tank (mB)
`getCapacity()`	`int`	Maximum EV (mB) with rune bonuses

Crafting

Method	Return Type	Description
`getProgressFloat()`	`float`	Progress 0.0 - 1.0
`getCraftingProgress()`	`int`	EV consumed so far
`getLiquidRequired()`	`int`	Total EV for the active recipe
`getTotalCraftingTime()`	`int`	Total craft duration in ticks
`getStackInSlot()`	`ItemStack`	Input item

Rates

Method	Return Type	Description
`getConsumptionRate()`	`int`	EV per tick while crafting
`getDrainRate()`	`int`	EV per tick lost when paused
`getChargingRate()`	`int`	EV per idle charge
`getChargingFrequency()`	`int`	Ticks between idle charges
`getTickRate()`	`int`	Ticks between altar operations

Rune-derived bonuses

Method	Return Type	Description
`getBonusCapacity()`	`float`	Capacity multiplier
`getEfficiency()`	`float`	Drain multiplier
`getSelfSacrificeBonus()`	`float`	Additive self-sacrifice bonus
`getSacrificeBonus()`	`float`	Additive entity-sacrifice bonus
`getSpeedBonus()`	`float`	Additive crafting-speed bonus
`getDislocationBonus()`	`float`	Fluid I/O multiplier
`getOrbCapacityBonus()`	`float`	Additive orb fill-rate bonus

Utility

Method	Return Type	Description
`getFluidHandler()`	`IFluidHandler`	Fluid handler
`checkTier()`	`void`	Forces a structure rescan

AraVitaeRecipe

Package com.breakinblocks.neovitae.api.recipe

Abstract base class for altar recipes (Recipe<AraVitaeInput>).

Static	Value
`RECIPE_TYPE_NAME`	`"ara_vitae_recipe"`

Constructors:

AraVitaeRecipe(Ingredient input, ItemStack result,
               int minTier, int totalBlood, int craftSpeed, int drainSpeed);
AraVitaeRecipe(Ingredient input, ItemStack result,
               int minTier, int totalBlood, int craftSpeed, int drainSpeed,
               boolean copyInputComponents);

Method	Return Type	Description
`getInput()`	`Ingredient`	Input ingredient
`getResult()`	`ItemStack`	Copy of base output
`getMinTier()`	`int`	Minimum altar tier
`getTotalBlood()`	`int`	Total EV required
`getCraftSpeed()`	`int`	EV per tick while crafting
`getDrainSpeed()`	`int`	Progress lost per tick when out of EV
`shouldCopyInputComponents()`	`boolean`	Whether `assemble` copies input components
`matches(AraVitaeInput, Level)`	`boolean`	Ingredient and tier match
`assemble(AraVitaeInput, HolderLookup.Provider)`	`ItemStack`	Output, with optional component copy
`getResultItem(HolderLookup.Provider)`	`ItemStack`	Copy of the base result
`canCraftInDimensions(int, int)`	`boolean`	Always `true`
`getSerializer()`	`RecipeSerializer<?>`	Abstract; supplied by subclasses
`getType()`	`RecipeType<?>`	Abstract; supplied by subclasses

JSON:

{
  "type": "neovitae:ara_vitae_recipe",
  "input": {"item": "minecraft:diamond"},
  "output": {"id": "neovitae:weak_blood_orb"},
  "minTier": 1,
  "bloodNeeded": 2000,
  "craftSpeed": 5,
  "drainSpeed": 1,
  "copyInputComponents": false
}

AraVitaeInput

Package com.breakinblocks.neovitae.api.recipe

public class AraVitaeInput implements RecipeInput {
    public AraVitaeInput(ItemStack inputStack, int altarTier);
    public ItemStack getItem(int index);
    public int getAltarTier();
    public int size();
}

Altar Rune System

Altar runes grant the Ara Vitae stat bonuses. Built-in types are EnumAltarRuneType constants; custom types implement IAltarRuneType and register via IAltarRuneRegistry.

IAltarRuneType

Package com.breakinblocks.neovitae.api.altar.rune

Method	Return Type	Description
`getId()`	`ResourceLocation`	Unique identifier
`getSerializedName()`	`String`	Lowercase identifier for NBT/JSON

EnumAltarRuneType

Package com.breakinblocks.neovitae.api.altar.rune

Value	Behavior
`SPEED`	Increases crafting speed
`EFFICIENCY`	Reduces EV drain when crafting is paused
`SACRIFICE`	Increases entity-sacrifice EV
`SELF_SACRIFICE`	Increases self-sacrifice EV
`DISPLACEMENT`	Multiplies fluid I/O rate
`CAPACITY`	Increases blood capacity
`AUGMENTED_CAPACITY`	Multiplies capacity bonus (compounds)
`ORB`	Increases soul network fill rate
`ACCELERATION`	Reduces tick rate for altar operations
`CHARGING`	Enables and increases stored charge

Static helper: fromSerializedName(String) returns the matching constant or null.

IAltarRuneRegistry

Package com.breakinblocks.neovitae.api.altar.rune

Method	Return Type	Description
`registerRuneType(IAltarRuneType)`	`void`	Registers a custom rune type
`getRuneType(ResourceLocation)`	`@Nullable IAltarRuneType`	Lookup by ID
`getRuneTypeByName(String)`	`@Nullable IAltarRuneType`	Lookup by name
`getAllRuneTypes()`	`Collection<IAltarRuneType>`	All registered types
`isRegistered(ResourceLocation)`	`boolean`	Whether the ID is registered
`registerRuneBlock(Block, IAltarRuneType, int amount)`	`void`	Associates a block with a rune type
`getRunesForBlock(Block)`	`Map<IAltarRuneType, Integer>`	All rune contributions for a block
`hasRunes(Block)`	`boolean`	Whether the block contributes any runes

@SubscribeEvent
public static void onCommonSetup(FMLCommonSetupEvent event) {
    event.enqueueWork(() -> {
        IAltarRuneRegistry registry = NeoVitaeAPI.getInstance().getRuneRegistry();
        registry.registerRuneType(ManaRuneType.INSTANCE);
        registry.registerRuneBlock(ModBlocks.MANA_RUNE.get(), ManaRuneType.INSTANCE, 1);
    });
}

AltarRuneModifiers

Package com.breakinblocks.neovitae.api.altar.rune

Getters: getCapacityMod(), getTickRate(), getConsumptionMod(), getSacrificeMod(), getSelfSacrificeMod(), getDislocationMod(), getOrbCapacityMod(), getChargeAmountMod(), getChargeCapacityMod(), getEfficiencyMod().

Mutators (all return void, none are chainable):

Method	Description
`addCapacityMod(float)` / `multiplyCapacityMod(float)`	Capacity adjustments
`adjustTickRate(int)` / `setTickRate(int)`	Tick rate adjustments (minimum 1)
`addConsumptionMod(float)`	Crafting-speed bonus
`addSacrificeMod(float)` / `addSelfSacrificeMod(float)`	Sacrifice bonuses
`multiplyDislocationMod(float)` / `addDislocationMod(float)`	Dislocation adjustments
`addOrbCapacityMod(float)`	Orb capacity bonus
`addChargeAmountMod(float)` / `addChargeCapacityMod(float)`	Charging adjustments
`multiplyEfficiencyMod(float)`	Efficiency multiplier
`reset()`	Reset to defaults

RuneInstance

Package com.breakinblocks.neovitae.api.altar.rune

public record RuneInstance(BlockPos pos, Block block, @Nullable BlockEntity blockEntity) {
    public boolean hasBlockEntity();
    public boolean isBlockEntityType(Class<? extends BlockEntity> type);
    public <T extends BlockEntity> @Nullable T getBlockEntityAs(Class<T> type);
    public boolean isBlockType(Class<? extends Block> blockClass);
}

Worked example: dynamic mana rune

@SubscribeEvent
public static void onCalculateStats(AltarRuneEvent.CalculateStats event) {
    List<ManaRuneBlockEntity> manaRunes =
        event.getRuneBlockEntities(ManaRuneBlockEntity.class);

    int powered = 0, unpowered = 0;
    for (ManaRuneBlockEntity rune : manaRunes) {
        if (rune.hasMana()) powered++; else unpowered++;
    }

    AltarRuneModifiers mods = event.getModifiers();
    if (powered > 0) {
        mods.addCapacityMod(0.20f * powered);
        mods.multiplyEfficiencyMod(1.0f + 0.15f * powered);
    }
    if (unpowered > 0) {
        mods.addCapacityMod(0.05f * unpowered);
    }
}