Skip to content
schphePublic

About

tsx to json ui compiler

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

jui

A SolidJS-style, Tailwind-flavoured TSX → Minecraft Bedrock UI compiler.

Write components with signals and utility classes; jui compiles them — at build time — into a complete, installable Bedrock resource pack: the JSON-UI documents and every texture they reference. No runtime ships to the game.


What it is

jui is three things behind one pipeline:

  1. A compiler — TSX → HIR → MIR → JSON-UI. Components run once at build to construct a tree; reactivity compiles to engine-native bindings, control flow to factories / grids / visibility.
  2. An asset baker — any styled box (bg-slate-800 border-2 rounded) or declared source (vector, procedural, 3D, image, particles, composites) is rendered and emitted as a deduplicated, quantized, optimized PNG — through one registry, with a persistent content-hash cache.
  3. A devtools suite — a native application with a vanilla-accurate, animated, interactive preview, plus an inspector, effect/asset labs, a state + server simulator, a timeline, and source-mapped diagnostics.

It is written in Rust, with a small embedded TypeScript authoring layer (the only place JavaScript runs — user TSX, executed once in a quarantined V8 isolate to emit the UI tree).

The core principle: everything is a bakeable source; everything reactive compiles to a binding; the preview is the truth; and authoring reads like signals + components.

Because Bedrock offers no headless screenshot and no programmatic reload, the preview is not a convenience — it is the only ground truth during iteration, so it composites jui's output into the real vanilla screens using a real Bedrock pack's textures, fonts, and UI docs.


A taste

import { channels, Col, defineScreen, For, Overlay, Row, Text } from "jui";
import { Tabs } from "jui/ui";

const coins = channels.hudTitle.number("coins:");   // live server value, parsed from the title

defineScreen({
  name: "shop",
  root: () => (
    <Overlay class="w-full h-full">
      <Col class="w-72 anchor-center bg-slate-800 border-2 border-slate-600 rounded p-3 gap-2">
        <Row class="justify-between items-center">
          <Text class="text-white text-lg">Mythic Emporium</Text>
          <Text class="text-amber-300" bind={coins} />
        </Row>

        {/* Tabs own their selection as client-side `local()` state — no server round-trip. */}
        <Tabs
          default="buy"
          tabs={[
            { id: "buy",  label: "Buy",  panel: (
              <For each="shop_items">
                {(item) => <Text class="text-slate-200" bind={item("#item_name")} />}
              </For>
            ) },
            { id: "sell", label: "Sell", panel: <Text class="text-slate-400">Nothing to sell.</Text> },
          ]}
        />
      </Col>
    </Overlay>
  ),
});

Every class is checked; every bind is typed; the bg-*/border/rounded bakes to a nine-slice PNG; the Tabs selection lowers to a Bedrock radio-toggle group; For lowers to a factory + collection binding.


The model

Reactivity — one primitive, four clocks

Bedrock state isn't locally mutable — the game, the server, or the UI-assembly step owns it. jui models this honestly with one primitive, signal(), whose clock (when it resolves) is inferred:

Clock Written Resolves Lowers to
Build a plain value at compile folded into output (or drops the element)
Inst signal("$var") at UI assembly $variables / |default
Live signal("#binding") per frame, server-owned #binding view / collection bindings
Local local(...) per frame, client-owned toggle / radio groups + view bindings

The type system makes it impossible to read a runtime value at build time. local() is the one structural addition — client-owned state (tabs, toggles, disclosures, input text) that lowers to Bedrock's own toggle/radio machinery, so it works with no server round-trip and the preview simulates it perfectly.

Surfaces — where a UI lives

Surface What it is
Server form The game renders a server-sent form; jui reskins it by a title flag. The primary path.
Screen patch Non-destructively modify a vanilla screen (HUD, inventory, chat, pause) via modifications.
HUD overlay Insert content into the vanilla HUD (hudOverlay).
Standalone screen A jui-owned document (defineScreen).

Assets — the differentiator

Any styled box becomes generated art; you ship polished UI without opening an image editor (and hand art drops in through the same src= / theme tokens when you want it). One pipeline bakes them all:

Source ─render→ Raster ─▶ registry (dedup) ─▶ frame-dedup ─▶ imagequant ─▶ oxipng ─▶ PNG + sidecar

Sources include canvas/procedural (seeded noise/fbm/voronoi), vector (SVG via resvg + an SVG-JSX DSL), image pipelines, GIF, 3D (.geo.json/.bbmodel through a wgpu mesh renderer + a GPU effect graph — outline, AO, rim, bloom, grade…), schematics (.schematic/ .litematic/.nbt parsed + meshed via nucleation), GPU particles, layer composites, and bevel. Animated sources reduce to a single flipbook with content-hash frame dedup + non-sequential playback. Builds are deterministic — identical inputs, identical bytes — which is what makes the cache correct.

Kit & theming

An opt-in jui/ui library of headless components (structure + behavior as named parts, no visual opinion) — overlays, navigation, data, feedback, and forms as a first-class category (all Bedrock custom-form element types, index-aligned with the server, with inline field errors). A theme fills each part's recipe slot with chrome that bakes through the normal asset pipeline, so switching a theme re-bakes every piece — several built-in packs (OreUI-like / clean / retro), all overridable per token or per part.


Architecture — the dependency law

The project is designed top-down but access flows strictly downward only. Every crate has a layer number (L0–L8); a crate may depend on lower or same-layer crates, never a higher layer.

This is enforced in CI (cargo xtask layering lint + cargo-deny), not just hoped for — it keeps the V8 mess and the GPU/devtools dependencies from ever leaking into the core, and makes every crate independently testable.

L0  jui-span · jui-color · jui-noise                 foundations
L1  jui-expr · jui-hir · jui-mir                      IRs
L2  jui-style · jui-lower · jui-cse                   compile passes
L3  jui-raster · jui-render · jui-codec · jui-flipbook · jui-assets   assets
L4  jui-emit · jui-preview                            out & preview
L5  jui-script                                        the ONLY crate that touches V8
L6  jui-lint · jui-contract · jui-build               orchestration
L7  devtools-core · panel-* · jui-devtools            devtools
L8  jui                                               the user-facing binary

The runtime/ TypeScript authoring package sits outside the crate graph. The single seam between JS and Rust is a versioned HIR-JSON schema (elements, flow, Expr values, and source spans).

The full design lives in docs/ — 30 numbered files, the canonical specification.


CLI

jui build [entry] [--out dir] [--png] [--sync <dir>] [--pack]   compile → pack (+ PNGs, launcher sync, .mcpack)
jui devtools [entry] [--panel <name>]                            the integrated IDE, or one panel standalone
jui snapshot <entry> [--against ref.png]                         render a screen → PNG (visual-regression)
jui ingest <ui-dir> [--types]                                    vanilla dump → typed catalog
jui verify <entry>                                               check patch/route targets against the catalog

Config lives in one typed home (defineConfig / jui.config.ts): entry, out, sync, vanilla pack, target MC version, theme, locale, cache dir. CLI flags override config fields.


Repository layout

crates/       the Rust crate graph (L0–L8)
runtime/      the TypeScript authoring package (outside the graph)
examples/     example .tsx screens, forms, HUDs, and asset showcases
docs/         the canonical design specification (00–29)
goldens/      golden-test fixtures (exact-JSON + perceptual-PNG)
xtask/        dev tooling — the layering lint
zed-jui/      the Zed editor extension

Status

Built bottom-up in phases, each finished green with a working demo before the next:

  • Phase 0–4 — workspace + layering law · compiler spine (signals, control flow, local-state, nav/focus, source-mapped diagnostics) · the asset pipeline (bake → dedup → quantize → cache) · the wgpu renderer + vanilla-accurate preview · the full generative asset suite (2D/3D/vector/particles/ schematics/fonts).
  • Phase 5 — authoring polish, the kit, forms + contract, i18n, motion, theming, version targeting, a11y lints.
  • Phase 6 — devtools completeness: the integrated IDE (preview / inspector / effect + asset labs / state + server simulator / timeline / diagnostics) plus CLI power-tools.
  • Phase 7 — hardening toward 1.0 (fuzz, determinism, interaction snapshots, cache eviction).

APIs are not yet stable — the shape comes first.


License

Apache-2.0.

jui generates resource packs and consumes vanilla assets as a build input (cached on your machine, never shipped); it does not bundle or redistribute Mojang assets.

About

tsx to json ui compiler

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages