Jepia API Documentation

Getting Started

Installation

Jepia is built with Bun. Make sure you have Bun installed (version >=1.0.0).

# Clone the repository
git clone #.git
cd jepia

# Install dependencies
bun install

Create Your First Add-On

Create a new TypeScript file (e.g., my-addon.ts) and import Jepia:

import { Addon, Item } from 'jepia';

const addon = new Addon('MyAddon', 'My first add-on');
const sword = new Item('Dragon Sword', 'myaddon:dragon_sword');
sword.addTexture('textures/items/dragon_sword.png');
addon.addItem(sword);

await addon.generate('./output');

Run the script with Bun:

bun run my-addon.ts

This will generate a complete add‑on structure in the ./output folder, ready to be imported into Minecraft Bedrock Edition.

Core Concepts

Addon

The Addon class is the main entry point. It automatically creates both a behavior pack and a resource pack, and coordinates component registration across them.

Packs

• Behavior Pack – Contains game logic: items, blocks, entities, recipes, loot tables.
• Resource Pack – Contains assets: textures, models, materials, render controllers, animations, sounds.

Both packs are created automatically when you instantiate an Addon.

Components

Components are the building blocks of your add‑on. Each component corresponds to a Minecraft JSON definition (item, block, entity, texture, model, material, render controller, etc.). Jepia provides a fluent, object‑oriented API for creating and configuring components.

All components are validated against official Minecraft JSON schemas using AJV before file generation.

Rendering Pipeline (Phase 3)

For custom entity visuals, Jepia now supports the full rendering pipeline:

1. TextureLayer – A single image with a PBR role (color, normal, MER, overlay, etc.).
2. TextureSet – Groups layers into a PBR texture set (.texture_set.json).
3. Material – Defines shader behavior (.material file with blend factors, defines, states).
4. RenderController – Wires geometry, textures, and materials together at runtime using Molang expressions.
5. Molang – Type-safe helpers for building Molang expression strings.

Automatic Render Controller Generation (Phase 4)

Jepia can automatically generate render controllers based on an entity's texture layers and UV atlas configuration via addon.generateRenderControllerForEntity(). It handles single‑texture, multi‑variant, and UV atlas entities, producing appropriate render controllers and materials.

ResourcePack File System Integration (Phase 4)

The ResourcePack class now provides file management APIs for materials, render controllers, and PBR texture sets. Use addMaterialFile(), addRenderControllerFile(), addTextureSetFile() and writeFiles() to register assets for automatic writing to disk.

Addon API

The Addon class provides the following methods:

ResourcePack API

The ResourcePack class (accessible via addon.getResourcePack()) manages asset files for the resource pack. New file management methods allow registering materials, render controllers, and PBR texture sets for automatic writing.

Component API

Item

import { Item } from 'jepia';

const ruby = new Item('Ruby', 'myaddon:ruby', 'A precious gemstone');
ruby
  .setMaxStackSize(64)
  .setMenuCategory('items')
  .addComponent('minecraft:durability', { max_durability: 100 })
  .addTexture('textures/items/ruby.png');

addon.addItem(ruby);

Key methods: setMaxStackSize, setMenuCategory, addComponent, addTexture, addModel.

Component Reference: See the full list of Item Components available for addComponent() — durability, food, combat, equipment, and more.

Block

Blocks can be added via the add‑on's addBlock method using either a Block component instance or a block identifier string with behavior data. The Block component API is under development; currently the string‑based API is recommended.

addon.addBlock('myaddon:ruby_ore', {
  display_name: 'Ruby Ore',
  material: 'stone',
  hardness: 3,
  blast_resistance: 3,
});

You can also provide optional resource data for the resource pack:

addon.addBlock('myaddon:ruby_ore', behaviorData, resourceData);

Component Reference: See the full list of Block Components available for addComponent() — geometry, destruction, lighting, redstone, and more.

Entity

Entities can be added using either an Entity component instance or a raw JSON definition. The component API provides better integration with the resource pack (client entity generation) and the rendering pipeline.

// Using raw JSON (legacy API)
addon.addEntity('myaddon:ruby_golem', {
  format_version: '1.21.40',
  'minecraft:entity': {
    description: {
      identifier: 'myaddon:ruby_golem',
      is_summonable: true,
      is_spawnable: true,
    },
    components: {
      'minecraft:physics': {},
      'minecraft:movement': { value: 0.25 },
      'minecraft:health': { value: 20, max: 20 },
    },
  },
});

// Using Entity component (recommended)
import { Entity } from 'jepia';
const mob = new Entity('Ruby Golem', 'myaddon:ruby_golem');
mob.addComponent('minecraft:health', { value: 20 });
addon.addEntity(mob);

The Entity component also supports attaching a Material for full pipeline integration:

import { Entity, Material, VanillaMaterials } from 'jepia';

const mob = new Entity('Ruby Golem', 'myaddon:ruby_golem');
const mat = Material.fromVanilla('myaddon:golem_mat', VanillaMaterials.ENTITY_ALPHATEST);
mob.setMaterial(mat);
addon.addEntity(mob);

You can also attach a RenderController to customize how the entity is rendered at runtime (geometry, textures, materials, part visibility, color tinting, UV animation). The controller is automatically written to resource_pack/render_controllers/ when the add‑on is generated.

import { Entity, RenderController, Molang } from 'jepia';

const mob = new Entity('Robot', 'myaddon:robot');
const rc = new RenderController('Robot Controller', 'myaddon:robot')
  .setGeometry('Geometry.default')
  .setMaterials([{ '*': 'Material.default' }])
  .setTextures(['Texture.default']);

mob.setRenderController(rc);
addon.addEntity(mob);

Texture Layer Management

Entities support multiple texture layers for variant skins, overlays, and PBR texture sets. Use addTextureLayer(), removeTextureLayer(), getTextureLayers(), and clearTextureLayers() to manage layers.

UV Atlas Variables

For texture atlasing, set UV atlas variables with setUvAtlasVariables(). This automatically injects Molang pre‑animation scripts into the client entity, enabling uv_anim render controllers.

Script Animation

Control animation playback via setScriptAnimate(), getScriptAnimate(), and clearScriptAnimate(). Entries can be unconditional animation short names or conditional Molang expressions.

Automatic Render Controller Generation

The add‑on's generateRenderControllerForEntity() method automatically creates an appropriate render controller based on the entity's texture layers and UV atlas configuration. See the Addon API table for details.

Component Reference: See the full list of Entity Components available for addComponent() — health, movement, navigation, combat, AI goals, and more.

import { Texture, Model } from 'jepia';

const tex = new Texture('myaddon:special_texture', './assets/special.png');
const model = new Model('myaddon:special_model', './models/special.geo.json');

import { TextureLayer } from 'jepia';

// Basic color layer (default type)
const color = new TextureLayer('Creamy', 'myaddon:llama_creamy',
  'textures/entity/llama_creamy.png');

// Normal map layer
const normal = new TextureLayer('Stone Normal', 'myaddon:stone_normal',
  'textures/blocks/stone_normal.png', 'normal');

// Additive glow overlay
const glow = new TextureLayer('Ghost Glow', 'myaddon:ghost_glow',
  'textures/entity/ghost_glow.png')
  .setBlending('additive');

// Atlas sub-region (top-left quadrant of a 2x2 atlas)
const atlasLayer = new TextureLayer('Mob 0', 'myaddon:mob_0',
  'textures/entity/mob_atlas.png')
  .setUvOffset([0, 0])
  .setUvScale([0.5, 0.5]);

import { TextureLayer, TextureSet } from 'jepia';

// Create texture layers
const color = new TextureLayer('Base', 'myaddon:base_color', 'textures/entity/base.png');
const normal = new TextureLayer('Normal', 'myaddon:base_normal', 'textures/entity/base_normal.png', 'normal');
const mer = new TextureLayer('MER', 'myaddon:base_mer', 'textures/entity/base_mer.png', 'mer');

// Create texture set and assign layers
const set = new TextureSet('Base PBR', 'myaddon:base_pbr');
set.setColor(color)
   .setNormal(normal)
   .setMer(mer);

// Alternative: assign raw values
const set2 = new TextureSet('Uniform PBR', 'myaddon:uniform_pbr');
set2.setColor([255, 0, 0, 255]) // RGBA array
    .setHeightmap(128); // uniform height value

import { Material, MaterialDefine, MaterialState, BlendFactor, VanillaMaterials } from 'jepia';

// Inherit from a vanilla material
const mat = new Material('Glow Material', 'myaddon:glow')
  .setParent(VanillaMaterials.ENTITY_ALPHABLEND)
  .addDefine(MaterialDefine.USE_EMISSIVE)
  .addState(MaterialState.Blending)
  .setBlendSrc(BlendFactor.SourceAlpha)
  .setBlendDst(BlendFactor.One);

// Convenience: create from vanilla shorthand
const mat2 = Material.fromVanilla('myaddon:cutout', VanillaMaterials.ENTITY_ALPHATEST);

VanillaMaterials.ENTITY               // "entity"
VanillaMaterials.ENTITY_ALPHATEST     // "entity_alphatest"
VanillaMaterials.ENTITY_ALPHABLEND    // "entity_alphablend"
VanillaMaterials.ENTITY_CHANGE_COLOR  // "entity_change_color"
VanillaMaterials.ENTITY_EMISSIVE      // "entity_emissive"
VanillaMaterials.PARTICLES            // "particles"
// ... and many more — see VanillaMaterials.ALL for the full list

BlendFactor.Zero             // multiplies by zero
BlendFactor.One              // passes through unchanged
BlendFactor.SourceColor      // uses source color value
BlendFactor.DestColor        // uses destination color value
BlendFactor.SourceAlpha      // uses source alpha
BlendFactor.DestAlpha        // uses destination alpha
BlendFactor.OneMinusSrcAlpha // 1 minus source alpha (common for standard transparency)

MaterialDefine.ALPHA_TEST      // cutout transparency
MaterialDefine.GLINT           // enchantment-glint effect
MaterialDefine.USE_EMISSIVE    // emissive texture support
MaterialDefine.USE_OVERLAY     // overlay tinting support
MaterialDefine.TINTED_ALPHA_TEST // tinted alpha test

MaterialState.Blending         // enable alpha blending
MaterialState.DisableCulling   // render both faces (no backface culling)
MaterialState.DisableDepthWrite // do not write to depth buffer

import { RenderController } from 'jepia';

// Simple single-texture entity
const rc = new RenderController('Robot Controller', 'myaddon:robot')
  .setGeometry('Geometry.default')
  .setMaterials([{ '*': 'Material.default' }])
  .setTextures(['Texture.default']);

// Multi-variant entity (ocelot pattern — texture array + q.variant)
const rc2 = new RenderController('Ocelot Controller', 'myaddon:ocelot')
  .setGeometry('Geometry.default')
  .setMaterials([{ '*': 'Material.default' }])
  .addTextureArray('skins', ['Texture.wild', 'Texture.black', 'Texture.red'])
  .setTextures(['Array.skins[q.variant]']);

// Static factory from TextureLayer instances
import { TextureLayer, RenderController } from 'jepia';
const layers = [wildLayer, blackLayer, redLayer];
const rc3 = RenderController.fromTextureLayers('Ocelot RC', 'myaddon:ocelot', layers, 'skins');

// Hide all bones by default, then show selectively
rc.setPartVisibility([
  { '*':     0 },                                    // hide everything
  { 'body':  'query.has_armor_slot(1)' },            // show body when chest armor present
  { 'leg*':  '!query.is_sleeping' },                 // show legs when not sleeping
  { 'chest*': 'query.is_chested' },                  // show chest parts when carrying chest
]);

// Hurt flash (blue tint at 50% alpha)
rc.setIsHurtColor({ r: '0.0', g: '0.0', b: '1.0', a: '0.5' });

// Suppress fire overlay on fireballs
rc.setOnFireColor({ r: '0.0', g: '0.0', b: '0.0', a: '0.0' });

// Overlay driven by Molang
rc.setOverlayColor({ r: '1.0', g: '1.0', b: '1.0', a: 'v.overlay_alpha' });

import { Molang } from 'jepia';

const uvAnim = Molang.uvAtlas();
// → { offset: ["v.offset_x", "v.offset_y"], scale: ["v.scale_x", "v.scale_y"] }

rc.setUvAnim(uvAnim.offset, uvAnim.scale);

RenderController.isValidTextureElement('Texture.default')    // true
RenderController.isValidMaterialElement('Material.default')  // true
RenderController.isValidGeometryElement('Geometry.default')  // true

import { TextureAtlas, Texture, Entity } from 'jepia';

// Create a 1024x1024 packed atlas with 8px padding
const atlas = new TextureAtlas('Mob Atlas', 'mymod:mob_atlas', 1024, 1024, 'packed', 8);

// Add texture entries with their pixel dimensions
const skin1 = new Texture('Skin 1', 'mymod:skin1', 'textures/entity/skin1.png');
const skin2 = new Texture('Skin 2', 'mymod:skin2', 'textures/entity/skin2.png');

atlas.addEntry(skin1, 256, 256);
atlas.addEntry(skin2, 256, 512);

// Pack and get UV coordinates
const uvMap = await atlas.pack('shelf');  // or 'maxrects'

// Apply UV coordinates to an entity (sets up uv_anim render controller)
const mob = new Entity('Multi-skin Mob', 'mymod:mob');
await atlas.applyToEntity(mob);

// Reports
const opt = atlas.getOptimizationReport();
// { originalArea, atlasArea, usedArea, wastedArea, efficiency, textureCount, atlasSize }

const mem = atlas.getMemoryReport();
// { originalMemory, atlasMemory, savedMemory, reductionPercentage }

import { AtlasPacker } from 'jepia';

const packer = new AtlasPacker(1024, 1024, 4); // width, height, padding
const rects = [
  { id: 'a', width: 256, height: 256 },
  { id: 'b', width: 128, height: 512 },
  { id: 'c', width: 64, height: 64 },
];

const result = packer.pack(rects, 'maxrects');
// Map<TextureData, { x, y, width, height }>

import { Recipe } from 'jepia';

// Shaped crafting
const pickaxe = new Recipe('Iron Pickaxe', 'myaddon:iron_pickaxe');
pickaxe.setShaped({
  pattern: ['III', ' S ', ' S '],
  key: {
    I: { item: 'minecraft:iron_ingot' },
    S: { item: 'minecraft:stick' }
  },
  result: { item: 'myaddon:iron_pickaxe', count: 1 }
});
addon.addRecipe(pickaxe);

// Furnace smelting
const smelt = new Recipe('Smelt Ore', 'myaddon:smelt_ore');
smelt.setFurnace({
  input: { item: 'myaddon:raw_ore' },
  output: 'myaddon:ingot',
  tags: ['furnace', 'smoker', 'blast_furnace']
});
addon.addRecipe(smelt);

// Brewing
const brew = new Recipe('Brew Speed Potion', 'myaddon:brew_speed');
brew.setBrewing({
  input: 'minecraft:potion',
  reagent: 'myaddon:speed_herb',
  output: 'myaddon:speed_potion'
});
addon.addRecipe(brew);

import { LootTable } from 'jepia';

const golemLoot = new LootTable('Iron Golem Drops', 'myaddon:iron_golem');

// Always drop some iron
golemLoot.addPool({
  rolls: { min: 3, max: 5 },
  entries: [
    { type: 'item', name: 'minecraft:iron_ingot', weight: 1 }
  ]
});

// Chance at a rare drop
golemLoot.addPool({
  rolls: 1,
  entries: [
    { type: 'item', name: 'myaddon:golem_core', weight: 1 },
    { type: 'empty', weight: 4 }
  ]
});

addon.addLootTable(golemLoot);

import { SpawnRule } from 'jepia';

const rule = new SpawnRule('Forest Critter Spawning', 'myaddon:forest_critter');
rule
  .setPopulationControl('animal')
  .addCondition({
    'minecraft:spawns_on_surface': {},
    'minecraft:brightness_filter': { min: 7, max: 15, adjust_for_weather: true },
    'minecraft:weight': { default: 80 },
    'minecraft:biome_filter': { test: 'has_biome_tag', value: 'forest' }
  });

addon.addSpawnRule(rule);

import { TradeTable } from 'jepia';

const trades = new TradeTable('Scrap Merchant', 'myaddon:scrap_merchant');

// Novice tier — always available
trades.addTier({
  total_exp_required: 0,
  trades: [
    {
      wants: [{ item: 'minecraft:emerald', quantity: 1 }],
      gives: [{ item: 'myaddon:composite_ingot', quantity: 2 }],
      max_uses: 8,
      reward_exp: true,
      trader_exp: 1
    }
  ]
});

// Expert tier — unlocks after earning XP
trades.addTier({
  total_exp_required: 70,
  groups: [
    {
      num_to_select: 1,
      trades: [
        {
          wants: [{ item: 'minecraft:emerald', quantity: 5 }],
          gives: [{ item: 'myaddon:powered_drill', quantity: 1 }]
        },
        {
          wants: [{ item: 'minecraft:emerald', quantity: 4 }],
          gives: [{ item: 'myaddon:electric_motor', quantity: 3 }]
        }
      ]
    }
  ]
});

addon.addTradeTable(trades);

import { Biome } from 'jepia';

const crystalForest = new Biome('Crystal Forest', 'myaddon:crystal_forest');
crystalForest
  .setClimate({ temperature: 0.4, downfall: 0.5 })
  .setSurfaceBuilder('minecraft:overworld', {
    top_material: 'myaddon:crystal_grass',
    mid_material: 'minecraft:dirt',
    sea_material: 'minecraft:water',
  })
  .addTag('forest')
  .addTag('cold')
  .setCreatureSpawnProbability(0.2)
  .setHumid(true);

addon.addBiome(crystalForest);

import { Feature } from 'jepia';

// Ore feature
const crystalOre = new Feature('Crystal Ore', 'myaddon:crystal_ore_feature');
crystalOre
  .setType('minecraft:ore_feature')
  .setData({
    count: 6,
    replace_rules: [
      { places_block: 'myaddon:crystal_ore', may_replace: ['minecraft:stone', 'minecraft:deepslate'] },
    ],
  });

addon.addFeature(crystalOre);

import { FeatureRule } from 'jepia';

const crystalOreRule = new FeatureRule('Crystal Ore Rule', 'myaddon:crystal_ore_overworld');
crystalOreRule
  .setPlacesFeature('myaddon:crystal_ore_feature')
  .addBiomeFilter({ test: 'has_biome_tag', operator: '==', value: 'overworld' })
  .setPlacementPass('feature_placement_pass')
  .setDistribution({
    iterations: 8,
    scatter_chance: { numerator: 2, denominator: 3 },
    x: { distribution: 'uniform', extent: [0, 16] },
    y: { distribution: 'uniform', extent: [0, 64] },
    z: { distribution: 'uniform', extent: [0, 16] },
  });

addon.addFeatureRule(crystalOreRule);

import { Dimension } from 'jepia';

const crystalVoid = new Dimension('Crystal Void', 'myaddon:crystal_void');
crystalVoid
  .setBounds(0, 256)
  .setGeneratorType('overworld');

addon.addDimension(crystalVoid);

Molang Utilities

The Molang class provides static helpers for building type-safe Molang expression strings used in render controllers, animations, and particle definitions. The MolangQuery constant object provides named constants for common query properties.

import { Molang, MolangQuery } from 'jepia';

// Query expressions
Molang.query('variant')          // → "q.variant"
Molang.query('is_invisible')     // → "q.is_invisible"

// Query with arguments
Molang.queryCall('has_armor_slot', 1)       // → "q.has_armor_slot(1)"
Molang.queryCall('armor_color_slot', 1, 0)  // → "q.armor_color_slot(1, 0)"

// Variables
Molang.variable('decor_index')   // → "v.decor_index"
Molang.variable('offset_x')      // → "v.offset_x"

// Entity property query (shapeshifter pattern)
Molang.property('minecraft:shape')    // → "q.property('minecraft:shape')"

// Array access
Molang.arrayIndex('Array.skins', Molang.query('variant'))
// → "Array.skins[q.variant]"

// Convenience: variant array selection
Molang.variantArray('skins')   // → "Array.skins[q.variant]"

// Ternary
Molang.ternary(Molang.query('is_sheared'), 'Geometry.sheared', 'Geometry.woolly')
// → "(q.is_sheared ? Geometry.sheared : Geometry.woolly)"

// Logical NOT
Molang.not(Molang.query('is_sleeping'))  // → "!q.is_sleeping"

// Equality comparison
Molang.equals(Molang.property('minecraft:shape'), "'chicken'")
// → "q.property('minecraft:shape') == 'chicken'"

// Property-to-index (shapeshifter nested ternary)
Molang.propertyToIndex('minecraft:shape', ['shapeshifter', 'chicken', 'cat'])
// → "(q.property('minecraft:shape') == 'shapeshifter' ? 0 : ...)"

// Math helpers
Molang.mathCos('q.anim_time * 12.3')   // → "math.cos(q.anim_time * 12.3)"
Molang.mathFloor('q.variant * 0.5')    // → "math.floor(q.variant * 0.5)"

// UV atlas helpers
const uvAnim = Molang.uvAtlas();
// → { offset: ["v.offset_x", "v.offset_y"], scale: ["v.scale_x", "v.scale_y"] }

const [uOffset, uScale] = Molang.uvAtlasAxis();
// uOffset → "v.offset_x", uScale → "v.scale_x"

MolangQuery constants

Packager

The Packager class creates distributable .mcaddon and .mcpack archives from generated pack folders using ZIP compression.

import { Packager, packageAddon } from 'jepia';

// Using the Packager class
const packager = new Packager({
  outputPath: './dist',
  addonName: 'MyAddon',
  format: 'mcaddon',         // 'mcaddon' | 'mcpack' | 'both'
  compressionLevel: 9,       // 0-9 (optional)
});

const result = await packager.package(
  './output/behavior_pack',
  './output/resource_pack'
);

console.log(result.success);       // true
console.log(result.totalSize);     // bytes
console.log(result.addonPackPath); // './dist/MyAddon.mcaddon'

// Convenience function (one-liner)
await packageAddon(
  './output/behavior_pack',
  './output/resource_pack',
  './dist',
  'MyAddon'
);

PackageResult

interface PackageResult {
  behaviorPackPath?: string;   // path to .mcpack (behavior)
  resourcePackPath?: string;   // path to .mcpack (resource)
  addonPackPath?: string;      // path to .mcaddon
  totalSize: number;           // total bytes across all archives
  packSizes: {
    behaviorPack?: number;
    resourcePack?: number;
    addonPack?: number;
  };
  success: boolean;
  error?: string;
}

Configuration

Jepia supports configuration files for storing add-on metadata, build options, and persisted UUIDs. Configuration is validated using Zod schemas.

jepia.config.json

{
  "name": "MyAddon",
  "author": "YourName",
  "version": "1.0.0",
  "description": "A custom Minecraft add-on",
  "namespace": "myaddon",
  "baseGameVersion": "1.20.0",
  "build": {
    "output": "./dist",
    "createPackage": true,
    "packageFormat": "mcaddon",
    "validate": true,
    "minify": false
  },
  "uuids": {
    "behaviorPackUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "behaviorModuleUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "resourcePackUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "resourceModuleUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

UUID Persistence

When addon.generate() is called, Jepia automatically writes the generated UUIDs to jepia.config.json. On subsequent builds, the same UUIDs are reused so that Minecraft treats the pack as the same installation. This prevents duplicate pack entries and preserves world-level settings.

Configuration API

Examples

The repository includes several ready‑to‑run examples in the examples/ directory:

• simple‑addon.ts – Basic items, blocks, entities, recipes, and loot tables.
• comprehensive‑addon.ts – A larger add‑on ("FantasyRealm") with 21 components across all categories.
• texture‑layering‑migration.ts – Seven migration scenarios demonstrating the upgrade path from the legacy single-texture API to multi-layer, PBR TextureSet, and Vibrant Visuals systems.

Run any example with:

bun run examples/simple-addon.ts

Full Rendering Pipeline Example

import {
  Addon, Entity,
  TextureLayer, RenderController,
  Material, VanillaMaterials,
  Molang
} from 'jepia';

const addon = new Addon('MyMod', 'Custom entity with full rendering pipeline');

// 1. Create texture variants
const wildLayer  = new TextureLayer('Wild',  'mymod:ocelot_wild',  'textures/entity/ocelot_wild.png');
const blackLayer = new TextureLayer('Black', 'mymod:ocelot_black', 'textures/entity/ocelot_black.png');
const redLayer   = new TextureLayer('Red',   'mymod:ocelot_red',   'textures/entity/ocelot_red.png');

// 2. Create material
const mat = Material.fromVanilla('mymod:ocelot_mat', VanillaMaterials.ENTITY_ALPHATEST);

// 3. Create render controller (auto-configures texture array + q.variant)
const rc = RenderController.fromTextureLayers(
  'Ocelot RC', 'mymod:ocelot',
  [wildLayer, blackLayer, redLayer]
);

// 4. Add hurt color tint
rc.setIsHurtColor({ r: '0.0', g: '0.0', b: '1.0', a: '0.5' });

// 5. Create entity and wire everything together
const ocelot = new Entity('Ocelot', 'mymod:ocelot');
ocelot.addComponent('minecraft:health', { value: 10 });
ocelot.setMaterial(mat);
ocelot.setRenderController(rc);

addon.addEntity(ocelot);
await addon.generate('./output');

Advanced Usage

Texture Layering & PBR

Jepia supports the full Minecraft PBR pipeline via TextureLayer and TextureSet. This allows building complex textures with normal maps, MER (metalness/emissive/roughness), and heightmaps for Vibrant Visuals rendering.

import { TextureLayer, TextureSet } from 'jepia';

const color     = new TextureLayer('Base', 'myaddon:base_color', 'textures/entity/base.png');
const normalMap = new TextureLayer('Normal', 'myaddon:base_normal',
  'textures/entity/base_normal.png', 'normal');
const mer       = new TextureLayer('MER', 'myaddon:base_mer',
  'textures/entity/base_mer.png', 'mer');

const pbr = new TextureSet('Base PBR', 'myaddon:base_pbr');
pbr.setColor(color)
   .setNormal(normalMap)
   .setMer(mer);
// Generates a .texture_set.json file for Vibrant Visuals

Dynamic Geometry Selection

import { RenderController, Molang } from 'jepia';

// Sheep: woolly vs sheared geometry based on q.is_sheared
const rc = new RenderController('Sheep RC', 'myaddon:sheep')
  .addGeometryArray('geos', ['Geometry.default', 'Geometry.sheared'])
  .setGeometry(Molang.arrayIndex('Array.geos', Molang.query('is_sheared')))
  .setMaterials([{ '*': 'Material.default' }])
  .setTextures(['Texture.default']);

Shapeshifter Pattern (Property-Based Geometry)

import { RenderController, Molang } from 'jepia';

const shapes = ['shapeshifter', 'chicken', 'cat', 'sheep'];
const rc = new RenderController('Shapeshifter RC', 'myaddon:shapeshifter')
  .addGeometryArray('geos', shapes.map(s => `Geometry.${s}`))
  .setGeometry(Molang.arrayIndex(
    'Array.geos',
    Molang.propertyToIndex('minecraft:shape', shapes)
  ))
  .setMaterials([{ '*': 'Material.default' }])
  .setTextures(['Texture.default']);

Configuration File

You can store add‑on metadata (including generated UUIDs) in a jepia.config.json file. This ensures consistent UUIDs across multiple builds.

{
  "name": "MyAddon",
  "author": "Your Name",
  "uuids": {
    "behaviorPackUUID": "...",
    "resourcePackUUID": "..."
  }
}

Scripting

Jepia integrates Minecraft's Script API directly into the add‑on build pipeline. You write runtime game logic in the same TypeScript file as your JSON components. During addon.generate(), Jepia extracts the script callbacks, bundles them with Bun.build, and writes behavior_pack/scripts/main.js. The behavior pack manifest automatically gains a "type": "script" module and the correct @minecraft/* dependencies.

addon.script()

Registers an inline runtime script block. The callback body is extracted and bundled into scripts/main.js.

Simple form — defaults to @minecraft/server at the latest stable version:

addon.script((ctx) => {
  const { world, system } = ctx.server;

  world.afterEvents.entityHitEntity.subscribe((event) => {
    const attacker = event.damagingEntity;
    if (attacker.typeId === 'minecraft:player') {
      system.run(() => attacker.sendMessage('You struck something!'));
    }
  });
});

Full form — specify module versions explicitly:

addon.script({
  modules: {
    server: '2.5.0',     // @minecraft/server (Scripting V2 stable)
    serverUi: '2.0.0',   // @minecraft/server-ui (Scripting V2 stable)
  },
}, (ctx) => {
  const { world } = ctx.server;
  const { ActionFormData } = ctx.serverUi;

  world.afterEvents.itemUse.subscribe((event) => {
    const form = new ActionFormData()
      .title('Menu')
      .button('Hello');
    form.show(event.source);
  });
});

Multiple addon.script() calls are merged into a single scripts/main.js with deduplicated imports.

ScriptContext properties

@minecraft/server version → Minecraft version

Only Scripting V2 (2.x.x) is supported. V1 (1.x.x) has been removed.

addon.setScriptModuleVersion()

Override the version for a specific module globally:

addon.setScriptModuleVersion('@minecraft/server', '2.5.0'); // Scripting V2 stable

addon.scriptFile()

Points to an existing TypeScript or JavaScript file. Jepia bundles it alongside any inline blocks. Useful for complex scripts or existing codebases.

// Single file
addon.scriptFile('./scripts/events.ts');

// Multiple files (bundled into one output)
addon.scriptFile('./scripts/events.ts');
addon.scriptFile('./scripts/commands.ts');

File-based scripts can use normal top-level import ... from '@minecraft/server' statements — Jepia treats all @minecraft/* modules as externals automatically.

Generated output structure

behavior_pack/
├── manifest.json        ← script module + @minecraft/server dependency added
└── scripts/
    └── main.js          ← bundled runtime code (runs inside Minecraft only)

Generated manifest (excerpt)

{
  "modules": [
    { "type": "data", "uuid": "...", "version": [1, 0, 0] },
    { "type": "script", "language": "javascript",
      "uuid": "...", "version": [1, 0, 0], "entry": "scripts/main.js" }
  ],
  "dependencies": [
    { "module_name": "@minecraft/server", "version": "2.5.0" }
  ]
}

Custom Components V2

Custom Components bridge JSON block/item definitions with runtime Script API handlers. Calling addCustomComponent() on a Block or Item does two things automatically during addon.generate():

1. Adds the component name to the block/item JSON components section.
2. Generates system.beforeEvents.startup.subscribe() registration code in scripts/main.js.

Block.addCustomComponent()

import { Block } from 'jepia';

const cloudBlock = new Block('Cloud Block', 'myaddon:cloud_block');

cloudBlock.addCustomComponent(
  'myaddon:crumble_on_step',   // namespaced component name
  {
    // Handler runs inside Minecraft — system is imported by generated startup code
    onStepOn: (event) => {
      const { block, dimension } = event;
      system.run(() => {
        dimension.runCommand(`setblock ${block.x} ${block.y} ${block.z} air`);
      });
    },
    onEntityFallOn: (event) => {
      event.entity.sendMessage('The cloud crumbles!');
    },
  },
  { fragile: true }  // optional JSON params embedded in block component entry
);

Block event handlers (BlockCustomComponentHandlers):

Item.addCustomComponent()

import { Item } from 'jepia';

const coin = new Item('Lucky Coin', 'myaddon:lucky_coin');

coin.addCustomComponent('myaddon:flip_coin', {
  onUse: (event) => {
    const { source: player } = event;
    system.run(() => {
      if (Math.random() > 0.5) {
        player.sendMessage('Heads! Good fortune.');
        player.addEffect('minecraft:luck', 200, { amplifier: 0 });
      } else {
        player.sendMessage('Tails! Better luck next time.');
      }
    });
  },
  onHitEntity: (event) => {
    event.attackingEntity?.sendMessage('Strike with the Lucky Coin!');
  },
});

Item event handlers (ItemCustomComponentHandlers):

Accessors

block.hasCustomComponents();           // boolean
block.getCustomComponents();           // CustomComponentRegistration[]
block.getCustomComponent('ns:name');   // single registration or undefined
block.getSummary().customComponentCount; // number

Custom Commands

Register a custom slash command. Jepia generates the startup registration code in scripts/main.js automatically, including enum registration and command handler wiring.

import { CustomCommandPermissionLevel, CustomCommandParamType } from 'jepia';

addon.addCustomCommand({
  name: 'myaddon:heal',
  description: 'Heal targeted players to full health',
  permissionLevel: CustomCommandPermissionLevel.GameDirectors,
  mandatoryParameters: [
    { type: CustomCommandParamType.PlayerSelector, name: 'targets' },
  ],
  // system is imported in the generated startup code — use it directly.
  // This callback runs inside Minecraft only.
  callback: (origin, targets) => {
    system.run(() => {
      for (const player of targets) {
        const health = player.getComponent('minecraft:health');
        if (health) health.setCurrentValue(health.effectiveMax);
        player.sendMessage('You have been healed!');
      }
    });
  },
});

CustomCommandConfig

CustomCommandPermissionLevel

CustomCommandParamType

Custom enums

addon.addCustomCommand(
  {
    name: 'myaddon:give_ore',
    description: 'Give player an ore type',
    mandatoryParameters: [
      { type: CustomCommandParamType.PlayerSelector, name: 'target' },
      { type: CustomCommandParamType.Enum, name: 'oreType' },
    ],
    callback: (origin, target, oreType) => {
      system.run(() => {
        target[0]?.runCommand(`give @s myaddon:${oreType}_ore`);
      });
    },
  },
  [
    { name: 'OreType', values: ['iron', 'copper', 'gold'] },
  ]
);

Cross-Reference Helpers

These methods bridge component identifiers between JSON definitions and script code. They're especially useful when component IDs are dynamic or derived from user input.

const fireSword = new Item('Fire Sword', 'myaddon:fire_sword');
addon.addItem(fireSword);

// Get the identifier for use in scripts
const id = addon.getItemId(fireSword);  // "myaddon:fire_sword"

// Or look up all registered IDs
const itemIds = addon.getRegisteredItemIds();   // ["myaddon:fire_sword", ...]
const blockIds = addon.getRegisteredBlockIds();  // ["myaddon:magic_ore", ...]
const entityIds = addon.getRegisteredEntityIds(); // [...]

Constants injection

When scripts are enabled, Jepia automatically injects a constants object into scripts/main.js containing all registered component identifiers in SCREAMING_SNAKE_CASE:

// Auto-generated in scripts/main.js
export const ITEMS = {
  FIRE_SWORD: "myaddon:fire_sword",
  COOL_POTION: "myaddon:cool_potion",
};
export const BLOCKS = {
  MAGIC_ORE: "myaddon:magic_ore",
};
export const ENTITIES = {
  DRAGON: "myaddon:dragon",
};

Use these constants inside your script callbacks to avoid string duplication between JSON and runtime code.

Script Types Reference

ScriptModuleId

type ScriptModuleId =
  | '@minecraft/server'           // stable 2.5.0 (V2)
  | '@minecraft/server-ui'        // stable 2.0.0 (V2)
  | '@minecraft/common'           // stable 1.2.0
  | '@minecraft/server-gametest'  // 1.0.0-beta only
  | '@minecraft/server-admin'     // 1.0.0-beta only
  | '@minecraft/server-net'       // 1.0.0-beta only
  | '@minecraft/server-editor'    // 0.1.0-beta only
  | '@minecraft/server-graphics'  // 1.0.0-beta only
  | '@minecraft/diagnostics'      // 1.0.0-beta only
  | '@minecraft/debug-utilities'; // 1.0.0-beta only

ScriptOptions

interface ScriptOptions {
  modules?: {
    server?: string;          // @minecraft/server version
    serverUi?: string;        // @minecraft/server-ui version
    common?: string;          // @minecraft/common version
    serverGametest?: string;
    serverAdmin?: string;
    serverNet?: string;
    serverEditor?: string;
    serverGraphics?: string;
    diagnostics?: string;
    debugUtilities?: string;
  };
}

UUID persistence

The script module UUID (required for stable pack identity) is stored in jepia.config.json alongside the behavior/resource pack UUIDs:

{
  "addonName": "MyAddon",
  "uuids": {
    "behaviorPackUUID": "...",
    "behaviorModuleUUID": "...",
    "resourcePackUUID": "...",
    "resourceModuleUUID": "...",
    "scriptModuleUUID": "..."
  }
}

Dialogue

NPC dialogue definitions written to behavior_pack/dialogue/<id>.json. Format version 1.20.80.

import { Dialogue } from 'jepia';

const dlg = new Dialogue('Trader Dialogue', 'myaddon:trader');
dlg.addScene('intro', {
  npc_name: 'Mysterious Trader',
  text: 'What do you seek?',
  on_open_commands: ['/effect @initiator speed 10 1'],
  buttons: [
    { name: 'Shop',   commands: ['/dialogue open @e[type=myaddon:trader,r=3] @initiator shop'] },
    { name: 'Leave',  commands: [] },
  ],
});
addon.addDialogue(dlg);

Camera

Custom camera presets written to resource_pack/cameras/presets/<id>.json. Format version 1.21.0.

import { Camera } from 'jepia';

const cam = new Camera('Over-Shoulder', 'myaddon:over_shoulder');
cam.setInheritFrom('minecraft:follow_orbit')
   .setRadius(4)
   .setViewOffset(2.0, 0.5)
   .setEntityOffset(0, 1.5, 0)
   .setStartingRotation(-10, 0);
addon.addCamera(cam);

Fog

Fog definitions written to resource_pack/fogs/<id>.json. Format version 1.16.100.

import { Fog } from 'jepia';

const fog = new Fog('Mystic Fog', 'myaddon:mystic');
fog.setDistanceFog('air',   { fog_start: 0.8, fog_end: 1.0, fog_color: '#c0c0ff', render_distance_type: 'render' })
   .setDistanceFog('water', { fog_start: 0,   fog_end: 30,  fog_color: '#1a3080', render_distance_type: 'fixed' })
   .setVolumetricDensity('air', { max_density: 0.3, uniform: false })
   .setVolumetricMediaCoefficients('air', { scattering: [0.02, 0.02, 0.02] });
addon.addFog(fog);

SoundDefinition

Sound event definitions aggregated into a single resource_pack/sounds/sound_definitions.json. Format version 1.20.20. Event names use Bedrock's dot-notation (e.g. "random.chestopen").

import { SoundDefinition } from 'jepia';

const snd = new SoundDefinition('Drill Use', 'myaddon.drill.use');
snd.setCategory('block')
   .addSoundFile('sounds/myaddon/drill_use1')
   .addSoundEntry({ name: 'sounds/myaddon/drill_use2', volume: 0.9, pitch: [0.9, 1.1] })
   .setDistance(4, 16);
addon.addSoundDefinition(snd); // merged into sound_definitions.json

BlockCullingRule

Block face culling rules written to resource_pack/block_culling/<id>.json. Format version 1.21.80.

import { BlockCullingRule } from 'jepia';

const cull = new BlockCullingRule('Glass Pane Culling', 'myaddon:glass_pane');
cull.addFaceRule('block', 0, 'north', 'same_block')
    .addFaceRule('block', 0, 'south', 'same_block')
    .addFaceRule('block', 0, 'east',  'same_block')
    .addFaceRule('block', 0, 'west',  'same_block');
addon.addBlockCullingRule(cull);

Conditions: "default", "same_block", "same_block_permutation", "same_culling_layer".

Plugin System

The plugin system lets you hook into the add-on generation lifecycle. Implement JepiaPlugin and register it with addon.use(plugin).

import type { JepiaPlugin } from 'jepia';

const myPlugin: JepiaPlugin = {
  name: 'my-plugin',

  onBeforeGenerate({ addonName, outputPath, metadata }) {
    console.log(`Building "${addonName}" → ${outputPath}`);
    metadata.startTime = Date.now();
  },

  onAfterGenerate({ metadata }) {
    const ms = Date.now() - (metadata.startTime as number);
    console.log(`Done in ${ms}ms`);
  },
};

addon.use(myPlugin);
await addon.generate('./output');

Both hooks are called in registration order and support async functions.

Particle

Particle effect definitions written to resource_pack/particles/<id>.json. Format version 1.10.0.

import { Particle } from 'jepia';

const sparks = new Particle('Sparks', 'myaddon:sparks');
sparks.setRenderParameters('particles_alpha', 'textures/particle/particles');
sparks.setEmitterRate('steady', { spawn_rate: 10, max_particles: 50 });
sparks.setEmitterLifetime('looping', { active_time: 2 });
sparks.setEmitterShape('sphere', { radius: 0.5 });
sparks.setParticleLifetime(1.5);
sparks.setAppearanceBillboard({ size: [0.1, 0.1], facing_camera_mode: 'lookat_xyz' });
addon.addParticle(sparks);

Animation

Bone animations written to resource_pack/animations/<id>.json. Format version 1.8.0.

import { Animation } from 'jepia';

const walk = new Animation('Walk Anim', 'myaddon:walk');
walk.setLoop(true);
walk.setAnimationLength(1.0);
walk.addBoneKeyframes('left_leg', 'rotation', {
  '0.0': ['-30', '0', '0'],
  '0.5': ['30', '0', '0'],
  '1.0': ['-30', '0', '0'],
});
walk.addTimelineEvent('0.5', '/playsound step.grass @s');
addon.addAnimation(walk);

AnimationController

Animation state machines written to resource_pack/animation_controllers/<id>.json. Format version 1.10.0.

import { AnimationController } from 'jepia';

const ctrl = new AnimationController('Move Controller', 'myaddon:move');
ctrl.setInitialState('idle');
ctrl.addState('idle', {
  animations: ['idle'],
  transitions: [{ walk: 'q.is_moving' }],
});
ctrl.addState('walk', {
  animations: ['walk'],
  transitions: [{ idle: '!q.is_moving' }],
  blend_transition: 0.2,
});
addon.addAnimationController(ctrl);

Attachable

Item appearance when worn or held, written to resource_pack/attachables/<id>.json. Format version 1.8.0.

import { Attachable } from 'jepia';

const helmet = new Attachable('Iron Helmet', 'myaddon:iron_helmet');
helmet.setMaterials({ default: 'armor' });
helmet.setTextures({ default: 'textures/models/armor/iron_1' });
helmet.setGeometry({ default: 'geometry.humanoid.armor.helmet' });
helmet.setRenderControllers(['controller.render.armor']);
addon.addAttachable(helmet);

ClientBiome

Client-side biome rendering written to resource_pack/biomes_client/<id>.json. Format version 1.0.0. Pairs with the server-side Biome component.

import { ClientBiome } from 'jepia';

const crystal = new ClientBiome('Crystal Caves Client', 'myaddon:crystal_caves');
crystal.setWaterColor('#1a3c6b');
crystal.setSkyColor('#0a0a2e');
crystal.setFogAppearance('#0a0a2e', 0.0, 0.5);
crystal.setGrassColor('#2d5a27');
crystal.setFoliageColor('#1e3a1e');
addon.addClientBiome(crystal);

JigsawStructure

Procedural jigsaw structure definitions written to behavior_pack/worldgen/structures/<id>.json. Format version 1.21.20.

import { JigsawStructure } from 'jepia';

const village = new JigsawStructure('Village', 'myaddon:village');
village.setStep('surface_structures');
village.setStartPool('myaddon:village/town_centers');
village.setMaxDepth(6);
village.setStartHeight({ type: 'constant', value: { absolute: 0 } });
village.setTerrainAdaptation('beard_thin');
village.setHeightmapProjection('world_surface');
village.addBiomeFilter({ test: 'has_biome_tag', value: 'village' });
addon.addJigsawStructure(village);

TemplatePool

Weighted structure template pools written to behavior_pack/worldgen/template_pools/<id>.json. Format version 1.21.20.

import { TemplatePool } from 'jepia';

const pool = new TemplatePool('Town Centers', 'myaddon:village/town_centers');
pool.addElement({ location: 'myaddon:village/plains_center' }, 1);
pool.addElement({ location: 'myaddon:village/desert_center' }, 1);
pool.addEmptyElement(3); // 60% chance of nothing
pool.setFallback('minecraft:empty');
addon.addTemplatePool(pool);

StructureSet

Structure placement rules written to behavior_pack/worldgen/structure_sets/<id>.json. Format version 1.21.20.

import { StructureSet } from 'jepia';

const set = new StructureSet('Village Set', 'myaddon:villages');
set.setPlacement({
  type: 'minecraft:random_spread',
  salt: 10387312,
  spacing: 34,
  separation: 8,
  spread_type: 'linear',
});
set.addStructure('myaddon:village', 1);
addon.addStructureSet(set);

ProcessorList

Block transformation rules for structure placement, written to behavior_pack/worldgen/processors/<id>.json. Format version 1.21.20.

import { ProcessorList } from 'jepia';

const proc = new ProcessorList('Mossy Processor', 'myaddon:mossy');
proc.addBlockIgnore(['minecraft:structure_void']);
proc.addRule({
  input_predicate: { predicate_type: 'minecraft:block_match', block: 'minecraft:cobblestone' },
  location_predicate: { predicate_type: 'minecraft:always_true' },
  output_state: { name: 'minecraft:mossy_cobblestone' },
});
addon.addProcessorList(proc);

Validation

Every component is validated against the official Minecraft JSON schemas using AJV. Validation happens automatically when you add components and before file generation.

If a component fails validation, Jepia throws a detailed error with schema‑path and error messages. You can also trigger validation manually:

import { validator } from 'jepia';

const isValid = validator.validateItem(item.toJSON());
if (!isValid) {
  console.error(validator.errors);
}

All render-pipeline components expose a validate() method that returns { valid: boolean, errors: string[] }:

const rc = new RenderController('My RC', 'myaddon:entity')
  .setGeometry('Geometry.default')
  .setMaterials([{ '*': 'Material.default' }])
  .setTextures(['Array.skins[q.variant]']); // references array not yet defined

const result = rc.validate();
// result.valid → false
// result.errors → ['Texture reference "Array.skins[q.variant]" uses array "Array.skins"
//                   which is not defined in textureArrays...']

The following schemas are bundled for validation:

• item.schema.json – Items (format_version 1.21.40+)
• block.schema.json – Blocks (format_version 1.21.40+)
• entity.schema.json – Entities (format_version 1.21.40+)
• material.schema.json – Material files
• render_controller.schema.json – Render controllers (format_version 1.8.0)
• texture_set.schema.json – Texture sets (format_version 1.16.100 / 1.21.30)