# RenderLib

RenderLib is a client-side Fabric rendering library for Minecraft **26.1.2**. It provides one coherent API for retained GUI screens, movable HUD layouts, world-space objects, screen extensions, and low-level immediate drawing.

The current repository targets:

| Toolchain | Version |
| --- | --- |
| Minecraft | `26.1.2` |
| Java | `25` |
| Fabric Loader | `0.19.3` |
| Fabric API | `0.154.2+26.1.2` |
| RenderLib | `2.0.0` |
| Names | official Minecraft names |

> RenderLib is developed against one exact Minecraft line. Do not assume source or binary compatibility with older `1.21.x` releases.

## Choose an API

| You want to… | Start with | Guide |
| --- | --- | --- |
| Build a full retained screen | `GuiView` + `GuiComponent` | [GUI library guide](GUI_LIBRARY_GUIDE.md) |
| Add movable retained HUD elements | `ManagedHudLayout` | [HUD guide](HUD_WIDGET_LIBRARY_GUIDE.md) |
| Shape and paint high-fidelity 2D text | `GuiTextStyle` + `GuiTextEngine` | [Text engine guide](TEXT_ENGINE_GUIDE.md) |
| Build renderer-compatible 3D scenes, models, effects, particles, or picking | `WorldScene` / `RenderLibWorld` | [World rendering guide](HIGH_LEVEL_3D_GUIDE.md) |
| Overlay or replace an existing screen | `RenderLibScreen` | [Screen injection guide](SCREEN_INJECTION_GUIDE.md) |
| Replace a handled menu while preserving vanilla logic | `RenderLibMenu` | [Screen injection guide](SCREEN_INJECTION_GUIDE.md#3-virtual-menus) |
| Browse the complete public API | Documentation site | [Open `docs/index.html`](docs/index.html) |

## Add RenderLib to a mod

Use the public Maven repository in the consuming mod:

```groovy
repositories {
    maven {
        name = "RenderLib"
        url = "https://renderlib.ifallious.com/maven"
        content { includeGroup "com.render" }
    }
}

dependencies {
    modImplementation "com.render:render-lib:2.0.0"
}
```

Declare the runtime dependency in the consuming mod's `fabric.mod.json`:

```json
{
  "depends": {
    "render-lib": ">=2.0.0"
  }
}
```

Gradle will include RenderLib on development run configurations. Install the same jar alongside the consuming mod in a normal client. RenderLib bootstraps its GUI, HUD, world, screen-extension, and menu hooks from its Fabric client entrypoint; consumers do not call those bootstrap methods again.

Browse the hosted [documentation](https://renderlib.ifallious.com/), [Javadoc](https://renderlib.ifallious.com/javadoc/), or download the consumer-only [Codex skill](https://renderlib.ifallious.com/skill/use-renderlib.zip).

## Build this repository

```powershell
.\gradlew.bat test
.\gradlew.bat build
```

The remapped runtime jar is written to `build/libs`. Distribution tasks are:

```powershell
.\gradlew.bat assembleDocumentationSite
.\gradlew.bat assemblePublicSite
.\gradlew.bat deployWebsite
.\gradlew.bat publishMavenRelease
.\gradlew.bat publishPublicRelease
```

`assembleDocumentationSite` creates the website without Maven artifacts. `assemblePublicSite` creates a complete local bundle. The three publishing tasks deploy website-only changes, an immutable Maven version, or both respectively.

## First retained screen

```java
import com.render.api.RenderColor;
import com.render.api.gui.ButtonComponent;
import com.render.api.gui.ContainerComponent;
import com.render.api.gui.GuiView;
import com.render.api.gui.TextComponent;

public final class SettingsView extends GuiView {
    @Override
    protected void build() {
        ContainerComponent panel = new ContainerComponent()
            .centered()
            .size(720.0F, 420.0F)
            .padding(28.0F)
            .flowColumn()
            .gap(16.0F)
            .backgroundColor(RenderColor.hex("#F20B1017"))
            .borderColor(RenderColor.hex("#4D5EE7F7"))
            .borderWidth(1.0F)
            .cornerRadius(24.0F);

        panel.add(new TextComponent()
            .text("RenderLib")
            .textScalePixels(30.0F)
            .color(RenderColor.hex("#EAFBFF"))
            .shadow(false));

        panel.add(new ButtonComponent()
            .text("Close")
            .onPress(this::close));

        root().add(panel);
    }
}
```

Open the retained view on the client thread:

```java
new SettingsView().open();
```

## What is implemented now

- Retained component trees with absolute, stacked, row-flow, and column-flow layout.
- Rounded fills and true border rings rendered through a signed-distance shader.
- Rounded box shadows and glows with analytic Gaussian falloff.
- Linear, radial, and conic gradients with multiple stops, exact hard transitions, repetition, and adjustable lookup precision.
- Reusable sparse `GuiStylePreset` styles with hover, pressed, focused, and disabled states.
- Default `GuiUiMode.MODERN` typed Java stylesheets with selectors, cascade
  layers, inheritance, custom states, and stable generated pseudo-element
  boxes; select `GuiUiMode.LEGACY` explicitly for the original runtime.
- Modern-mode intrinsic measurement and fragment layout with typed lengths,
  content/border sizing, block and inline flow, Flexbox, Grid, relative/
  absolute/fixed/sticky positioning, anchors, baseline alignment, and
  fragment-based hit testing.
- HarfBuzz-shaped, ICU-laid-out 2D text with Noto variable fonts, bidi and
  complex-script clusters, OpenType features/axes, gradients, strokes,
  layered shadows, decorations, hit testing, and grapheme-safe inputs.
- Transitions, keyframes, overlays, dialogs, toasts, drag/drop, inputs, menus, images, SVGs, entity previews, and resource-backed TTF/OTF/TTC families.
- Opt-in modern retained paint: reusable raster/SVG/gradient/mesh/worklet
  `GuiImage` values, ordered background layers, pixel/percentage/double
  gradient stops and hints, seven interpolation spaces, hue-path control,
  typed per-side borders/outlines/shadows, exact raster/procedural nine-slice
  borders, adaptive Coons-patch meshes, managed `GuiImage` software cursors,
  and animated versioned retained SVG trees.
- Compositor backend: immutable transform/clip/mask/filter/motion
  values, live projective subtree transforms and curved SVG motion paths with
  inverse hit testing, painted shape clips, pooled image-mask/filter
  passes, bounds-scissored dense Gaussian blur, analytic common rounded masks,
  and clipped glass backdrops that include the live game and earlier UI while
  retaining a sharp foreground. Managed views own their screen
  background rather than inheriting a global menu blur, and every backdrop has
  an explicit-shape or implicit border-box clip. Screen, managed-HUD,
  retained-widget, and HUD-toast graphs accumulate without replacing one
  another; per-view
  `GuiRenderCompatibilityReport` / `GuiRenderStats` expose telemetry.
- Text runtime: closed-by-default per-view font policy, bounded
  operating-system discovery, asynchronous allowlisted remote
  SFNT/WOFF/WOFF2 caching, real LCD RGB/BGR coverage with eligibility
  fallback statistics, animated carets, and foreground-aware selection/named
  highlight pseudo paint.
- Interaction runtime: automatic `list-item` markers/counters,
  additive and disjoint-range counter styles, configurable quotes, independent
  X/Y clipping, distinct hidden/clip behavior, stable scrollbar gutters,
  exact rounded overflow masks, scroll margins/snap-stop, automatic anchoring,
  retained marker navigation, configurable smooth scrolling, all-property
  typed transitions/animations, named view-progress ranges, and retained
  old/new view transitions.
- Keyboard focus traversal with `tabIndex`, reverse traversal, modal focus trapping, and focus restoration.
- Bounded asynchronous image/SVG loading with cache reset on resource reload and guarded URL input.
- Managed HUD placement with client-local position, scale, and opacity persistence.
- Renderer-neutral extracted world scenes with primitives, strokes, models/OBJ, LOD, particles, trails, decals, effects, picking, statistics, and renderer diagnostics.
- Additive/replacement screen extensions and packet-safe virtual menu action queues.

## Quality boundary

RenderLib borrows useful ideas from browser layout and paint APIs, but it is **not a browser engine**. Its 2D text stack follows the browser-style itemize/shape/layout/paint pipeline, while the surrounding rendering backend, clipping, compositing, input model, and layout algorithms remain Minecraft-specific. In particular:

- legacy hosts retain RenderLib's focused absolute/stack/row/column layouts;
  modern hosts add typed block/inline, Flexbox, Grid, intrinsic sizing, and
  positioning over the retained component tree, rather than a browser DOM;
- styling and layout remain Java-only with no CSS text parser, stylesheet
  files, DOM, or embedded script runtime; the compositor executes typed effect graphs
  through managed pooled targets;
- effects use RenderLib-owned GPU passes tuned for GUI rendering, including a
  separable Gaussian backdrop blur, but are not complete CSS filter
  conformance;
- opacity and explicit isolation create atomic retained-subtree compositing
  groups, while non-normal background blend requests currently use the
  documented source-over fallback;
- affine/projective transform lists, full curved SVG motion paths, and painted
  basic/path clips execute through Minecraft's extracted GUI and managed
  target APIs;
- remote assets are intentionally restricted and should not be used for untrusted arbitrary content;
- large scroll trees are not a virtualized list implementation;
- framebuffer-dependent world effects are capability-routed and may use documented portable fallbacks, especially with shader packs or unknown renderer replacements.

See [performance and limits](docs/PERFORMANCE_AND_LIMITS.md) before designing a large or effect-heavy interface.

## Documentation map

- [Getting started](docs/GETTING_STARTED.md) — dependency setup, initialization, design space, and a first feature.
- [GUI library guide](GUI_LIBRARY_GUIDE.md) — layout, styling, widgets, focus, overlays, animation, assets, and custom components.
- [Text engine guide](TEXT_ENGINE_GUIDE.md) — font families, shaping, Unicode layout, rich text, paint/effects, metrics, editing, caches, fallback, and migration.
- [Style and rendering](docs/STYLE_AND_RENDERING.md) — colors, borders, gradients, shadows, glow, text, images, and fidelity notes.
- [HUD guide](HUD_WIDGET_LIBRARY_GUIDE.md) — managed layouts, editor behavior, persistence, passive content, and immediate HUD rendering.
- [World rendering guide](HIGH_LEVEL_3D_GUIDE.md) — scenes, retained/immediate commands, materials, models, effects, lifecycle, and picking.
- [Renderer compatibility](RENDERER_COMPATIBILITY_GUIDE.md) — Vanilla, Sodium, Iris, SAFE mode, fallbacks, diagnostics, and smoke profiles.
- [World API migration](WORLD_3D_MIGRATION.md) — breaking changes for the 2.0.0 world API.
- [Screen injection guide](SCREEN_INJECTION_GUIDE.md) — additive layers, replacement views, handled-screen context, virtual menus, and safe queues.
- [API reference](docs/API_REFERENCE.md) — high-signal type and method index.
- [Performance and limits](docs/PERFORMANCE_AND_LIMITS.md) — cost model, cache behavior, design guidance, and current limitations.
- [Offline workbench](docs/index.html) — searchable, responsive documentation with copyable examples and a small style explorer.

## Repository landmarks

- Public APIs: `src/main/java/com/render/api`
- Retained GUI framework: `src/main/java/com/render/api/gui`
- Client bootstrap and showcase: `src/main/java/com/render/client`
- Minecraft integration mixins: `src/main/java/com/render/mixin`
- Tests: `src/test/java/com/render/api`
- Runtime shaders and fonts: `src/main/resources/assets/render-lib`

The built-in showcase is opt-in. Start a development client with `-Drenderlib.demo=true` to register it, and optionally add `-Drenderlib.demo.autopen=true` to open the control surface as soon as a world loads. Its seven-page feature gallery runs in `GuiUiMode.MODERN` and gives each major subsystem a separate live screen. The gallery demonstrates the typed cascade, inheritance, pseudo-elements, intrinsic sizing, Flexbox, Grid, positioning, anchors, final fragments, unified images, layered backgrounds, advanced gradients, mesh/worklet paint, retained SVG styling, per-side borders, portable subtree transforms, inset clips, immutable effect nodes, compositor diagnostics, external-font policy, caret/highlight styling, generated counters and markers, two-axis scrolling, snap behavior, timelines, reduced motion, semantic tables, balanced multicolumn flow, and virtualized on-screen pages. The gameplay telemetry card, focus card, and toast use light white frosted surfaces with independently rounded live-game backdrop blur. F12 opens the live inspector safely on any page. The demo also builds a fully labeled 3D gallery six blocks ahead of the player's initial view: every primitive and circle form, text/images/original full-height beacon waypoints, generated and OBJ models, instances, LOD, particles, trails, decals, picking, all nine effects (including true emissive-mask bloom where validated), every depth/blend/cull/lighting and stroke policy, both animation clocks, immediate commands, plus the live renderer backend and fallback counters. A high-altitude custom-mesh sun demonstrates vertex-colored limb darkening and granulation, feathered sunspots, and very strong orange-red per-emitter bloom without decorative outer shells or changes to Minecraft's sky renderer. The gallery rebuilds in front of the player after a world change. Normal runtime behavior stays quiet by default.

## License

See [LICENSE](LICENSE) and [third-party notices](THIRD_PARTY_NOTICES.md).