HeroCore > https://github.com/HerotaleRPG/herocore/

REQUIRED FOR HEROES RPG MOD

RPG attribute, combat, and progression framework for Hytale.

HeroCore is a schema and formula library that extends Hytale's native ECS (Entity Component System). It provides primary attributes, derived stat calculations, a multi-stage damage/heal pipeline, status effects, leveling, and more — all wired through Hytale's native EntityStatMap, StaticModifier, and ECS event systems. No bridge classes, no parallel stat engines, no custom event buses.

Version: 0.2.0
Server: Hytale 2026.02.17+
Java: 25
Author: Kainzo

---

Table of Contents

1. Architecture Overview
2. Plugin Lifecycle
3. ECS Components
4. Attribute System
5. Stat Derivation
6. Damage Pipeline
7. Heal Pipeline
8. Combat State & Timeout
9. Status Effects
10. Leveling & Progression
11. Configuration
12. Downstream Integration Guide
13. API Reference
14. Building

---

Architecture Overview

HeroCorePlugin (JavaPlugin)
│
├── Schema Layer ── definitions HeroCore owns
│   ├── RPGAttribute enum         62 attributes (primary + secondary)
│   ├── DamageType enum           PHYSICAL, MAGICAL, FIRE, ICE, etc.
│   ├── HealType enum             SPELL, POTION, REGEN_TICK, PASSIVE, ENVIRONMENTAL
│   ├── DamageFlag enum           CRIT, DOT, AOE, MELEE, RANGED, etc.
│   └── CoreConfig                all tuning knobs (damage, heal, derivation, regen)
│
├── Math Layer ── pure functions, unit-testable, zero side effects
│   ├── AttributeDerivationFormulas   primary → secondary bonus amounts
│   ├── DamageFormulas                resistance curves, crit rolls, lifesteal
│   └── HealFormulas                  healing power scaling, heal crit
│
├── ECS Components ── registered in setup(), stored on entities
│   ├── HeroCoreStatsComponent        primary bases (STR/DEX/INT/FAITH/VIT/RES)    PERSISTENT
│   ├── HeroCoreProgressionComponent  level, XP, xpToNextLevel                     PERSISTENT
│   ├── CombatStateComponent          in-combat flag + dt accumulator               transient
│   └── StatusEffectIndexComponent    active effect IDs + remainingSeconds           transient
│
├── ECS Systems ── all extend native Hytale system types
│   ├── HeroCoreSetupSystem           HolderSystem — ensures components on entity add
│   ├── AttributeDerivationSystem     EntityTickingSystem — writes StaticModifiers (BEFORE Recalculate)
│   ├── CombatTimeoutSystem           DelayedEntitySystem — exits combat after timeout
│   └── StatusEffectTickSystem        DelayedEntitySystem — expires timed effects
│
├── Damage Pipeline ── EntityEventSystem chain (SystemDependency ordering)
│   AttackDamageBonusSystem → FallDamageReductionSystem → ResistanceMitigationSystem
│   → CriticalHitSystem → LifestealSystem → MinimumDamageSystem → DamageApplicationSystem
│
├── Heal Pipeline ── EntityEventSystem chain
│   HealingPowerScalingSystem → HealingReceivedBonusSystem → HealCritSystem
│
├── Registries ── API facades for downstream plugins
│   ├── LevelingRegistry          XP granting, level queries, profile management
│   ├── MobRegistry               mob/NPC profile registration and lookup
│   └── ZoneModifierRegistry      zone-scoped modifiers (v0.3 planned)
│
└── Native Hytale (used, not replaced)
    ├── EntityStatMap           single source of truth for all stat values
    ├── StaticModifier          all modifier application
    ├── RegeneratingValue       regen (configured via EntityStatType JSON assets)
    ├── BuilderCodec            component persistence
    └── CommandBuffer.invoke()  ECS event dispatch

Design Principles

1. No parallel infrastructure. HeroCore writes StaticModifier entries into EntityStatMap. There is no second stat container, no bridge syncing values between two systems.
2. Ref<EntityStore> everywhere in runtime. UUID is for persistence only. All methods, events, and systems pass live entity handles.
3. All systems extend native Hytale types. EntityTickingSystem, DelayedEntitySystem, EntityEventSystem, HolderSystem — no custom system abstraction.
4. Pure math is separated from ECS wiring. DamageFormulas, HealFormulas, AttributeDerivationFormulas are static pure functions. Unit tests don't need a server instance.
5. All persistence uses BuilderCodec. No Gson serialization on join/quit events. Components are serialized as part of the entity store's save cycle.

---

Plugin Lifecycle

HeroCorePlugin extends JavaPlugin and follows the standard Hytale module pattern:

Phase	What Happens
preLoad()	Loads CoreConfig from mods/herocore/config.json (falls back to built-in defaults)
setup()	Registers all 4 components, 4 ECS event types, and all systems via getEntityStoreRegistry()
start()	Resolves custom stat type indices via HeroCoreStatTypes.update() and validates them
shutdown()	Logs clean shutdown

Manifest

{
    "Group": "Herotale",
    "Name": "Herocore",
    "Version": "0.2.0",
    "Main": "net.herotale.herocore.impl.HeroCorePlugin",
    "IncludesAssetPack": true
}

---

ECS Components

All components are registered via HeroCoreComponentRegistry.registerComponents() in setup(). Each component follows the standard pattern: implements Component<EntityStore>, copy constructor, clone(), static ComponentType handle.

HeroCoreStatsComponent (persistent)

Holds the six primary RPG attribute base values. These are the inputs to the AttributeDerivationSystem.

Field	Type	Description
strength	float	Physical damage, mining speed, block strength
dexterity	float	Crit chance, attack speed, dodge, move speed
intelligence	float	Spell power, mana, spell crit, magic resist
faith	float	Healing power, mana, mana regen, heal crit, buff strength
vitality	float	Max health, health regen, armor, physical resistance
resolve	float	CC resistance, debuff resistance, stamina regen, threat

Codec keys: HC_Strength, HC_Dexterity, HC_Intelligence, HC_Faith, HC_Vitality, HC_Resolve

HeroCoreProgressionComponent (persistent)

Tracks player level and XP progression.

Field	Type	Default	Description
level	int	1	Current level
currentXP	float	0	Accumulated XP toward next level
xpToNextLevel	float	100	XP threshold for next level-up

Codec keys: HC_Level, HC_CurrentXP, HC_XPToNextLevel

CombatStateComponent (transient)

Tracks whether an entity is in combat using dt-based timing (no wall clock). Reset on enterCombat(), accumulated via tickElapsed(dt).

Method	Description
enterCombat()	Sets in-combat, resets timer to 0
tickElapsed(float dt)	Accumulates time since last damage (only while in combat)
isInCombat()	true while in combat
getSecondsSinceLastDamage()	Elapsed seconds since enterCombat()

StatusEffectIndexComponent (transient)

Thin index that StatusEffectTickSystem reads to expire effects. The actual stat modifications live in EntityStatMap as StaticModifier entries. When an effect expires, StatusEffectTickSystem uses the tracked ModifierRef list to remove all associated modifiers automatically.

public static class EffectEntry {
    public final int stacks;
    public float remainingSeconds; // decremented by dt each tick

    // Modifier tracking for automatic cleanup on expiry
    public void trackModifier(int statIndex, String modifierKey);
    public List<ModifierRef> getModifierRefs();

    public record ModifierRef(int statIndex, String modifierKey) {}
}

Method	Description
addEffect(id, stacks, durationSeconds)	Register a new effect
getEffect(id)	Get an EffectEntry by ID (for calling trackModifier() after applying modifiers)
removeEffect(id)	Remove an effect by ID
getActiveEffects()	Map of all active effects

---

Attribute System

RPGAttribute Enum

RPGAttribute is the authoritative taxonomy of all RPG attributes. It defines 62 attributes across categories:

Category	Examples
Primary	STRENGTH, DEXTERITY, INTELLIGENCE, FAITH, VITALITY, RESOLVE
Combat — Physical	MAX_HEALTH, ARMOR, ATTACK_DAMAGE, ATTACK_SPEED, CRIT_CHANCE, LIFESTEAL
Combat — Magical	SPELL_POWER, SPELL_CRIT_CHANCE, MAGIC_PENETRATION, MAGIC_RESIST
Elemental	ELEMENTAL_DAMAGE_FIRE, ELEMENTAL_RESIST_ICE, ICE_RESISTANCE_PERCENT, etc.
Healing	HEALING_POWER, HEALING_RECEIVED_BONUS, HEAL_CRIT_CHANCE
Resources	MAX_MANA, MAX_STAMINA, MANA_REGEN, HEALTH_REGEN
Mobility	MOVE_SPEED, JUMP_HEIGHT, MINING_SPEED
Progression	XP_GAIN_MULTIPLIER, RARE_DROP_CHANCE

HeroCoreStatTypes

Resolves custom RPG stat type indices at runtime from EntityStatType JSON assets. Mirrors the pattern from DefaultEntityStatTypes.

// After start(), these return valid int indices
HeroCoreStatTypes.getCritChance();       // herocore:crit_chance
HeroCoreStatTypes.getAttackDamage();     // herocore:attack_damage
HeroCoreStatTypes.getSpellPower();       // herocore:spell_power
HeroCoreStatTypes.getPhysicalResistance(); // herocore:physical_resistance
HeroCoreStatTypes.getMagicResist();      // herocore:magic_resist
HeroCoreStatTypes.getAttackSpeed();      // herocore:attack_speed
HeroCoreStatTypes.getMoveSpeed();        // herocore:move_speed
HeroCoreStatTypes.getMiningSpeed();      // herocore:mining_speed
HeroCoreStatTypes.getHealingPower();     // herocore:healing_power
HeroCoreStatTypes.getCritDamageMultiplier(); // herocore:crit_damage_multiplier

// Dynamic lookup by asset ID string
HeroCoreStatTypes.getIndex("herocore:lifesteal");

// Helper: read stat value from an entity ref
float value = HeroCoreStatTypes.getStatValue(entityRef, statIndex);

HeroCoreModifiers

All modifier keys used by HeroCore are constants in HeroCoreModifiers. Zero inline strings in modifier calls.

// Derived stats (written by AttributeDerivationSystem)
HeroCoreModifiers.DERIVED_MAX_HEALTH       // "HC_derived_max_health"
HeroCoreModifiers.DERIVED_CRIT_CHANCE      // "HC_derived_crit_chance"
HeroCoreModifiers.DERIVED_SPELL_POWER      // "HC_derived_spell_power"
HeroCoreModifiers.DERIVED_ATTACK_DAMAGE    // "HC_derived_attack_damage"
HeroCoreModifiers.DERIVED_MOVE_SPEED       // "HC_derived_move_speed"
HeroCoreModifiers.DERIVED_ARMOR            // "HC_derived_armor"
// ... 30+ constants total

// Dynamic key builders
HeroCoreModifiers.effect("burn", "health");  // "HC_effect_burn_health"
HeroCoreModifiers.gear("chest_iron", "armor"); // "HC_gear_chest_iron_armor"
HeroCoreModifiers.derived("custom_stat");    // "HC_derived_custom_stat"

---

Stat Derivation

How It Works

AttributeDerivationSystem is an EntityTickingSystem that runs every tick. It reads the six primary attributes from HeroCoreStatsComponent and writes derived stat bonuses as StaticModifier entries into the entity's EntityStatMap.

It implements EntityStatsSystems.StatModifyingSystem (marker interface) and declares BEFORE EntityStatsSystems.Recalculate via SystemDependency. This ensures:

1. HeroCore writes derived modifiers into EntityStatMap
2. Hytale's native Recalculate system processes all modifiers
3. Final computed values are ready for gameplay systems to read

Downstream stat-modifying systems must also declare BEFORE EntityStatsSystems.Recalculate to avoid race conditions:

@Nonnull
@Override
public Set<Dependency<EntityStore>> getDependencies() {
    return Set.of(
        new SystemDependency<>(Order.BEFORE, EntityStatsSystems.Recalculate.class)
    );
}

HeroCoreStatsComponent (primary bases)
        │
        ▼
AttributeDerivationFormulas.computeDerived()  ← pure math
        │
        ▼
EntityStatMap.putModifier()  ← writes named modifiers
        │
        ▼
EntityStatsSystems.Recalculate  ← native Hytale (runs AFTER)

All modifiers use ADDITIVE stacking on ModifierTarget.MAX. This is intentional — percent-based stats should stack additively. The asset's max field handles capping.

Derivation Formulas

Derived Stat	Formula	Source Attributes
Physical Resistance	(VIT + RES) / 2	Vitality, Resolve
Spell Power	(INT + FAITH) / 2	Intelligence, Faith
Crit Chance	min(1.0, DEX / 200)	Dexterity
Crit Damage Multiplier	1.5 + (STR + INT) / 500	Strength, Intelligence
Attack Damage	STR / 10	Strength
Move Speed	1.0 + DEX / 500	Dexterity
Attack Speed	1.0 + DEX / 300	Dexterity
Magic Resist	INT / 10	Intelligence
Healing Power	FAITH / 10	Faith
Mining Speed	1.0 + STR / 500	Strength

These formulas are in AttributeDerivationFormulas.computeDerived() — a pure static function. All formulas are covered by 13 unit tests.

---

Damage Pipeline

Damage flows through a chain of EntityEventSystem<EntityStore, HeroCoreDamageEvent> implementations, ordered via SystemDependency. Each stage reads stat values from EntityStatMap and modifies the event's modifiedAmount.

Pipeline Stages (in execution order)

#	System	What It Does
1	AttackDamageBonusSystem	Scales damage by attacker's attack_damage stat
2	FallDamageReductionSystem	Reduces fall damage by victim's fall_damage_reduction stat (only activates for DamageType.FALL — skips all other damage types). HeroCore addition — not in the base refactor guide pipeline. Declares AFTER AttackDamageBonusSystem via SystemDependency.
3	ResistanceMitigationSystem	Applies elemental/magic resistance (not physical — that's native)
4	CriticalHitSystem	Rolls crit from crit_chance, multiplies by crit_damage_multiplier
5	LifestealSystem	Heals attacker for lifesteal % of damage (dispatches HeroCoreHealEvent)
6	MinimumDamageSystem	Enforces configurable minimum damage floor
7	DamageApplicationSystem	Writes final damage to EntityStatMap via subtractStatValue()

HeroCoreDamageEvent

public class HeroCoreDamageEvent extends CancellableEcsEvent {
    @Nullable Ref<EntityStore> attacker;  // null = environmental
    DamageType damageType;                // PHYSICAL, FIRE, etc.
    float rawAmount;                      // original damage
    float modifiedAmount;                 // current (mutated by pipeline)
    boolean isCrit;                       // set by CriticalHitSystem
}

Dispatching Damage

From any ECS system with access to a CommandBuffer:

// Dispatch damage to a target entity — flows through entire pipeline
cb.invoke(targetRef, new HeroCoreDamageEvent(attackerRef, DamageType.PHYSICAL, 25f));

// Environmental damage (no attacker)
cb.invoke(targetRef, new HeroCoreDamageEvent(null, DamageType.FIRE, 10f));

CommandBuffer.invoke() is immediate — the event flows through all pipeline stages synchronously.

Cancelling Damage

Any pipeline stage (or a downstream plugin's system) can cancel:

event.setCancelled(true); // all subsequent stages check isCancelled()

---

Heal Pipeline

Same pattern as damage. Three EntityEventSystem<EntityStore, HeroCoreHealEvent> stages:

#	System	What It Does
1	HealingPowerScalingSystem	Scales healing by healer's healing_power stat (SPELL/PASSIVE heals, optionally REGEN_TICK)
2	HealingReceivedBonusSystem	Applies target's healing_received_bonus stat
3	HealCritSystem	Rolls heal crit from heal_crit_chance, multiplies by heal_crit_multiplier

HeroCoreHealEvent

public class HeroCoreHealEvent extends CancellableEcsEvent {
    @Nullable Ref<EntityStore> healer;
    HealType healType;       // SPELL, POTION, REGEN_TICK, PASSIVE, ENVIRONMENTAL
    float rawAmount;
    float modifiedAmount;
    boolean isCrit;
}

Dispatching Heals

cb.invoke(targetRef, new HeroCoreHealEvent(healerRef, HealType.SPELL, 50f));

---

Combat State & Timeout

CombatStateComponent

Entities enter combat when they take damage (DamageApplicationSystem calls combat.enterCombat()). The timer accumulates via world tick dt — no wall clock.

CombatTimeoutSystem

A DelayedEntitySystem that fires every 0.5 seconds (intentionally slower than StatusEffectTickSystem's 0.25s — combat timeout doesn't need sub-second precision, and 0.5s reduces unnecessary iteration). Iterates entities with CombatStateComponent, checks if secondsSinceLastDamage > combatTimeoutSeconds (configurable, default 8.0s from config). When timeout elapses:

1. Sets inCombat = false
2. Dispatches CombatExitEvent via cb.invoke() — downstream plugins can react to this

CombatExitEvent

public class CombatExitEvent extends EcsEvent {
    // Marker event — no fields. Dispatched when combat timeout expires.
}

---

Status Effects

How Effects Work

1. Apply: Write StaticModifier entries into EntityStatMap, record the effect in StatusEffectIndexComponent, and call trackModifier() to register each modifier for automatic cleanup
2. Tick: StatusEffectTickSystem decrements remainingSeconds by dt every 0.25s (intentionally fast — status effects need sub-second precision)
3. Expire: When remainingSeconds <= 0, StatusEffectTickSystem removes all tracked modifiers from EntityStatMap (via the ModifierRef list) and removes the index entry. The tick system owns full cleanup — callers only need to call trackModifier() at apply time

Applying an Effect (downstream code)

// Write the stat modifier
EntityStatMap statMap = store.getComponent(ref, EntityStatsModule.get().getEntityStatMapComponentType());
String modKey = HeroCoreModifiers.effect("burn", "health_regen");
statMap.putModifier(healthRegenIndex, modKey,
    new StaticModifier(ModifierTarget.MAX, CalculationType.ADDITIVE, -5f));

// Record in the index so it auto-expires
StatusEffectIndexComponent index = store.getComponent(ref, StatusEffectIndexComponent.getComponentType());
index.addEffect("burn", 1, 10f); // 1 stack, 10 seconds

// Register the modifier for automatic cleanup on expiry
StatusEffectIndexComponent.EffectEntry entry = index.getEffect("burn");
entry.trackModifier(healthRegenIndex, modKey);
// StatusEffectTickSystem will remove this modifier when the effect expires

StatusEffectDefinition (API data record)

// In api/status/StatusEffect.java — builder pattern
StatusEffect effect = StatusEffect.builder()
    .id("herocore:burn")
    .durationSeconds(5f) // seconds — consistent with ECS dt-based timing
    .source("fire_trap")
    .stacks(3)
    .build();

---

Leveling & Progression

XP Curves

HeroCore provides three XP curve implementations via XpCurve:

Type	Factory	Description
Exponential	XpCurve.exponential(baseXp, growthRate)	Standard RPG curve
Linear	XpCurve.linear(xpPerLevel)	Flat XP per level
Discrete	XpCurve.discrete(long[] thresholds)	Custom thresholds

Presets via XpCurveFactory:

• XpCurveFactory.standard() — base 100, growth 1.15
• XpCurveFactory.fast() — base 50, growth 1.10
• XpCurveFactory.slow() — base 200, growth 1.25
• XpCurveFactory.flatCurve() — 1000 XP per level

LevelingProfile

LevelingProfile profile = LevelingProfile.builder()
    .id("combat")
    .maxLevel(60)
    .xpCurve(XpCurve.exponential(100, 1.15))
    .build();

LevelingRegistry

Register profiles and grant XP:

LevelingRegistry reg = HeroCore.get().getLevelingRegistry();
reg.register(profile);

// In an ECS system with access to Ref, Store, and CommandBuffer:
reg.grantXP(entityRef, store, cb, "combat", 150.0, XPSource.KILL);
int level = reg.getLevel(entityRef, store, "combat");

Level Events

// EcsEvent — dispatched through the ECS event system
public class LevelUpEvent extends EcsEvent {
    int oldLevel, newLevel;
}
public class LevelDownEvent extends EcsEvent {
    int oldLevel, newLevel;
}

LevelUpEvent is dispatched when XP gain causes the entity's computed level to increase (via LevelingRegistry.grantXP()). LevelDownEvent is dispatched when XP is explicitly set lower via LevelingRegistry.setXP() and the recalculated level is lower than the previous level. Both events carry the old and new level values.

---

Configuration

Configuration loads from mods/herocore/config.json. If not present, defaults are copied from the built-in hero-core-defaults.json.

Config Sections

Section	Key Fields
modifierStacking	maxPercentAdditive, multiplicativeCap
damage	critDamageBaseMultiplier (default 2.0), minimumDamage (default 1.0), maxResistanceReduction (default 0.9)
heal	healCritBaseMultiplier, healingPowerScalesRegenTick, healingPowerScalesPassive
resourceRegen	tickIntervalSeconds (default 2.0), outOfCombatBonusMultiplier, combatTimeoutSeconds (default 8.0)
leveling	defaultMaxLevel (60), sourceWeights (per XPSource multipliers)
attributeDerivation	Per-attribute derivation coefficients (vitality, strength, dex, intel, faith, resolve)
defenseDerivation	Per-damage-type resistance derivation coefficients

---

Heroes RPG Mod Implementation Guide

This section is a practical checklist for wiring HeroCore into a full RPG mod: leveling and XP, primary attributes, derived/secondary stats, and equipment integration.

1) Leveling and XP

1. Define one or more LevelingProfile entries (combat, crafting, gathering, etc.).
2. Register profiles in LevelingRegistry during plugin setup() or start().
3. Grant XP from gameplay events using LevelingRegistry.grantXP().

LevelingRegistry leveling = HeroCore.get().getLevelingRegistry();
leveling.register(LevelingProfile.builder()
    .id("combat")
    .maxLevel(60)
    .xpCurve(XpCurve.exponential(100, 1.15))
    .build());

// Award XP in an ECS system with Store + CommandBuffer
leveling.grantXP(entityRef, store, cb, "combat", 120.0, XPSource.KILL);

React to progression with ECS events:

reg.registerSystem(new EntityEventSystem<EntityStore, LevelUpEvent>(LevelUpEvent.class) {
    @Override
    public Query<EntityStore> getQuery() {
        return HeroCoreStatsComponent.getComponentType();
    }

    @Override
    protected void handle(int index, ArchetypeChunk<EntityStore> chunk,
                          Store<EntityStore> store, CommandBuffer<EntityStore> cb,
                          LevelUpEvent event) {
        HeroCoreStatsComponent stats = chunk.getComponent(index, HeroCoreStatsComponent.getComponentType());
        stats.setStrength(stats.getStrength() + 1f);
        stats.setVitality(stats.getVitality() + 2f);
    }
});

2) Primary Attributes and Secondary Stats

• Primary attributes live in HeroCoreStatsComponent (STR/DEX/INT/FAITH/VIT/RES).
• Secondary stats are derived and written into EntityStatMap by AttributeDerivationSystem every tick.
• Derived values are computed by AttributeDerivationFormulas and applied as StaticModifier entries.

If you modify primary attributes, do not recalculate secondary stats manually. The next tick will update the modifiers:

HeroCoreStatsComponent stats = store.getComponent(ref, HeroCoreStatsComponent.getComponentType());
stats.setDexterity(stats.getDexterity() + 5f);

Reading secondary stats always goes through EntityStatMap:

EntityStatMap statMap = store.getComponent(ref, EntityStatsModule.get().getEntityStatMapComponentType());
int critIdx = HeroCoreStatTypes.getCritChance();
float critChance = statMap.get(critIdx).get();

3) Equipment, Inventory, and Item Events

HeroCore does not implement inventory or equipment events directly. Use Hytale's inventory or equipment events (or your own mod's item system) and translate those into stat modifiers.

Recommended pattern:

1. Listen for item equip/unequip or inventory change events (outside HeroCore).
2. Apply or remove modifiers using HeroCoreModifiers.gear() keys.
3. Store any equipped state in your own component if needed, not in HeroCore.

// Example: apply a chestplate armor bonus
String key = HeroCoreModifiers.gear("chestplate_iron", "armor");
int armorIdx = HeroCoreStatTypes.getPhysicalResistance();
statMap.putModifier(armorIdx, key,
    new StaticModifier(Modifier.ModifierTarget.MAX, StaticModifier.CalculationType.ADDITIVE, 12f));

// Remove on unequip
statMap.removeModifier(armorIdx, key);

If your project already has an inventory event layer, this is the bridge point to convert items into stat effects.

---

Downstream Integration Guide

Dependency Declaration

In your downstream plugin's manifest.json:

{
    "Dependencies": {
        "Herotale:Herocore": "*"
    }
}

Reading Stats

All stats live in EntityStatMap. HeroCore provides stat index resolvers:

// Read a HeroCore-defined stat from an entity
EntityStatMap stats = store.getComponent(ref, EntityStatsModule.get().getEntityStatMapComponentType());
int critIdx = HeroCoreStatTypes.getCritChance();
float critChance = stats.get(critIdx).get(); // 0.0–1.0

// Read a native Hytale stat
int healthIdx = DefaultEntityStatTypes.getHealth();
float health = stats.get(healthIdx).get();

// Convenience helper
float value = HeroCoreStatTypes.getStatValue(ref, HeroCoreStatTypes.getSpellPower());

Intercepting the Damage Pipeline

Register an EntityEventSystem with SystemDependency to insert your logic between existing stages:

@Override
protected void setup() {
    var reg = getEntityStoreRegistry();

    reg.registerSystem(new EntityEventSystem<EntityStore, HeroCoreDamageEvent>(HeroCoreDamageEvent.class) {
        @Override
        public Query<EntityStore> getQuery() {
            // Return a query that matches entities with HeroCoreStatsComponent
            return HeroCoreStatsComponent.getComponentType();
        }

        @Override
        public Set<Dependency<EntityStore>> getDependencies() {
            return Set.of(
                new SystemDependency<>(Order.AFTER,  CriticalHitSystem.class),
                new SystemDependency<>(Order.BEFORE, LifestealSystem.class)
            );
        }

        @Override
        protected void handle(int index, ArchetypeChunk<EntityStore> chunk,
                              Store<EntityStore> store, CommandBuffer<EntityStore> cb,
                              HeroCoreDamageEvent event) {
            if (event.isCancelled()) return;
            // Your custom damage modification logic here
            // e.g., class-specific damage bonuses, elemental interactions
        }
    });
}

Reacting to Level-Ups

reg.registerSystem(new EntityEventSystem<EntityStore, LevelUpEvent>(LevelUpEvent.class) {
    @Override
    public Query<EntityStore> getQuery() {
        return HeroCoreStatsComponent.getComponentType();
    }

    @Override
    protected void handle(int index, ArchetypeChunk<EntityStore> chunk,
                          Store<EntityStore> store, CommandBuffer<EntityStore> cb,
                          LevelUpEvent event) {
        HeroCoreStatsComponent rpg = chunk.getComponent(index, HeroCoreStatsComponent.getComponentType());
        // Scale attributes on level-up — derivation system picks up changes next tick
        rpg.setVitality(20f + event.getNewLevel() * 2f);
        rpg.setStrength(15f + event.getNewLevel() * 1.5f);
    }
});

Reacting to Combat Exit

reg.registerSystem(new EntityEventSystem<EntityStore, CombatExitEvent>(CombatExitEvent.class) {
    @Override
    public Query<EntityStore> getQuery() {
        // Match entities with CombatStateComponent
        return CombatStateComponent.getComponentType();
    }

    @Override
    protected void handle(int index, ArchetypeChunk<EntityStore> chunk,
                          Store<EntityStore> store, CommandBuffer<EntityStore> cb,
                          CombatExitEvent event) {
        // Entity left combat — trigger out-of-combat effects, UI changes, etc.
    }
});

Modifying Primary Attributes

Write directly to HeroCoreStatsComponent. The AttributeDerivationSystem automatically recalculates derived modifiers on the next tick:

HeroCoreStatsComponent stats = store.getComponent(ref, HeroCoreStatsComponent.getComponentType());
stats.setStrength(stats.getStrength() + 5f);
// Next tick: AttributeDerivationSystem writes updated modifiers into EntityStatMap

Writing Custom Modifiers

Use HeroCoreModifiers key conventions for namespace safety:

EntityStatMap statMap = store.getComponent(ref, EntityStatsModule.get().getEntityStatMapComponentType());
int critIdx = HeroCoreStatTypes.getCritChance();

// Apply a modifier (namespace with your plugin prefix)
// Hytale API: putModifier(int statIndex, String key, Modifier modifier)
statMap.putModifier(critIdx, "myplugin:elixir_crit_boost",
    new StaticModifier(Modifier.ModifierTarget.MAX, StaticModifier.CalculationType.ADDITIVE, 0.1f));

// Remove it later
// Hytale API: removeModifier(int statIndex, String key)
statMap.removeModifier(critIdx, "myplugin:elixir_crit_boost");

Note on putModifier argument order: The Hytale compiled API signature is putModifier(int statIndex, String key, Modifier modifier) — stat index first, then key string, verified from the decompiled EntityStatMap.java. This matches removeModifier(int statIndex, String key). Note that some documentation (including the refactor guide) shows the arguments in a different order (String key, int index, ...) — that order is incorrect per the actual bytecode. All HeroCore code uses the verified (int, String, Modifier) order.

Granting XP

// Inside an ECS system (has access to Ref, Store, CommandBuffer):
LevelingRegistry leveling = HeroCore.get().getLevelingRegistry();
leveling.grantXP(entityRef, store, cb, "combat", 100.0, XPSource.KILL);

Using Mob Profiles

MobRegistry mobs = HeroCore.get().getMobRegistry();
mobs.registerProfile(myBossProfile);
Optional<MobProfile> profile = mobs.getProfile("skeleton_warrior");

Using Zone Modifiers (v0.3 planned)

⚠️ Not yet implemented. ZoneModifierRegistry with ZoneTrigger.REGION_ENTRY is a planned v0.3 feature. The API surface exists but zone trigger integration with Hytale's world system is not wired. Do not use this API in production code — it will compile but have no runtime effect. See Planned Features for details.

---

Planned Features

These APIs exist as interface/class definitions but are not yet wired to Hytale's runtime. They are reserved for future versions.

Zone Modifier System (v0.3)

ZoneModifierRegistry will allow applying attribute modifiers when entities enter or leave world zones. The registry interface and ZoneModifierDefinition builder are defined but zone boundary detection via Hytale's world system is not yet integrated.

// Future usage (v0.3):
ZoneModifierRegistry zones = HeroCore.get().getZoneModifierRegistry();
zones.register(ZoneModifierDefinition.builder()
    .zoneId("dungeon_fire")
    .trigger(ZoneTrigger.REGION_ENTRY)
    .modifier(new AttributeModifier(RPGAttribute.FIRE_RESISTANCE, -0.2))
    .build());

HeroCoreReadyEvent

HeroCoreReadyEvent is defined as a lifecycle signal for downstream plugins that treat HeroCore as an optional dependency. Currently, this event is not dispatched — it exists as a reserved API surface.

For plugins that declare HeroCore as a required dependency in manifest.json, standard load ordering is sufficient: HeroCore's setup() and start() will complete before your plugin's setup() runs. You do not need this event.

This event will be wired in a future version for optional-dependency use cases where a plugin needs to detect HeroCore availability at runtime.

---

API Reference

Key Classes by Package

net.herotale.herocore.api

Class	Description
HeroCore	Service locator — HeroCore.get() for registries

net.herotale.herocore.api.attribute

Class	Description
RPGAttribute	Enum of all 62 RPG attributes
AttributeModifier	Record: attribute + value + label

net.herotale.herocore.api.component

Class	Description
HeroCoreStatsComponent	Primary attribute bases (persistent)
HeroCoreProgressionComponent	Level and XP (persistent)
CombatStateComponent	In-combat tracking (transient)
StatusEffectIndexComponent	Active effect index (transient)

net.herotale.herocore.api.damage

Class	Description
HeroCoreDamageEvent	CancellableEcsEvent — damage pipeline event
DamageType	Enum: PHYSICAL, MAGICAL, FIRE, ICE, LIGHTNING, POISON, ARCANE, TRUE, FALL, VOID
DamageFlag	Enum: CRIT, DOT, AOE, MELEE, RANGED, SPELL, etc.

net.herotale.herocore.api.heal

Class	Description
HeroCoreHealEvent	CancellableEcsEvent — heal pipeline event
HealType	Enum: SPELL, POTION, REGEN_TICK, PASSIVE, ENVIRONMENTAL

net.herotale.herocore.api.entity

Class	Description
MobRegistry	Registry for mob/NPC profiles — registerProfile(), getProfile()
MobProfile	Interface: mob identity, base level, base attributes, optional scaling profile
MobScalingProfile	Interface: per-level stat scaling rules
MobCategory	Enum: mob classification (used by profiles)

net.herotale.herocore.api.event

Class	Description
LevelUpEvent	EcsEvent — dispatched on level gain (via grantXP())
LevelDownEvent	EcsEvent — dispatched on level loss (via setXP() when new level < old)
CombatExitEvent	EcsEvent — dispatched when combat timeout expires
HeroCoreReadyEvent	Lifecycle signal — not yet dispatched (reserved for v0.3 optional-dependency support; see Planned Features)
AttributeChangeEvent	Server event — attribute value changed (reserved — defined but not yet dispatched)
StatusChangeEvent	Server event — status effect applied/removed (reserved — defined but not yet dispatched)
MobSpawnEvent	Server event — mob spawned with profile (reserved)
MobDeathEvent	Server event — mob died (reserved)
ProgressionEvent	Server event — progression milestone (reserved)
MorphEvent	Server event — entity morph change (reserved)
ResourceChangeEvent	Server event — resource pool changed (reserved)
CraftingEvent	Server event — crafting action (reserved)

net.herotale.herocore.impl

Class	Description
HeroCorePlugin	Main plugin class — singleton via HeroCorePlugin.get()
HeroCoreComponentRegistry	Registers all 4 components, exposes ComponentType handles
HeroCoreStatTypes	Resolves custom stat indices from JSON assets
HeroCoreModifiers	Modifier key string constants (HC_ prefix)

net.herotale.herocore.system.damage

Class	Pipeline Position	Description
AttackDamageBonusSystem	1st	Scales damage by attacker's attack damage
FallDamageReductionSystem	2nd	Reduces fall damage (only for DamageType.FALL). HeroCore addition — declares AFTER AttackDamageBonusSystem.
ResistanceMitigationSystem	3rd	Applies resistance per damage type
CriticalHitSystem	4th	Rolls and applies crits
LifestealSystem	5th	Heals attacker for % of damage
MinimumDamageSystem	6th	Enforces minimum damage floor
DamageApplicationSystem	7th (final)	Writes damage to EntityStatMap

net.herotale.herocore.system.heal

Class	Pipeline Position	Description
HealingPowerScalingSystem	1st	Scales healing by healing power
HealingReceivedBonusSystem	2nd	Applies healing received bonus
HealCritSystem	3rd	Rolls and applies heal crits

net.herotale.herocore.system.combat

Class	Description
CombatTimeoutSystem	DelayedEntitySystem — exits combat after timeout
StatusEffectTickSystem	DelayedEntitySystem — decrements effect timers (every 0.25s), removes expired effects and their tracked modifiers

---

Building

# Build and run all tests
./gradlew clean build

# Tests only
./gradlew test

Requirements:

• JDK 25
• Gradle 9.2.0 (wrapper included)
• Hytale Server API 2026.02.17+ (resolved from maven.hytale.com)

Test Suites (62 tests total):

• AttributeDerivationFormulasTest — 13 tests covering all derivation formulas
• DamageFormulasTest — 21 tests covering resistance, crit, lifesteal, min damage
• HealFormulasTest — 14 tests covering heal scaling, heal crit
• XpCurveTest — 14 tests covering exponential, linear, discrete XP curves

All math tests are pure-function tests that require no server instance.

---

Compliance Notes

• No bridge pattern — EntityStatMap is the single source of truth
• No parallel stat engine — HeroCoreStatsComponent holds only primary bases
• No custom event bus — all events use CancellableEcsEvent / EcsEvent via CommandBuffer.invoke()
• No custom system ordering — SystemDependency with Order.BEFORE / Order.AFTER
• No ScheduledExecutorService — tick systems use DelayedEntitySystem and EntityTickingSystem
• No standalone Gson persistence — BuilderCodec with HC_-prefixed keys
• No custom system abstraction — all systems extend native Hytale types directly
• Ref<EntityStore> in all runtime logic — UUID only at persistence boundaries