Skip to main content
HRTK stands for Hytale Runtime Testing Kit - a testing framework that runs inside the Hytale server, giving your tests access to real game state.

​
Why HRTK?

Traditional test frameworks like JUnit run outside the game. They can’t access Hytale’s ECS stores, world state, event system, or command pipeline. You end up mocking everything, and your mocks drift from reality. HRTK is different. Your tests run inside the live server as a plugin. They interact with real Store<EntityStore>, real EventRegistry, real CommandManager. When you deal damage in a test, Hytale’s actual DamageSystems.executeDamage() runs. When you spawn an entity, it exists in a real world.

24 Annotations

JUnit-familiar annotations like @HytaleTest, @BeforeEach, @Tag, @Timeout - plus Hytale-specific ones like @EcsTest, @WorldTest, @FlowTest, @Benchmark

12 Assert Classes

Domain-specific assertions: EcsAssert, StatsAssert, CombatAssert, InventoryAssert, LootAssert, EffectAssert, EventAssert, CommandAssert, and more

9 Test Adapters

Server-side adapters that wrap Hytale internals: deal damage, read stats, apply effects, check inventory, roll loot tables, capture events

​
Who is this for?

Mod Developers

Write tests alongside your mod code. Verify components persist, codecs round-trip, commands work, damage calculates correctly. Tests ship in your JAR and run when HRTK is installed.

Server Operators

Install HRTK on your dev server. Run /hrtk run to execute all mod tests. Verify mods work correctly before deploying to production.
Players never see or interact with HRTK. It’s server-side only.

​
What can you test?

Everything a mod touches:
SurfaceWhat you can verify
ECSComponents persist, archetypes match, entity queries return correctly
StatsHealth/stamina/mana values, stat modifiers, alive/dead state
CombatDamage reduces health, lethal damage causes death, knockback applies
EventsEvents fire with correct data, cancellation works, priority ordering
CommandsCommands execute, output is correct, permissions enforced
CodecsSerialization round-trips, malformed data rejected
InventoryItems added/removed, slots contain expected stacks
LootDrop lists contain expected items, drops spawn after kills
EffectsEffects apply/expire, stat modifiers active, invulnerability works
WorldEntities spawn at positions, chunks load, worlds create/destroy
UIPages build correct commands, event bindings registered
PerformanceBenchmark with warmup/iteration control via TimeRecorder

​
Quick Example

@HytaleSuite("My Mod Tests")
public class MyModTests {

    @HytaleTest("Addition works")
    void testMath() {
        HytaleAssert.assertEquals(4, 2 + 2);
    }

    @EcsTest
    void testComponentPersists(EcsTestContext ctx) {
        var entity = ctx.createEntity();
        ctx.putComponent(entity, MyComponent.TYPE, new MyComponent("hello"));
        ctx.flush();
        EcsAssert.assertHasComponent(ctx.getStore(), entity, MyComponent.TYPE);
    }

    @FlowTest(timeoutTicks = 200)
    void testKillFlow(WorldTestContext ctx) {
        var ref = ctx.spawnEntity("Skeleton", 0, 65, 0);
        ctx.waitTicks(3);
        CombatTestAdapter.dealLethalDamage(ref, ctx.getStore());
        ctx.waitTicks(5);
        StatsAssert.assertDead(ctx.getStore(), ref);
    }
}
1

Add dependency

Add HRTK-API.jar as compileOnly in your build.gradle
2

Write tests

Annotate test methods with @HytaleTest and use assert classes
3

Install plugin

Drop HRTK.jar in your server’s mods folder
4

Run

/hrtk run in the server console or in-game

Get started

Write your first test in 5 minutes