What the build writes
A compiled screen reaches the client as JSON UI in the addon's resource pack: screen definitions, an addon-owned router mounted on the vanilla screen, and for a container screen, a stamp on the entity or block that opens it.
Roots and mounts
The root names the host: <Screen> for an action form, <Form> for a native modal, <Container> for an entity or block container screen, and <Experimental_OreUI> for an experimental player-owned Ore presentation. The file naming convention and component set are shared.
The JSON UI hosts emit the documents described below. The experimental Ore host emits pack-local layouts and client resources under hbui/.
| Root | Screen | Where the layout is mounted | Opened with |
|---|---|---|---|
<Screen> | an action form | the library's own container on the form screen | render(Screen, player) |
<Form> | a native modal form | the same container, with the engine's fields in place | render(Form, player) |
<Container entity> | a custom entity's container screen | the vanilla chest, through a hook and the addon's router | createContainerScreen(Container) |
<Container block> | a custom block's container screen | the vanilla data-driven container, through a second hook and the same router | createContainerScreen(Container) |
A tree that starts with anything else — or a <Container> naming neither entity nor block, or both — is refused by the list of roots. Hosts covers what each screen can carry.
Routing
Each addon owns its screen definitions and router. The router selects a screen by its complete routing key, and a hook mounts the router on the native host.
- Form screens use one title dictionary and one optional embed dictionary per addon. A lookup supplies the selected cell id to a factory, which creates only that screen, its backdrop, and its cursor. The title carries the protocol header and the screen's namespaced name; the embed marker comes from the host's first button entry. Adding routes increases the dictionaries and shipped definitions without adding live selectors. A resident guide keeps its pages inside the selected screen so local navigation remains available.
- Container screens gate on a layout key. A marker item in the container's first slot carries a protocol key — is this container a compiled screen at all? — as its max durability, and the layout key as its current durability, and the router shows the layout whose key matches. An entity-hosted screen inserts the addon's root into
RP/ui/chest_screen.json, at vanilla'schest.small_chest_panel_top_half; a block-hosted screen inserts the same root intoRP/ui/data_driven_container_screen.json, atdata_driven_container.panel_top_half. A vanilla chest or data-driven container has no marker, fails the first check and renders untouched.
A screen's layout key is a hash of <namespace>_<name> folded into 1..3969. It depends on nothing but the screen's own name, so a rebuild never moves a key and an entity placed in a world keeps opening the screen it was stamped with; two addons built apart never claim the same key for their first screens. Two screens of one addon hashing alike is a build failure naming both.
The form hook in RP/ui/server_form.json appends an addon-owned factory bridge to main_screen_content and preserves the original native form factory. The bridge uses the native server_form_factory event for both long_form and custom_form, so routing controls join the form's binding initialization. The mount fills the viewport so screen cells inherit usable dimensions. All addon builds share the same viewport and vanilla fallback rules. Ordinary form titles keep the native layout. Each addon's selectors, cells, and widget dependencies live in its own namespace and files.
Collection and view bindings in form cells use binding_condition: "always" by default so values arriving after cell construction populate the controls and update their visibility. Explicit binding conditions are preserved. Factories limit live construction; every screen definition still ships in the resource pack.
Container hooks use additive modifications at vanilla's own path. Their insert targets declare their own controls, because inserting into a definition that only inherits the array would create an array that shadows the inherited one.
Host definitions
A container screen names the entity or the block it opens from. The stage finds that host's definition under BP/entities or BP/blocks by its identifier — a screen naming a host that is not there fails the build — and stamps the workspace copy.
An entity (<Container entity={'core:furnace'}>)
"description": {
"properties": {
// The runtime reads this when a player opens the entity, to pick the screen.
"core:ui_layout": { "type": "int", "range": [0, 3969], "default": 1094 }
}
},
"components": {
"minecraft:inventory": {
"container_type": "container", // the only type that routes to the chest screen
"inventory_size": 75, // drawn slots + live channels; a hand-written value is overwritten
"private": false // `true` stops the player opening it at all
}
}
A block (<Container block={'core:workbench'}>)
"description": {
"states": {
// A string, not a number: the engine stores an integer state by its value in the block's
// state bits, and a layout key does not fit them. The key is the default; `none` is there
// because a one-value state needs zero bits, which the engine logs as out of range.
"core:ui_layout": ["1094", "none"]
}
},
"components": {
"minecraft:block_entity": {
"container": { "slot_count": 35 }, // drawn slots + live channels, 1..54
"dynamic_properties": true // where the screen's state is kept
}
}
minecraft:block_entity cannot vary per permutation and cannot be combined with minecraft:crafting_table — the stage refuses a block that declares one, since a compiled screen needs the block entity for its own container. A block container holds 54 slots at most, the whole of a screen's allocation: the routing sentinel, every <Slot> and Button, and one bank slot for each detected dynamic Text. A screen that outgrows it either sheds cells or moves to an entity, whose inventory has no cap.
Nobody keeps a container size or a layout key in step with a layout by hand — the failure mode of that is a screen that silently draws cells the container does not have, or a host that opens the wrong screen. Everything else on the entity or block is yours: its geometry, its behavior, whether it can be pushed or hurt.
One host opens one screen: two screens naming the same entity, or the same block, is a build error.
Text composed per language
Some text takes its shape from what it says: a baked breadcrumb trail collapses to its room, a <Trans> breaks into lines. The stage builds every screen with the strings of each language RP/texts/languages.json lists, as the filters before it left them, so the build composes that text once per language.
What the screens composed is written into each RP/texts/<locale>.lang, in a marked block, under keys named after what the text says in every language. Two screens composing the same text share one key. A screen that is not static also carries each <Trans> as laid out, in the snapshot it is registered with, so a render at runtime draws the same pieces and emits a press among them in the same place.
Live container text
Each detected live label uses one occupied bank slot. Runtime writes the complete host-resolved string into that item's custom name, and the compiled label reads it while the container stays open. Values carry at most 128 UTF-16 code units without splitting a surrogate pair. maxLength can shorten literal text further; static text remains baked and consumes no text slot. See Dynamic text.
Next steps
- Faces and hosts — the passes that produce each screen document
- Build checks — everything that stops a build, and what fails it
- Container screens — serving a screen an entity or a block owns