Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hrtk.frotty27.com/llms.txt

Use this file to discover all available pages before exploring further.

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 entity system, world state, events, or commands. You end up faking everything, and your fakes drift from reality. HRTK is different. Your tests run inside the live server as a plugin. They interact with real entities, real events, and real commands. When you deal damage in a test, Hytale’s actual damage system runs. When you spawn an entity, it exists in a real world.

26 Annotations

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

28 Assert Classes

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

38 Example Tests

Comprehensive example mod with 38 test suites covering ECS, events, effects, combat, permissions, projectiles, game modes, and more

​
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, overlap behavior, stat modifiers active, invulnerability
PermissionsPermission checks, user/group add/remove, built-in permission constants
ProjectilesProjectile module available, config assets, physics properties
Game ModesGameMode enum, GameModeType asset lookup, mode change events
Death/RespawnDeathComponent inspection, item loss config, damage pipeline
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.spawnNPC("Trork_Warrior", 0, 65, 0);
        ctx.flush();

        var statMap = (EntityStatMap) ctx.getComponent(ref, EntityStatMap.getComponentType());
        int healthStat = DefaultEntityStatTypes.getHealth();
        statMap.subtractStatValue(healthStat, 9999.0f);
        ctx.flush();
        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