Strata 0.2.0

These notes describe the changes since 0.1.6. They cover the common UI API, reactive state, Paper/Folia and Velocity integration, browser rendering, Minecraft compatibility, and extension contracts. Rebuild consuming Mods and plugins for the callback API changes, and keep all installed Strata artifacts on the same release.

Common UI definitions, screens, and HUDs

UiDefinition describes content and presentation together and returns a UiSession when opened. Use definition.open() on the client or the Paper extension definition.open(plugin, player) on the server. Screen is the default presentation; HUD is selected on the definition. The optional title is used for narration and is not drawn automatically.

The session can switch between Screen and HUD while retaining its content, input values, and scroll position, or close itself from an event handler. onXxx callbacks receive the owning session as their receiver, so close() and switch(...) address the UI delivering that event. Applied presentation and typed lifecycle status are available on the handle; remote presentation changes become visible there after client acknowledgement.

Multiple HUDs can coexist with an ordinary screen. Namespaced categories and visibility rules control whether each HUD remains visible, temporarily hides, or closes when another screen opens. HUDs follow F1 visibility and support explicit interaction without a new default keybinding. Input policies separately allow movement, camera control, and other game actions while a UI is open; forwarded keys are released at input and ownership boundaries.

See screens and state for presentation, visibility, input, and lifetime contracts.

Reactive application and component state

mutableStateOf, MutableState, and read-only State add application-owned reactive values. Reading a value during content evaluation tracks that dependency; changing it schedules reevaluation, while equal assignments skip invalidation. Dependencies follow the reads made by the latest evaluation and are released when the UI closes.

Existing component values participate in the same tracking, including checkbox, slider, cycle-button, and text-editor values. For example, a label that reads TextFieldState.value can update when the editor changes without a separate copied value. State remains owned by its creating execution context and must be created outside content that can reevaluate. Writes during declaration evaluation are rejected.

The existing StateSource inputs, mapped sources, and Observe regions remain available for external data and narrower update boundaries. Compatible keyed content retains its nodes and editing state across reevaluation.

Server-owned Paper, Folia, and Velocity UIs

The new Paper and Velocity runtimes let plugins define UIs and execute their handlers on the server or proxy, with native rendering on a matching Strata Fabric client. Paper uses the primary server thread; Folia follows each player through its entity scheduler and preserves a logical execution owner across region migrations. Create Folia state in PaperUi.open(ownerPlugin, player) { ... } and enter PaperUi.execute(player) { ... } for later state or session access from the player's region. Velocity creates state and runs callbacks on its dedicated UI thread through an asynchronous opening API. The service negotiates supported declarations, sends retained updates, and keeps sessions isolated by player and owning plugin. Plugin disable and player disconnection release associated handlers, observations, and pending transfers. Screen and HUD sessions use the same definition and control API.

Remote components include editable form bindings, server-owned virtual-list rows, CPU Canvas snapshots, ready image tiles, and native inventory Slots. Client edits and server replacements are ordered so older acknowledgements do not overwrite newer input. Slot transactions use Minecraft's existing container handling, and container-bound HUDs close when their container changes. Synchronous input-consumption decisions and custom native rendering require client-side implementations.

Install the appropriate platform plugin artifact and the matching client runtime; vanilla clients cannot display these UIs. Proxy-owned and backend-owned sessions have independent negotiation and authenticated routing, and can coexist as one foreground Screen plus multiple HUDs. The public Fabric runtime does not require Fabric API. The Paper plugin also supports Folia; consuming plugins must declare folia-supported: true and obey native region ownership. Ordinary movement, including riding a minecart, keeps UIs open; teleportation that replaces a native container retires its bound UI. Velocity does not create native inventories or translate Minecraft protocol versions. Remote peers use protocol version 1 and require matching Strata builds on both ends. See Velocity setup and examples, Paper setup and examples and the exact-version compatibility matrix.

Platform APIs and lifecycle events

strata-paper-api and strata-velocity-api separate application-facing opening methods and event types from runtime implementation modules. Consumers compile against the corresponding API and depend on the installed Strata plugin without bundling it. PaperUi provides capabilities, owner-scoped factories and state access, and registration; VelocityUi provides owner-thread factories, queued work, and asynchronous capabilities.

Both platforms publish client-ready and connection-ended notifications, plus UI-opened, presentation-changed, and UI-closed events. Opening and presentation notifications follow client application acknowledgement, and terminal events include the reason and last applied presentation. Paper and Folia events use Bukkit listeners; Velocity listeners read event snapshots and queue live session operations through VelocityUi.execute. See the event contract for ordering, failure, and threading details.

Kotlin/JavaScript and browser rendering

The platform-neutral API and retained core now target both JVM and JavaScript, allowing shared definitions and state logic across runtimes. Existing JVM artifact coordinates remain available. Portable profile identifiers use Uuid and parseUuid; the JVM identifier remains java.util.UUID.

The new Web runtime mounts retained layouts, text, buttons, and native progress elements into a browser DOM. Keyed updates preserve compatible DOM elements, and unchanged text measurements are reused. renderWebHtml produces initial content, while renderWebDocument produces a complete initial document with a deferred application script. Mounting a matching definition adopts that initial DOM; inconsistent initial content is rejected. WebTheme.Native and WebTheme.Minecraft select native browser styling or an original Minecraft-inspired CSS theme without requiring game assets; build rendering and mounting must use the same theme.

Web support is a subset of Minecraft capabilities: unavailable components, HUD presentation, and game-input controls fail explicitly. Browser demos cover reactive counters, keyed lists, and progress, and are included with the generated API documentation. See the Web examples for compiled applications and initial-document generation.

Custom declarations and remote extensions

Elements and modifiers can optionally expose typed declaration projections. The projection SPI represents immutable properties, action endpoints, state bindings, and resource snapshots without transmitting application objects or executable code. Typed input subscriptions add declared keyboard/button filters and propagation behavior with server-side event notifications, including capture and cancellation. Event-dependent synchronous consumption remains a client responsibility. Custom remote types must be registered on both endpoints with matching namespaced schema identities. Unsupported types are rejected during admission rather than silently omitted.

Local custom components continue to work without projection registration. For remote extensions, follow the declaration projection contract and the compiled Paper/client extension examples.

Minecraft compatibility and examples

Minecraft 26.3 gains its own Fabric runtime, native input and rendering integration, and distribution metadata. Minecraft 1.20 remains the supported floor; select the exact versioned runtime and its required Java version from the compatibility matrix. Loaded-client development and packaged-JAR checks remain distinct from exact-version Paper and Velocity server acceptance.

Documentation adds an animated player-list walkthrough with compiled source and still frames, interactive browser demos alongside Dokka, platform setup guides, and extension contracts.

Upgrading from 0.1.6

• Replace ScreenDefinition and Screens.open(...) with UiDefinition and definition.open() for new code. The deprecated entries delegate to the common path.
• Rebuild consumers after the event callback receiver change. Wrap stored callbacks or bound method references when necessary, for example onActivate { handler() }; event arguments and return values are unchanged.
• Close an unused definition with definition.close() and an opened UI with session.close(). Create a fresh definition for each opening.
• Keep editing and navigation state outside reevaluated content, and perform state changes in handlers or owner-confined application work.
• For Paper or Velocity, compile against the platform API, declare the Strata plugin dependency, supply the owning plugin when opening a UI, and install the matching client runtime.
• In shared JVM/JavaScript code, use Uuid and parseUuid; JVM APIs continue to use java.util.UUID.
• Read live UiSession properties inside their execution owner. Use PaperUi.execute from the player's Folia region; Velocity platform events supply snapshots for listeners running elsewhere.
• A logical execution owner identifies serialized UI access; it does not grant permission to access native player or world state, or propagate automatically into asynchronous continuations.