Java–Lua Boundary
The core rule is:
Lua says what outcome to pursue and how outcomes compose. Java/native code owns reusable mechanisms whose correctness or quality depends on ticks, performance, cleanup, game internals, or proprietary algorithms.
This is not a rule that every loop belongs in Java. It is a rule that every valuable reusable mechanism has one responsible owner.
Capability map
| Domain | Lua policy | Java/native mechanism | Server pack knowledge |
|---|---|---|---|
| Navigation | destination, constraints, fallback policy | topology, pathfinding, movement, recovery | named places, teleports, server rules |
| Mining | targets, zone, tool policy, stop/sell rules | scan, vantage selection, aim, break timing, retries | resource IDs, regions, routes |
| Combat | target policy, risk limits, loadout goals | target tracking, aim, attack cadence, pursuit | mob identity and encounter rules |
| Camera | desired subject/style constraints | interpolation, occlusion, stabilization | optional server-specific limits |
| Inventory | desired item/loadout, disposal policy | slot transactions, GUI synchronization | menu layouts and item semantics |
| World | query intent and filters | snapshots, spatial indexes, ray tests | semantic regions and aliases |
| HUD/config | fields and presentation choices | rendering, persistence, validation | pack defaults and labels |
| Events | subscriptions and reactions | delivery, buffering, backpressure | semantic event interpretation |
| Raw interaction | explicit low-level sequence | safe inputs, ray use, timing, cleanup | optional selectors |
Decision test
A behavior belongs in the engine when one or more are true:
- it must coordinate on client ticks;
- it owns movement, camera, attack, use, or inventory resources;
- it is performance-sensitive or requires precomputation;
- partial failure could leave input or state stuck;
- quality depends on Hexis algorithms or tuning;
- many scripts would otherwise duplicate it;
- exposing the implementation would reveal valuable Hexis IP.
A behavior belongs in Lua when it selects between capabilities, defines user policy, combines results, configures a workflow, or expresses a server/user goal.
Server-specific facts belong in a pack unless the engine requires them to perform a universal Minecraft mechanism.
The abstraction ladder
Hexis should offer a small ladder rather than one forced abstraction level:
- Goal actions — complete reusable jobs such as harvest in a zone.
- Domain actions — navigate, mine a selected block set, manage a loadout.
- Raw actions — look, press, use, attack, select a slot, raycast.
High-level actions may compose lower-level engine mechanisms internally. Lua may drop down a level for custom behavior, but doing so is an explicit choice with more responsibility and more permissions.
Example: mining
Lua should be able to express:
local job = hexis.mining.harvest({
region = pack.regions.galatea_grove,
target = pack.resources.fig_logs,
policy = {
avoid_players_within = 8,
stop_when_inventory_full = true,
},
})
local result = hexis.await(job)
The engine—not this script—should own connected-block discovery, scan caching, vantage-point choice, navigation, camera alignment, ray verification, break timing, retry classification, and release of held inputs.
The same script can still implement a custom mining sequence with
hexis.raw, but raw should not be the default generated by an
AI for a standard job.
Boundary failure modes
- Too much Lua: giant state machines, manual polling, duplicated cleanup, hard-to-debug timing, and leaked behavior IP.
- Too little Lua: a hard-coded bot where users cannot express new policy.
- Too much server logic in core: every server update forces engine changes.
- Unsafe raw access: scripts can bypass permissions, the client thread, or cleanup.
The target contract is successful only when production scripts become smaller without becoming less capable or less trustworthy.