Content Builder

EriItem is the entry point for creating any item. Start with the static factory method EriItem.create(modid, name) and chain the methods you need. The name becomes the item's registry name (e.g. mymod:ruby) and is also used as the translation key and model filename.

EriItem.create("modid", "ruby")
    .maxStackSize(16)
    .rarity(EnumRarity.RARE)
    .glowing(true)
    .tooltip("&7A precious gem")
    .tooltip("&cVery rare")
    .onRightClick(ctx -> ctx.getPlayer().heal(2f))
    .creativeTab(CreativeTabs.MATERIALS)
    .register();

Methods

• EriItem.create(String modid, String name)

  Static factory. Creates a new item builder. modid is your mod's ID; name is the registry name (lowercase, underscores). Must be called first.
  STATIC
• maxStackSize(int size)

  Sets the maximum number of items that can stack in one inventory slot. Default: 64.
  FLUENT
• maxDamage(int damage)

  Sets the maximum durability of the item. Items with durability automatically show the durability bar. Setting this implicitly sets maxStackSize to 1.
  FLUENT
• rarity(EnumRarity rarity)

  Sets the item rarity, which controls the color of its name in tooltips. Values: COMMON (white), UNCOMMON (yellow), RARE (aqua), EPIC (light purple).
  FLUENT
• creativeTab(CreativeTabs tab)

  Places the item in a creative mode tab. Use any of Minecraft's built-in tabs (CreativeTabs.MATERIALS, CreativeTabs.TOOLS, etc.) or pass a custom tab instance.
  FLUENT
• glowing(boolean glow)

  When true, applies the enchantment glint visual effect to the item regardless of whether it is actually enchanted.
  FLUENT
• tooltip(String line)

  Adds a line to the item tooltip shown when hovering in an inventory. Supports Minecraft color codes with & (e.g. &7gray text). Call multiple times for multiple lines.
  FLUENT
• onRightClick(Consumer<ItemActionContext> action)

  Registers a callback fired when the player right-clicks while holding this item. Receives an ItemActionContext with the player, world, hand, and position.
  EVENT
• onLeftClick(Consumer<ItemActionContext> action)

  Registers a callback fired when the player left-clicks (attacks) while holding this item. Receives an ItemActionContext.
  EVENT
• food()

  Opens a FoodBuilder sub-builder for configuring food properties. Call .done() on the sub-builder to return here.
  SUB-BUILDER
• tool()

  Opens a ToolBuilder sub-builder for configuring tool properties. Call .done() to return.
  SUB-BUILDER
• armor()

  Opens an ArmorBuilder sub-builder for configuring armor properties. Call .done() to return.
  SUB-BUILDER
• animatedModel(String modelId)

  Configures the item to use an animated 3D Blockbench model when held or in inventory. Rendering is delegated to an internal TileEntityItemStackRenderer. modelId uses the format "modid:item/name" (e.g. "eriniumfaction:item/faction_sword"). The Blockbench JSON file must be at assets/{modid}/models/item/{name}.json.
  FLUENT
• register()

  Finalizes the item and submits it to EriAPI's ContentRegistry for Forge registration. Must be the last call in every chain.
  TERMINAL

public static EriItem RUBY = EriItem.create("mymod", "ruby")
    .maxStackSize(16)
    .register();

FoodBuilder is a sub-builder accessed via EriItem.create(...).food(). It lets you define all food properties inline. When you are done, call .done() to return to the parent EriItem builder and continue chaining.

EriItem.create("modid", "golden_apple_custom")
    .food()
        .hunger(6)
        .saturation(1.2f)
        .alwaysEdible(true)
        .effect(new PotionEffect(MobEffects.REGENERATION, 100, 1), 1.0f)
        .done()
    .register();

Methods

• hunger(int amount)

  How many hunger points are restored when eaten. Each full shank icon = 2 points; a full hunger bar = 20 points.
  FLUENT
• saturation(float modifier)

  The saturation modifier added on top of the hunger points. Higher values mean the player stays fed longer. Bread is ~0.6, golden apple is ~1.2.
  FLUENT
• alwaysEdible(boolean value)

  When true, the item can be eaten even when the player's hunger bar is full (like golden apples). Default: false.
  FLUENT
• effect(PotionEffect effect, float probability)

  Applies a potion effect when the food is eaten. probability is a float from 0.0 (never) to 1.0 (always). Call multiple times for multiple effects.
  FLUENT
• done()

  Closes the FoodBuilder and returns the parent EriItem builder so you can continue chaining.
  RETURN

ToolBuilder is accessed via EriItem.create(...).tool(). It configures the item as a sword, pickaxe, axe, shovel, or hoe by setting the tool type, attack damage, durability, and attack speed. Call .done() when finished.

EriItem.create("modid", "ruby_sword")
    .tool()
        .type(ToolType.SWORD)
        .damage(8f)
        .durability(1500)
        .speed(1.6f)
        .done()
    .register();

ToolType enum values

Methods

• type(ToolType type)

  Determines which kind of tool behavior is applied. See table above.
  FLUENT
• damage(float attackDamage)

  The amount of attack damage dealt. A stone sword deals 5.0; a diamond sword deals 7.0.
  FLUENT
• durability(int uses)

  How many uses before the item breaks. A diamond sword has 1561 uses; an iron sword has 251.
  FLUENT
• speed(float attackSpeed)

  The attack speed modifier. Higher values mean faster attack cooldown recovery. A sword is ~1.6; an axe is ~0.9.
  FLUENT
• done()

  Closes the ToolBuilder and returns the parent EriItem builder.
  RETURN

ArmorBuilder is accessed via EriItem.create(...).armor(). It configures which armor slot the item occupies, how much protection it provides, and which material name to use for the armor texture. Call .done() when finished.

EriItem.create("modid", "ruby_chestplate")
    .armor()
        .slot(ArmorSlot.CHEST)
        .protection(8)
        .toughness(2.0f)
        .materialName("ruby")
        .done()
    .register();

ArmorSlot enum values

Methods

• slot(ArmorSlot slot)

  Which armor slot this item equips into. See table above.
  FLUENT
• protection(int points)

  Number of armor points granted. Each full shield icon in the HUD = 2 points; maximum total from all four pieces is 20.
  FLUENT
• toughness(float value)

  Armor toughness reduces the damage-scaling penalty from strong hits. Diamond armor has 2.0 per piece; most other materials have 0.0.
  FLUENT
• materialName(String name)

  The base name used to look up the armor layer textures. For "ruby", Minecraft will look for textures/models/armor/ruby_layer_1.png and ruby_layer_2.png.
  FLUENT
• done()

  Closes the ArmorBuilder and returns the parent EriItem builder.
  RETURN

EriBlock is the entry point for creating any block. Works exactly like EriItem — start with the static factory, chain the properties you need, and end with .register().

The name parameter becomes the block's registry name (e.g. mymod:ruby_ore) and is also used for the block state JSON and model filename lookups.

EriBlock.create("modid", "ruby_ore")
    .material(Material.ROCK)
    .hardness(3.0f)
    .resistance(15.0f)
    .harvestTool("pickaxe", 2)
    .soundType(SoundType.STONE)
    .drops(Items.DIAMOND, 1, 3)
    .creativeTab(CreativeTabs.BUILDING_BLOCKS)
    .onBreak(ctx -> System.out.println("Broken!"))
    .register();

Methods

• EriBlock.create(String modid, String name)

  Static factory. Creates a new block builder. Must be called first.
  STATIC
• material(Material material)

  Sets the block's material, which determines default properties like flammability, piston behavior, and map color. Common values: Material.ROCK, Material.WOOD, Material.IRON, Material.GROUND.
  FLUENT
• hardness(float value)

  How long it takes to mine the block without the correct tool. Dirt is 0.5, stone is 1.5, obsidian is 50.0. Use -1.0f for unbreakable.
  FLUENT
• resistance(float value)

  Explosion resistance. Stone is 10.0, obsidian is 6000.0. Generally set this higher than hardness.
  FLUENT
• harvestTool(String toolClass, int level)

  Specifies which tool is required to harvest drops, and at which harvest level. Tool class values: "pickaxe", "axe", "shovel". Levels: 0=wood, 1=stone, 2=iron, 3=diamond.
  FLUENT
• soundType(SoundType soundType)

  The set of sounds played when walking on, placing, or breaking the block. Common values: SoundType.STONE, SoundType.WOOD, SoundType.SAND, SoundType.METAL, SoundType.GLASS.
  FLUENT
• drops(Item item, int min, int max)

  Sets what the block drops when broken. min and max define the random drop count range. For a block that drops itself, omit this method.
  FLUENT
• creativeTab(CreativeTabs tab)

  Places the block's item form in a creative mode tab.
  FLUENT
• onBreak(Consumer<BlockActionContext> action)

  Registers a callback fired when a player breaks this block. Receives a BlockActionContext with the world, position, and player.
  EVENT
• onPlace(Consumer<BlockActionContext> action)

  Registers a callback fired when a player places this block. The callback is triggered in onBlockPlacedBy, which guarantees that ctx.getPlayer() always returns the player who placed the block (never null).
  EVENT
• onWalk(Consumer<BlockActionContext> action)

  Registers a callback fired every tick an entity walks on top of this block.
  EVENT
• hitbox(AxisAlignedBB box)

  Sets a single custom hitbox (selection + collision). Replaces the default full-block hitbox. Automatically sets isFullCube and isOpaque to false. Coordinates are in blocks: 1.0 = 1 block = 16 pixels. Example: new AxisAlignedBB(0, 0, 0, 1, 0.5, 1) = half-block height.
  FLUENT
• hitboxes(AxisAlignedBB... boxes)

  Defines multiple independent collision boxes. Each box is tested separately for entity collision. The selection outline (hover highlight) shows the union of all boxes. Automatically sets isFullCube and isOpaque to false. Recommended: keep under 6-8 boxes to avoid TPS impact on busy servers.
  FLUENT
• renderLayer(BlockRenderLayer layer)

  Sets the client render layer for the block. Used for translucent, alpha-tested, or transparent blocks. Common values:

  • SOLID (default) — opaque full block
  • CUTOUT — binary alpha (plants, grates)
  • CUTOUT_MIPPED — binary alpha with mipmaps (leaves)
  • TRANSLUCENT — continuous alpha transparency (stained glass, ice)
  FLUENT
• onEntityWalk(TriConsumer<World, BlockPos, Entity> action)

  Callback invoked every tick an entity walks on top of the block (equivalent to Forge's onEntityWalk). Unlike onWalk(Consumer<BlockActionContext>), this variant gives direct access to the world, position, and entity - useful for movement effects or zone damage.
  FLUENT
• onEntityCollision(TriConsumer<World, BlockPos, Entity> action)

  Callback invoked every tick an entity passes through the block (entity inside the hitbox). Equivalent to Forge's onEntityCollision. Useful for plants that damage on contact, slowdown blocks, or trigger traps.
  FLUENT
• logLike()

  Turns the block into a tree log (BlockRotatedPillar) with the AXIS property (X, Y, Z). The block orients itself based on the face it is placed on (upright, lying north/south, lying east/west). The blockstate JSON must handle the three variants axis=x, axis=y, axis=z.
  FLUENT
• leavesLike(Block sapling)

  Turns the block into tree leaves (BlockLeaves) with the vanilla CHECK_DECAY and DECAYABLE properties. Leaves automatically decay when disconnected from a log. Forces the CUTOUT_MIPPED render layer. The sapling argument is dropped with 5% probability during natural decay (may be null to disable).
  Overload: leavesLike() is equivalent to leavesLike(null).
  FLUENT
• plantLike()

  Turns the block into a decorative plant:

  • Reduced hitbox (0.15, 0, 0.15 to 0.85, 0.9, 0.85)
  • No collision (entities pass through)
  • Automatic CUTOUT render layer
  • isOpaque=false, isFullCube=false

  The blockstate JSON should use the block/cross model for the X-shaped display (like vanilla flowers).
  FLUENT
• register()

  Finalizes the block and submits it to ContentRegistry for Forge registration. Must be the last call.
  TERMINAL

import net.minecraft.util.math.AxisAlignedBB;

// Single hitbox — half-block height (1.0 = 1 block = 16 pixels)
EriBlock.create("mymod", "half_slab")
    .material(Material.ROCK)
    .hardness(2.0f)
    .hitbox(new AxisAlignedBB(0, 0, 0, 1, 0.5, 1))
    .register();

// Multiple hitboxes — base plate + central pillar
EriBlock.create("mymod", "machine")
    .material(Material.IRON)
    .hardness(4.0f)
    .hitboxes(
        new AxisAlignedBB(0,    0,    0,    1,    0.25, 1),    // flat base
        new AxisAlignedBB(0.25, 0.25, 0.25, 0.75, 1,    0.75) // central pillar
    )
    .register();

Fluent builder for creating a 3D animated block with model and animations.

• EriAnimBlock create(String modid, String name)

  Creates a new animated block builder.
  STATIC
• EriAnimBlock material(Material mat)

  Block material (Material.IRON, Material.WOOD, etc.).
  FLUENT
• EriAnimBlock hardness(float hardness)

  Mining time.
  FLUENT
• EriAnimBlock resistance(float resistance)

  Explosion resistance.
  FLUENT
• EriAnimBlock animation(String animFileId)

  Required. ID of the .erianim.json file in the format "modid:path/name" (without the extension). Resolves to assets/modid/animations/path/name.erianim.json.
  FLUENT
• EriAnimBlock tileEntity(Class<?> teClass)

  Custom TileEntity (optional). Must extend AnimatedBlockTileEntity and provide a public no-arg constructor. If omitted, EriAPI uses AnimatedBlockTileEntityGeneric (enough for 90% of cases).
  
  Use this option when you need custom logic: react to an animation event at a precise frame, conditionally chain animations, save a block-specific NBT state, sync data to the client, etc.
  FLUENT
• EriAnimBlock onRightClick(Consumer<BlockActionContext> handler)

  Callback fired when the player right-clicks the block.
  EVENT
• Block register()

  Finalizes and registers the block + the associated TileEntity + TESR. Returns the Block instance.
  TERMINAL

Base class to extend for custom behavior. The 3 methods below are designed to be overridden.

Overridable methods (protected)

• void onAnimationEvent(AnimationEvent event)

  Called for every event triggered by the animation (keyframes of type effect, sound, particle, custom). Useful to spawn a sound / particle at a precise frame.
  OVERRIDE
• void onAnimationComplete(String animName)

  Called when an animation finishes (reaches the last keyframe in ONCE / HOLD / HIDE, or after one full loop for LOOP_N). Ideal for chaining animations.
  OVERRIDE
• void onAnimationCallback(String callbackName)

  Called specifically for callback keyframes with the callback name (defined in the animation JSON). Lets you name precise points of the animation (e.g. "chest_opened") and react to them in Java.
  OVERRIDE

Public utilities (call these)

• void playAnimation(String animName)

  Plays the named animation with the EndBehavior defined in the JSON (default).
  PUBLIC
• void playAnimation(String animName, EndBehavior endBehaviorOverride)

  Plays the animation forcing a custom EndBehavior (ONCE, LOOP, HOLD, HIDE, LOOP_N).
  PUBLIC
• void pauseAnimation()

  Pauses the animation at the current frame (synced client+server).
  PUBLIC
• void resumeAnimation()

  Resumes a paused animation.
  PUBLIC
• void resetAnimation()

  Returns to the initial pose (smooth interpolation).
  PUBLIC
• void resetAnimation(boolean instant)

  Returns to the initial pose; instant=true skips interpolation (immediate snap).
  PUBLIC
• void stopAnimation()

  Stops the current animation (stays at current frame without returning to base pose).
  PUBLIC
• void setTexture(String target, String value)

  Replaces a model texture at runtime. target is the texture key from the Blockbench JSON, value is the new texture path (e.g. "mymod:blocks/core_active"). Synced to client.
  PUBLIC
• void clearTexture(String target)

  Removes the texture override for target (back to the original texture).
  PUBLIC
• void clearAllTextures()

  Clears all texture overrides at once.
  PUBLIC
• boolean isAnimating()

  Returns true if an animation is currently playing.
  PUBLIC
• String getCurrentAnimation()

  Name of the current animation, or null if none is active.
  PUBLIC
• float getAnimationProgress()

  Progress of the current animation, from 0.0 to 1.0.
  PUBLIC
• void setBlockYRotation(float rotation)

  Block rotation around the Y axis (degrees). Synced to client.
  PUBLIC

EriRecipe provides fluent builders for the three main recipe types in Minecraft 1.12.2: shaped crafting, shapeless crafting, and smelting. Each type has its own static factory method.

A shaped recipe requires ingredients to be placed in a specific grid pattern. Define the pattern with up to three strings of up to three characters each, then map each character to an ingredient.

EriRecipe.shaped("modid", "ruby_block")
    .pattern("RRR", "RRR", "RRR")
    .key('R', myRubyItem)
    .result(myRubyBlock, 1)
    .register();

Methods

• EriRecipe.shaped(String modid, String name)

  Static factory. Creates a shaped recipe builder. name is the recipe's registry name.
  STATIC
• pattern(String... rows)

  Defines the crafting grid pattern. Pass 1–3 strings of 1–3 characters each. Use a space character for empty slots. Each non-space character must be mapped with .key().
  FLUENT
• key(char symbol, Item item)

  Maps a character used in the pattern to an ingredient item. Call once per unique character. Also accepts Block or EriItem / EriBlock references.
  FLUENT
• result(Item item, int count)

  The item produced by this recipe and how many copies. Also accepts Block, EriItem, or EriBlock references.
  FLUENT
• register()

  Submits the recipe to Forge's recipe registry. Must be the last call.
  TERMINAL

A shapeless recipe can be crafted by placing the ingredients anywhere in the grid — order and position do not matter.

EriRecipe.shapeless("modid", "ruby_from_block")
    .ingredient(myRubyBlock)
    .result(myRubyItem, 9)
    .register();

Methods

• EriRecipe.shapeless(String modid, String name)

  Static factory. Creates a shapeless recipe builder.
  STATIC
• ingredient(Item item)

  Adds a required ingredient. Call multiple times to add more. Also accepts Block, EriItem, or EriBlock.
  FLUENT
• result(Item item, int count)

  The item produced and how many copies.
  FLUENT
• register()

  Submits the recipe to Forge's recipe registry.
  TERMINAL

A smelting recipe defines what a furnace produces when a given input item is cooked.

EriRecipe.smelting("modid", "ruby_smelt")
    .input(myRubyOre)
    .result(myRubyItem)
    .xp(1.0f)
    .register();

Methods

• EriRecipe.smelting(String modid, String name)

  Static factory. Creates a smelting recipe builder.
  STATIC
• input(Item item)

  The item that goes into the furnace input slot. Also accepts Block, EriItem, or EriBlock.
  FLUENT
• result(Item item)

  The item produced by smelting. Always produces exactly one copy.
  FLUENT
• xp(float amount)

  How much XP the player earns each time they smelt this recipe. Ores typically give 0.7–1.0; food gives 0.1–0.35.
  FLUENT
• register()

  Submits the smelting recipe to Forge.
  TERMINAL

ContentRegistry is the internal engine that connects EriAPI builders to the Forge event system. You do not need to interact with it directly — it is fully automatic.

What it does

When you call .register() on any builder, EriAPI adds the entry to an internal queue managed by ContentRegistry. The registry listens for Forge's RegistryEvent.Register<Item> and RegistryEvent.Register<Block> events and automatically flushes the queue at the correct moment during the mod loading lifecycle.

Model resolution

By default, EriAPI looks for item models at assets/<modid>/models/item/<name>.json and block states at assets/<modid>/blockstates/<name>.json. Place your JSON files there and EriAPI will pick them up automatically — no manual ModelLoader.setCustomModelResourceLocation() calls required.

When you register a callback with .onRightClick(), .onLeftClick(), or .onBreak(), your lambda receives a context object that gives you access to everything relevant to the interaction. You never need to construct these objects yourself — EriAPI creates and passes them automatically.

ItemActionContext

Passed to .onRightClick() and .onLeftClick() callbacks on EriItem.

BlockActionContext

Passed to .onBreak(), .onPlace(), and .onWalk() callbacks on EriBlock.

EriItem.create("mymod", "teleport_staff")
    .onRightClick(ctx -> {
        // Guard: only run on the server
        if (ctx.isRemote()) return;

        EntityPlayer player = ctx.getPlayer();
        BlockPos target = ctx.getHitPosition();

        if (target != null) {
            // Teleport the player to the clicked block
            player.setPositionAndUpdate(
                target.getX() + 0.5,
                target.getY() + 1.0,
                target.getZ() + 0.5
            );
        }
    })
    .register();

EriBlock.create("mymod", "alarm_block")
    .material(Material.ROCK)
    .hardness(1.5f)
    .onBreak(ctx -> {
        if (ctx.isRemote()) return;

        World world = ctx.getWorld();
        BlockPos pos = ctx.getPos();
        EntityPlayer player = ctx.getPlayer();

        // Broadcast a chat message to all players
        world.getMinecraftServer().getPlayerList()
            .sendMessage(new TextComponentString(
                (player != null ? player.getName() : "Someone")
                + " broke the alarm block at " + pos
            ));
    })
    .register();

Base class to extend for a custom entity. Mirrors the logic of GeneratedEntity but allows subclassing.

Extension contract

• Extend EriEntityBase
• Provide a public constructor: public MyEntity(World world) { super(world); }
• If you use @SyncParam, call EntityDataSync.register(this) in entityInit() after super.entityInit()
• You can override any method; call super to keep EriEntity behaviours (sounds, drops, callbacks...)

Accessible protected fields

• EntityDefinition eriDef

  The definition driving this entity. May be null if misconfigured.
  PROTECTED
• String eriDefId

  Canonical id (modId:registryName) used for NBT restoration.
  PROTECTED

Public accessors

• EntityDefinition getEriDef()

  Returns the EntityDefinition driving this entity.
  PUBLIC
• String getEriDefId()

  Returns the canonical id (modId:registryName).
  PUBLIC

• EriEntity entityClass(Class<? extends EriEntityBase> clazz)

  Specifies a custom Java class. When this method is called, EriAPI registers your class directly in Forge instead of using a pre-compiled slot. The class must extend EriEntityBase and have a public MyEntity(World world) constructor.
  FLUENT

Base class to extend for a custom projectile.

Extension contract

• Extend EriProjectileBase
• Required constructor: public MyProjectile(World world) { super(world); }
• Optional constructor: public MyProjectile(World world, EntityLivingBase thrower)
• Call super in overrides to keep piercing, bouncing, AOE, etc.

Accessible protected fields

• ProjectileDefinition eriDef

  The definition driving this projectile.
  PROTECTED
• String eriDefId

  Canonical id (modId:registryName) used for NBT logging.
  PROTECTED
• int pierceCount

  Number of entities this projectile has already pierced.
  PROTECTED
• int bounceCount

  Number of blocks this projectile has already bounced off.
  PROTECTED
• int ticksAlive

  Number of ticks since the projectile was spawned.
  PROTECTED

• EriProjectile projectileClass(Class<? extends EriProjectileBase> clazz)

  Specifies a custom Java class. When this method is called, EriAPI registers your class directly in Forge instead of using a pre-compiled slot from GeneratedProjectileSlots.
  FLUENT

Base class to extend for a custom item.

Extension contract

• Extend EriItemBase
• Required constructor: public MyItem() { super(); } (no arguments)
• You can override onItemRightClick, onItemUse, onUpdate, etc.
• Call super in overrides to keep the builder's .onRightClick() callback

Accessible protected fields

• ItemDefinition eriDef

  The definition driving this item. Contains tooltip, rarity, glow, etc.
  PROTECTED

• EriItem itemClass(Class<? extends EriItemBase> clazz)

  Specifies a custom Java class. When this method is called, EriAPI registers your class directly in Forge instead of GeneratedItem.
  FLUENT