System Overview
This page defines the target architecture. It does not claim that the current runtime already implements every layer.
Hexis is a layered automation framework. The boundary is based on behavioral ownership, not on making Java microscopic and Lua enormous.
Layer responsibilities
| Layer | Owns |
|---|---|
| Lua | Goals, policy, choices, composition, configuration, reusable workflows |
| Contract layer | Stable types, validation, permissions, actions, observations, results |
| Java/native engine | Time-sensitive coordination, performance, cleanup, valuable behavior quality |
| Server packs | Server-specific facts, selectors, routes, workflows, and capability declarations |
| Minecraft boundary | Main-thread game access through supported client APIs |
The Java job/action catalog is the reusable “jobbook”: coarse enough to own a complete high-quality mechanism, but composable enough that Lua still determines the overall plan.
Data flow
Lua submits an immutable request. The contract layer validates it and returns an action handle. Java schedules the action, acquires the resources it controls, and emits typed progress. Lua can wait, cancel, or react. Completion returns a stable result instead of requiring scripts to poll several unrelated flags.
Observations are snapshots or event payloads. Lua must not hold live Java game objects across ticks.
Domains the architecture must cover
The same model applies to navigation, mining, combat, camera, raw interaction, inventory, entities, blocks, HUD/config, events, cancellation, concurrency, and world lifecycle. Navigation is first because it is the most mature mechanism, not because the architecture is navigation-specific.
Design constraints
- Core contracts are server-agnostic.
- Proprietary behavior quality stays in protected code.
- Raw control remains possible without bypassing safety or lifecycle rules.
- One mechanism has one obvious contract and one result model.
- AI-visible descriptions and examples are part of the API quality bar.
- Cleanup is enforced by engine-owned resource leases, not script discipline.