Imported from TheRedDeveloper/ply-engine (SKILL.md). Install upstream with npx skills add TheRedDeveloper/ply-engine. Copyright stays with the author.

Ply Engine

This part is the ultimate guide for writing Ply applications.

Part 1: Non-Negotiable Rules

Never hallucinate Ply APIs. If a method is not listed in this skill, do not invent it.
Always make sure you do:

use ply_engine::prelude::*;

Respect feature gates. If an API requires a feature, make sure the feature is enabled before using it.
Indentation policy for generated code:

First, detect the existing indentation style and preserve it.
If style is unclear or you are generating a fresh snippet, default to 2-space indentation.
Never mix tabs and spaces in the same block.

Prefer explicit IDs for interactive elements and list items.
Every element should have explicit sizing configured.
Builder closures must use chain-return style by default.

DO THIS:

.layout(|l| l
  .direction(TopToBottom)
  .align(CenterX, Top)
  .gap(12)
  .padding(14)
)

DO NOT DO THIS:

.layout(|l| {
  l.direction(TopToBottom)
    .align(CenterX, Top)
    .gap(12)
    .padding(14);
  l
})

The same rule applies to other builder closures such as overflow, border, scrollbar, floating, effect, shader, text_input, and accessibility.

Part 2: Feature Matrix

Ply crate features:

a11y (default): accessibility support
text-styling: inline styling and animation tags
tinyvg: TinyVG vector rendering
shader-build: shader build pipeline utilities for build.rs
built-in-shaders: built-in shader assets
net: HTTP + WebSocket APIs
net-json: JSON deserialization helpers for net responses
audio: macroquad audio re-exports
storage: cross-platform persistent storage API

Part 3: App Skeleton

This is the default project structure generated by plyx init:

use ply_engine::prelude::*;

fn window_conf() -> macroquad::conf::Conf {
  macroquad::conf::Conf {
    miniquad_conf: miniquad::conf::Conf {
      window_title: "Hello Ply!".to_owned(),
      window_width: 800,
      window_height: 600,
      high_dpi: true,
      sample_count: 4,
      platform: miniquad::conf::Platform {
        webgl_version: miniquad::conf::WebGLVersion::WebGL2,
        ..Default::default()
      },
      ..Default::default()
    },
    draw_call_vertex_capacity: 100000,
    draw_call_index_capacity: 100000,
    ..Default::default()
  }
}

#[macroquad::main(window_conf)]
async fn main() {
  static DEFAULT_FONT: FontAsset = font!("assets/fonts/MyFont.ttf");
  let mut ply = Ply::new(&DEFAULT_FONT).await;

  loop {
    clear_background(BLACK);

    let mut ui = ply.begin();

    ui.element()
      .width(grow!())
      .height(grow!())
      .layout(|l| l.align(CenterX, CenterY))
      .children(|ui| {
        ui.text("Hello, Ply!", |t| t.font_size(32).color(0xFFFFFF));
      });

    ui.show().await;
    next_frame().await;
  }
}

Of course this is often expanded with different files that contain different functionality and components.

Part 4: Prelude

Everything below is re-exported from ply_engine::prelude in this repository.

4.1 Core Types

Ply
Ui
ElementBuilder
NoId
WithId
Id
GraphicAsset
FontAsset
ShaderAsset
Lerp
PointerData
PointerState
all easing functions from crate::easing::*

4.2 Utilities

render_to_texture
set_shader_source

4.3 Sizing Macros

grow!
fit!
fixed!
percent!
ratio!

4.4 Globbed Enums

AlignX::{Left, CenterX, Right}
AlignY::{Top, CenterY, Bottom}
BorderPosition::{Outside, Middle, Inside}
LayoutDirection::{LeftToRight, TopToBottom}

4.5 Type-Only Re-exports

WrapMode
AccessibilityRole

4.6 Feature-Gated Re-exports

built-in-shaders: *
net: net, WsMessage
storage: Storage
text-styling: styling
audio: *

4.7 Always Re-exported Modules and Helpers

jobs module
full macroquad::prelude::*
Ply Color
MacroquadColor alias for macroquad color
macroquad crate
CursorIcon

Important: because full macroquad::prelude::* is re-exported, any macroquad-prelude function/type is also in scope when using Ply prelude.

Part 5: Full API Reference (Ply, Ui, Builders)

5.1 `Ply` Core Methods

Construction and lifecycle:

Ply::new(default_font).await
Ply::new_headless(dimensions)
begin() -> Ui
eval() -> Vec<RenderCommand>
show().await

Pointer, focus, and cursor:

pointer_over(id) -> bool
pointer_over_ids() -> Vec<Id>
focused_element() -> Option<Id>
set_focus(id)
clear_focus()
is_pressed(id) -> bool
is_just_pressed(id) -> bool
is_just_released(id) -> bool
set_cursor(CursorIcon)
get_cursor() -> CursorIcon

Text input state by ID:

get_text_value(id) -> &str
set_text_value(id, value)
get_cursor_pos(id) -> usize
set_cursor_pos(id, pos)
get_selection_range(id) -> Option<(usize, usize)>
set_selection(id, anchor, cursor)

Layout, bounds, scroll:

set_layout_dimensions(dimensions)
pointer_state(position, is_down)
update_scroll_containers(drag_scrolling_enabled, scroll_delta, delta_time)
bounding_box(id) -> Option<BoundingBox>
scroll_container_data(id) -> Option<ScrollContainerData>
set_scroll_position(id, position)

Debug and performance:

set_debug_mode(bool)
set_debug_view_width(f32)
is_debug_mode() -> bool
set_culling(bool)
max_element_count(u32)
max_measure_text_cache_word_count(u32)
set_measure_text_function(|text, config| -> Dimensions)

5.2 `Ui` Methods

element() -> ElementBuilder
text(text, |TextConfig| ... )
scroll_offset() -> Vector2
inline-state queries for current open element context:
- hovered()
- pressed()
- just_pressed()
- just_released()
- focused()

Ui dereferences to Ply, so all Ply methods are callable from ui too.

5.3 `ElementBuilder` Methods (Complete)

Layout and sizing:

width(Sizing)
height(Sizing)
contain(f32)
cover(f32)
layout(|LayoutBuilder| ...)

Visuals:

background_color(color)
corner_radius(f32 | (f32, f32, f32, f32))
border(|BorderBuilder| ...) (multiple possible)
overflow(|OverflowBuilder| ...)
image(ImageSource)
effect(shader_asset, |ShaderBuilder| ...)
shader(shader_asset, |ShaderBuilder| ...)
rotate_visual(|VisualRotationBuilder| ...)
rotate_shape(|ShapeRotationBuilder| ...)

Structure and identity:

id(id_like) (NoId -> WithId)
get_id() -> &Id
floating(|FloatingBuilder| ...)
children(|ui| ...) -> Id
empty() -> Id

Interactivity:

with(|&mut Ui, ElementBuilder<WithId>| ...)
capture()
on_hover(|Id, PointerData| ...)
on_press(|Id, PointerData| ...)
on_release(|Id, PointerData, bool| ...)
on_focus(|Id| ...)
on_unfocus(|Id| ...)
preserve_focus()

Text input and accessibility:

text_input(|TextInputBuilder| ...)
accessibility(|AccessibilityBuilder| ...)

Part 6: Sizing and Layout APIs

6.1 `Sizing` and Macros

fit!() or fit!(min, max) or named args (min:, max:)
grow!() or grow!(min, max, weight) or named args (min:, max:, weight:)
fixed!(px)
percent!(fraction)
ratio!(aspect_ratio)

Notes:

grow!(weight: 0.0) behaves as fit internally.
negative grow weight is invalid.
ratio!(r) derives the dimension from the opposite axis (height = width / ratio on height, width = height * ratio on width). Setting ratio! on both axes panics during layout.
contain(ratio) and cover(ratio) adjust the element's resolved bounding box to fit or cover its allocated slot to respect the aspect ratio.

6.2 `LayoutBuilder`

gap(u16)
align(AlignX, AlignY)
direction(LayoutDirection)
wrap()
wrap_gap(u16)
padding(u16 | (top, right, bottom, left))

6.3 `OverflowBuilder`

clipping: clip_x(), clip_y(), clip()
scrolling: scroll_x(), scroll_y(), scroll()
no_drag_scroll()
scrollbar(|ScrollbarBuilder| ...)

6.4 `ScrollbarBuilder`

width(f32)
corner_radius(f32)
thumb_color(color)
track_color(color)
min_thumb_size(f32)
hide_after_frames(u32)

6.5 `FloatingBuilder`

offset(Vector2-like)
z_index(i16)
anchor((AlignX, AlignY), (AlignX, AlignY))
attach_parent()
attach_root()
attach_id(id)
clip_by_parent()
passthrough()

6.6 `BorderBuilder`

color(color)
all(u16)
left(u16)
right(u16)
top(u16)
bottom(u16)
between_children(u16)
position(BorderPosition)

6.7 Rotation Builders

Visual rotation (rotate_visual):

degrees(f32)
radians(f32)
pivot((x, y)) normalized in [0,1]
flip_x()
flip_y()

Shape rotation (rotate_shape):

degrees(f32)
radians(f32)
flip_x()
flip_y()

Part 7: Text APIs

7.1 `ui.text` + `TextConfig`

Text configuration methods:

color(color)
font(&'static FontAsset)
font_size(u16)
letter_spacing(u16)
line_height(u16)
wrap_mode(WrapMode)
alignment(AlignX)
effect(shader_asset, |ShaderBuilder| ...)
accessible()

WrapMode variants:

Words
Newline
None

7.2 Color Inputs

Ply Color accepts:

0xRRGGBB integers
(u8, u8, u8)
(u8, u8, u8, u8)
(f32, f32, f32)
(f32, f32, f32, f32)

Important: float channels are in 0..255 space, not 0..1.

Part 8: Text Input APIs

8.1 `TextInputBuilder`

placeholder(&str)
max_length(usize)
password()
multiline()
drag_select()
font(&'static FontAsset)
font_size(u16)
text_color(color)
placeholder_color(color)
cursor_color(color)
selection_color(color)
line_height(u16)
scrollbar(|ScrollbarBuilder| ...)
no_styles_movement()
on_changed(|&str| ...)
on_submit(|&str| ...)

8.2 `text_input::styling` module (feature: `text-styling`)

Important public functions:

escape_str(s): Escapes all style delimiters in a string
strip_styling(s): Removes all style tags, returning plain content
cursor_to_content(s, pos): Converts cursor pos to content character index
content_to_cursor(s, pos, snap_to_content): Converts content character index to cursor pos. When snap_to_content is true, the cursor skips structural positions like } and lands on the next visible character.
cursor_to_raw(s, pos): Converts styled cursor pos to raw index in the string
raw_to_cursor(s, pos): Converts raw string index to cursor position in the styled string

Different types of positions:

raw position: index in the full styled string, including markup such as {color=...|...} and escape characters.
cursor position: visual cursor index used by text input editing. This includes visible characters and styling structure positions that the cursor can pass through.
content position: index in plain visible content after styling is stripped.

Part 9: IDs, Interactivity, and State

9.1 `Id`

Id::new(label)
Id::new_index(label, index)
Id::new_index_seed(label, index, seed)
From<&'static str> and From<(&str, u32)>

9.2 Inline State Queries

Inside the active .children(|ui| ...) scope:

ui.hovered()
ui.pressed()
ui.just_pressed()
ui.just_released()
ui.focused()

9.3 Callback Events

.on_hover(|id, pointer| ...)
.on_press(|id, pointer| ...)
.on_release(|id, pointer, hovered| ...)
.on_focus(|id| ...)
.on_unfocus(|id| ...)

PointerData:

pointer.position: Vector2
pointer.state: PointerState (Idle, PressedThisFrame, Pressed, ReleasedThisFrame)
pointer.pressed() -> bool: checks if pointer is currently pressed (Pressed or PressedThisFrame)
pointer.released() -> bool: checks if pointer is currently released (Idle or ReleasedThisFrame)
pointer.just_pressed() -> bool: checks if pointer was just pressed this frame (PressedThisFrame)
pointer.just_released() -> bool: checks if pointer was just released this frame (ReleasedThisFrame)

Use .capture() on interactive elements (e.g. buttons inside a larger clickable area) to capture pointer input and prevent it from propagating to parent elements. Use .preserve_focus() on toolbar-like controls that should not steal text-input focus.

9.4 State Queries by ID

is_pressed(id)
is_just_pressed(id)
is_just_released(id)
pointer_over(id)
pointer_over_ids()
bounding_box(id)
scroll_container_data(id)

Part 10: Rendering, Assets, and Shader APIs

10.1 Assets

GraphicAsset:

graphic!("assets/images/logo.png") (macro embeds bytes relative to crate manifest)
GraphicAsset { id, data }

FontAsset:

font!("assets/fonts/lexend.ttf") (macro embeds bytes relative to crate manifest)
FontAsset { id, data }

Image inputs accepted by .image(...):

&'static GraphicAsset
Texture2D
tinyvg::format::Image (feature: tinyvg)

10.2 Shader APIs

ShaderAsset variants:

shader!("assets/shaders/custom.frag.glsl") (macro embeds shader source)
Source { id, fragment }
Stored(&'static str)

ShaderBuilder:

.uniform(name, value) where value is one of:
- f32
- [f32; 2]
- [f32; 3]
- [f32; 4]
- i32
- [[f32; 4]; 4]

Runtime shader source updates:

set_shader_source(name, fragment_source)
then reference through ShaderAsset::Stored(name)

10.3 Render Utility

render_to_texture(width, height, || { draw calls }) -> Texture2D

10.4 Built-in Shader Constants (feature: `built-in-shaders`)

FOIL: u_time (required), u_speed (default 1.0), u_intensity (default 0.3)
HOLOGRAPHIC: u_time (required), u_speed (default 1.0), u_saturation (default 0.7)
DISSOLVE: u_threshold (required), u_edge_color (required), u_edge_width (default 0.05), u_seed (default 0.0)
GLOW: u_glow_color (required), u_glow_radius (default 0.05), u_glow_intensity (default 1.0)
CRT: u_line_count (default 100.0), u_intensity (default 0.3), u_time (recommended)
GRADIENT_LINEAR: u_color_a (required), u_color_b (required), u_angle (default 0.0, radians)
GRADIENT_RADIAL: u_color_a (required), u_color_b (required), u_center (default [0.5, 0.5]), u_radius (default 0.5)
GRADIENT_CONIC: u_color_a (required), u_color_b (required), u_center (default [0.5, 0.5]), u_offset (default 0.0), u_hardness (default 0.0)

Part 11: Accessibility APIs

11.1 `AccessibilityRole` variants

None
Button
Link
Heading { level }
Label
StaticText
TextInput
TextArea
Checkbox
RadioButton
Slider
Group
List
ListItem
Menu
MenuItem
MenuBar
Tab
TabList
TabPanel
Dialog
AlertDialog
Toolbar
Image
ProgressBar

11.2 `AccessibilityBuilder` methods

role shortcuts:
- button(label: &str)
- heading(label: &str, level: u8)
- link(label: &str)
- static_text(label: &str)
- checkbox(label: &str)
- slider(label: &str)
- image(alt: &str)
generic fields:
- role(role: AccessibilityRole)
- label(text: &str)
- description(text: &str)
- value(text: &str)
- value_min(min: f32)
- value_max(max: f32)
- checked(checked: bool)
focus and order:
- focusable()
- tab_index(index: i32)
directional focus:
- focus_right(target: impl Into<Id>)
- focus_left(target: impl Into<Id>)
- focus_up(target: impl Into<Id>)
- focus_down(target: impl Into<Id>)
focus ring:
- disable_ring()
- ring_color(color: impl Into<Color>)
- ring_width(width: u16)
live regions:
- live_region_polite()
- live_region_assertive()

Part 12: Feature Modules (Net, Storage, Jobs, Audio)

12.1 Networking (`net`)

HTTP:

net::get(id, url, |HttpConfig| ...)
net::post(...)
net::put(...)
net::delete(...)
net::request(id) -> Option<Request>

HttpConfig methods:

header(key, value)
body(&str)
body_bytes(Vec<u8>)

Request methods:

response() -> Option<Result<Arc<Response>, String>>
cancel()

Response methods:

status() -> u16
text() -> &str
bytes() -> &[u8]
json<T>() (feature: net-json)

WebSocket:

net::ws_connect(id, url, |WsConfig| ...)
net::ws(id) -> Option<WebSocket>

WsConfig methods:

header(key, value)
insecure()

WebSocket methods:

send(&[u8])
send_text(&str)
recv() -> Option<WsMessage>
close()

WsMessage variants:

Connected
Text(String)
Binary(Vec<u8>)
Error(String)
Closed

12.2 Storage (`storage`)

Storage::new(path).await
save_string(path, data).await
save_bytes(path, data).await
load_string(path).await
load_bytes(path).await
remove(path).await
export(path).await

12.3 Jobs (`jobs`)

jobs::spawn(id, || async move { ... }, |result| { ... })
jobs::running(id)
jobs::is_running(id)
jobs::list()

12.4 Audio (`audio`)

When audio feature is enabled, macroquad audio APIs are in prelude. Typical calls:

load_sound(path).await
load_sound_from_bytes(bytes).await
play_sound_once(&sound)
play_sound(&sound, PlaySoundParams { .. })
stop_sound(&sound)
set_sound_volume(&sound, volume)

Part 13: Lerp and Easing APIs

13.1 `Lerp` trait

Implemented for:

f32
u16
Vector2
macroquad::prelude::Vec2
(f32, f32, f32, f32)
(u16, u16, u16, u16)
Color

Color-specific helpers:

Color::lerp_srgb(...)
Color::lerp_oklab(...)

13.2 Easing functions in prelude

ease_in_quad, ease_out_quad, ease_in_out_quad
ease_in_cubic, ease_out_cubic, ease_in_out_cubic
ease_in_quart, ease_out_quart, ease_in_out_quart
ease_in_sine, ease_out_sine, ease_in_out_sine
ease_in_expo, ease_out_expo, ease_in_out_expo
ease_in_back, ease_out_back, ease_in_out_back
ease_in_elastic, ease_out_elastic, ease_in_out_elastic
ease_out_bounce, ease_in_bounce, ease_in_out_bounce

Part 14: Shader Build Pipeline API

Use in build.rs with feature shader-build in build-dependencies.

Main API:

ShaderBuild::new()
.source_dir("...")
.output_dir("...")
.slangc_path("...")
.override_file_type_handler(ext, handler)
.build()

Defaults:

source: shaders/
output: assets/build/shaders/
SPIR-V temp: build/shaders/spirv/

Part 15: `plyx` CLI Reference for AI

If plyx is available, prefer it for setup and platform builds.

plyx init
plyx add [args]
plyx skill [--install]
plyx apk [--native] [--install] [--auto]
plyx web
plyx ios [--device] [--actions] [--auto]
plyx completions <shell> [--install]

15.1 `plyx init`

Creates a project, selects a font from Google Fonts, and selects feature flags.

Generates:

Cargo.toml
src/main.rs
assets/fonts/.ttf
optional build.rs and shaders/ if shader pipeline is selected
optional .claude/skills/ply-engine/SKILL.md

15.2 `plyx add`

Interactive mode (no args) or non-interactive forms:

plyx add <feature-key>
plyx add font <font name>

Feature keys recognized by plyx templates:

tinyvg
built-in-shaders
shader-pipeline
text-styling
net
net-json (depends on net)
audio
storage
skill

skill and shader-pipeline are plyx concepts, not feature keys in [dependencies]. shader-pipeline adds build-dependencies and build.rs. skill installs .claude/skills/ply-engine/SKILL.md into the project.

15.3 `plyx web`

Builds release wasm and outputs to build/web/:

build/web/app.wasm
build/web/index.html
build/web/ply_bundle.js
copies assets/ if present

15.4 `plyx apk`

Modes:

Docker (default)
native (--native)

Useful flags:

--install to install with adb
--auto non-interactive mode

APK output location:

target/android-artifacts/release/apk/<crate>.apk

15.5 `plyx ios`

Modes:

simulator build by default
real device with --device
workflow generation with --actions

Requirements:

macOS + Xcode tools (xcrun)
proper Rust iOS target
for --device: signing identity, provisioning profile, and entitlements

15.6 `plyx skill`

plyx skill prints the bundled skill text to stdout.
plyx skill --install installs to ~/.claude/skills/ply-engine/SKILL.md.

Part 16: Common Patterns

This section shows some common patterns that emerge when building with Ply. These are just examples, not requirements. You should feel free to deviate from these patterns when the situation calls for it and use appropriate values and variations. We show this with a lot of constants and default values like 24 that you would replace in a real app.

16.1 Cursor

Ply provides engine-managed cursor handling via ui.set_cursor(CursorIcon) and ui.get_cursor() -> CursorIcon:

ui.set_cursor(CursorIcon::Pointer);
let current: CursorIcon = ui.get_cursor();

The default cursor is CursorIcon::Pointer.
ui.set_cursor(...) persists across frames until explicitly changed, and overwrites ui.get_cursor() immediately.
The cursor is automatically applied to the window during ui.eval() / ui.show() (when not headless).

16.2 Styling Function Pattern

Reusable styling should be plain Rust functions that take and return ElementBuilder.

fn rounded<'ply, S>(el: ElementBuilder<'ply, S>) -> ElementBuilder<'ply, S> {
  el.corner_radius(12.0)
}

fn dark_bg<'ply, S>(el: ElementBuilder<'ply, S>) -> ElementBuilder<'ply, S> {
  el.background_color(0x2E2A28)
}

dark_bg(rounded(ui.element()))
  .width(grow!())
  .height(fixed!(60.0))
  .children(|ui| {
    ui.text("Styled with functions", |t| t.font_size(20).color(0xFFFFFF));
  });

For parameterized styles:

fn my_style<'ply, S>(el: ElementBuilder<'ply, S>, bg: u32, radius: f32) -> ElementBuilder<'ply, S> {
  el.background_color(bg).corner_radius(radius)
}

my_style(ui.element(), 0x181515, 10.0)
  .width(fit!())
  .height(fit!())
  .empty();

16.3 Button Example

You might want your buttons to use something like this with .with():

fn button(ui: &mut Ui, label: &str, mut on_click: impl FnMut() + 'static) {
  ui.element().width(fit!()).height(fit!())
    .corner_radius(SOME_RADIUS)
    .layout(|l| l.padding(SOME_PADDING).align(CenterX, CenterY))
    .accessibility(|a| a.button(label))
    .on_press(move |_, _| on_click())
    .with(|ui, el| {
      let bg = if ui.pressed() {
        LIGHT_PRIMARY_COLOR
      } else if ui.hovered() || ui.focused() {
        DARK_PRIMARY_COLOR
      } else {
        PRIMARY_COLOR
      };
      el.background_color(bg)
    })
    .children(|ui| {
      ui.text(label, |t| t.font_size(24).color(0xFFFFFF));
    });
}

.with() executes after the element's ID has been established in .empty() or .children(), so queries like ui.pressed(), ui.hovered(), and ui.focused() accurately refer to this element and el.get_id() is available without needing an extra wrapper element.

16.4 Polling HTTP Example

if user_data.is_none() {
  net::get("user_data", "https://example.com/", |r| r
    .header("Authorization", "Bearer token")
  );
}
// ...
if user_data.is_none() {
  if let Some(req) = net::request("user_data") {
    match req.response() {
      None => {
        ui.text("{swing|Loading...}", |t| t.font_size(24).color(0xFFFFFF));
      }
      Some(Ok(resp)) => {
        if resp.status() == 200 {
          let data: UserData = resp.json().unwrap_or_else(|e| {
            eprintln!("failed to parse user data: {e}");
            UserData::default()
          });
          user_data = Some(data);
        }
      }
      Some(Err(err)) => {
        eprintln!("request failed: {err}");
      }
    }
  }
}

16.5 Storage + Jobs Example

jobs::spawn(
  "save_game",
  || async move {
    Storage::new("my_app").await?
      .save_string("save.json",
        serde_json::to_string(&game_state).map_err(|e| e.to_string())?
      ).await
  },
  |result| {
    if let Err(e) = result {
      eprintln!("Failed to save game: {e}");
    }
  },
)?;

Using Storage on the main thread will cause frame skips on the web. It's best to use it inside a job like this to avoid blocking the main thread.

16.6 Render To Texture + Shader Example

Use a static shader asset for normal rendering flows.

static TINT_SHADER: ShaderAsset = ShaderAsset::Source {
  id: "tint.frag.glsl",
  fragment: r#"#version 100
precision mediump float;
varying vec2 uv;
uniform sampler2D Texture;
uniform vec4 u_tint_color;
uniform float u_tint_strength;

void main() {
  vec4 base = texture2D(Texture, uv);
  vec3 mixed_rgb = mix(base.rgb, u_tint_color.rgb, clamp(u_tint_strength, 0.0, 1.0));
  gl_FragColor = vec4(mixed_rgb, base.a);
}"#,
};

let chart = render_to_texture(400.0, 200.0, || {
  clear_background(BLANK);
  draw_line(0.0, 180.0, 400.0, 40.0, 3.0, GREEN);
  draw_circle(200.0, 110.0, 8.0, RED);
});

ui.element()
  .width(fixed!(400.0))
  .height(fixed!(200.0))
  .image(chart)
  .effect(&TINT_SHADER, |s| s
    .uniform("u_tint_color", [1.0, 0.85, 0.75, 1.0])
    .uniform("u_tint_strength", 0.25f32)
  )
  .empty();

16.7 Accessibility Example

ui.element().id("first").width(fit!()).height(fit!())
  .layout(|l| l.padding(SOME_PADDING))
  .background_color(FIRST_BUTTON_COLOR)
  .accessibility(|a| a.button("First").tab_index(1).focus_right("second"))
  .on_press(|_, _| println!("first pressed"); )
  .children(|ui| {
    ui.text("First", |t| t.font_size(24).color(0xFFFFFF).accessible());
  });

ui.element().id("second").width(fit!()).height(fit!())
  .layout(|l| l.padding(SOME_PADDING))
  .background_color(SECOND_BUTTON_COLOR)
  .accessibility(|a| a.button("Second").tab_index(2).focus_left("first"))
  .on_press(|_, _| println!("second pressed"); )
  .children(|ui| {
    ui.text("Second", |t| t.font_size(24).color(0xFFFFFF));
  });

16.8 Text Input + Text Styling Cursor Helpers

ui.element().id("editor").width(fixed!(400.0)).height(fixed!(120.0))
  .layout(|l| l.padding(BACKGROUND_PADDING))
  .background_color(BACKGROUND_COLOR)
  .text_input(|t| t
    .multiline()
    .font_size(24)
    .drag_select()
    .no_styles_movement()
    .on_changed(|text| println!("changed: {text}"))
  );

let raw = ui.get_text_value("editor").to_string();
let plain = styling::strip_styling(&raw);
let highlighted = plain.replace("TODO", "{color=#FFC32C|TODO}");

if raw != highlighted {
  let cursor = ui.get_cursor_pos("editor");
  let content_pos = styling::cursor_to_content(&raw, cursor);
  ui.set_text_value("editor", &highlighted);
  let new_cursor = styling::content_to_cursor(&highlighted, content_pos, true);
  ui.set_cursor_pos("editor", new_cursor);
}

.text_input() is a terminal method on ElementBuilder (returning Id), allowing developers to configure layout modifiers like .padding() directly on the housing element itself. The scrollable area includes the padding and scrollbars extend to include the padded perimeter. Also note how the .text_input closure is styled with the letter t on the first line and then the .arguments() on the following lines. This is how you should style builders that stretch across multiple lines.

16.9 Floating Tooltip

ui.element().id("tooltip_target").width(fit!()).height(fit!())
  .layout(|l| l.padding(5))
  .corner_radius(6.0)
  .background_color(BUTTON_COLOR)
  .children(|ui| {
    ui.text("Hover me", |t| t.font_size(24).color(0xE8E0DC));

    if ui.hovered() {
      ui.element().width(fit!()).height(fit!())
        .floating(|f| f
          .attach_parent()
          .anchor((CenterX, Top), (CenterX, Bottom))
          .offset((0.0, -4.0))
        )
        .background_color(TOOLTIP_COLOR)
        .corner_radius(6.0)
        .layout(|l| l.padding(5))
        .children(|ui| {
          ui.text("Tooltip text", |t| t.font_size(16).color(0xFFFFFF));
        });
    }
  });

16.10 Wrap Layout and Scrollbar

ui.element().width(grow!()).height(grow!())
  .layout(|l| l.wrap().wrap_gap(8).gap(8).padding(8))
  .overflow(|o| o
    .scroll_y()
    .scrollbar(|s| s
      .width(4.0)
      .thumb_color(0xFFFFFF)
      .track_color(0x222222)
      .hide_after_frames(60)
    )
  )
  .children(|ui| {
    for i in 0..200 {
      ui.element().id(("chip", i)).width(fit!()).height(fit!())
        .layout(|l| l.padding(6))
        .background_color(0x333333)
        .corner_radius(6.0)
        .children(|ui| {
          ui.text(&format!("Chip {i}"), |t| t.font_size(16).color(0xFFFFFF));
        });
    }
  });

16.11 GraphicAsset and FontAsset Pattern

Declare graphic and font assets as static using graphic! and font! macros.

static LOGO: GraphicAsset = graphic!("assets/images/logo.png");
static ICON_TVG: GraphicAsset = graphic!("assets/images/icon.tvg");
static BODY_FONT: FontAsset = font!("assets/fonts/lexend.ttf");

// ...

ui.element().width(fixed!(96.0)).height(fixed!(96.0)).image(&LOGO).empty();
ui.element().width(fixed!(96.0)).height(fixed!(96.0)).image(&ICON_TVG).empty();

ui.text("Body", |t| t.font(&BODY_FONT).font_size(24).color(0xFFFFFF));

UI/UX Playbook

This part is the definitive reference for producing interfaces and visuals that are both rigorously functional and genuinely memorable. It covers design thinking, aesthetic direction, foundational principles, common failure modes, advanced UX strategy, motion design, and game UI.

Part 1: Design Thinking

Before touching anything visual, understand the context and commit to a direction.

1.1 Understand the Brief

Purpose: What problem does this interface solve? Who uses it, and when?
Tone: Pick a clear aesthetic extreme and commit to it. Options include: brutally minimal, maximalist, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian. These are starting points, design something true to the context, not a template.
Constraints: Platform, performance needs, accessibility requirements.
Differentiation: What is the one thing someone will remember about this interface? Name it before you build it.

1.2 Commit, Don't Hedge

The single biggest failure mode in design is timidity, making choices that offend no one and inspire no one. Bold maximalism and refined minimalism are both valid. What fails is the middle: generic layouts, safe fonts, and evenly-distributed palettes that look like every other product.

Match execution depth to aesthetic vision. A maximalist design needs elaborate layering, rich animation, and complex composition. A minimalist design needs razor-sharp spacing, perfect type, and restraint exercised with intention.

Part 2: Foundations

2.1 Signifiers & Affordances

Self-Explanatory UI: Use containers to signal relationships. If items share a container, they are perceived as related.
Visual States: Always define all four interaction states if they exist: Hover, Active, Disabled, Loading. An incomplete state system is an incomplete design.
Cursor Icons: Explicitly define cursor changes. A static cursor is a broken signifier.
Show, Don't Tell: The UI should communicate how it works through visual cues alone, not instructional text.

2.2 Visual Hierarchy & Contrast

Scanning Priority: Place high-priority information at the top. Use size, weight, and color to direct the eye.
The Contrast Engine: Contrast creates hierarchy. Juxtapose big/small, colorful/monochrome, heavy/light. Everything cannot be equally important.
Flow Indicators: Use visual indicators to demonstrate relationships and flow without requiring text.

2.3 The 4-Point Grid

Standard Spacing: Use multiples of 4 for all spacing: 4, 8, 16, 24, 32, 48, 64, unless when your UI should stay the same when resizing.
Section Breathing Room: Usually use at minimum 32px between visually distinct sections.
Proximity as Meaning: Group related elements tightly. Separate unrelated ones clearly. If a label and its input are far apart, the relationship breaks.

2.4 Color & Depth

Semantic Color: Assign meaning consistently: Blue (action/interactive), Red (error/danger), Green (success/confirmation), Yellow (warning/caution). Never reverse these expectations.
Dark Mode Depth: Represent depth by making foreground surfaces lighter than the background, not darker. This mirrors how light physically works.
Dominant + Accent: Dominant colors with sharp accent colors outperform evenly-distributed palettes. Pick a position and commit to it.

2.5 Typography

Typography is communication architecture.

Font Personality by Category:

Serif: Traditional, classic, editorial. Best for print contexts or brands that lean into heritage.
Sans-Serif: Modern, legible, digital-native. The standard for screens.
Display/Decorative: Expressive, high-impact. Use only for headlines or hero moments.
Outdated Fonts: Avoid fonts with strong cultural baggage (Comic Sans, Papyrus, Courier). They undermine credibility regardless of context.
Availibility: Usually use fonts that the user already has in their assets. If the user has no fitting fonts use plyx add font NAME to download from Google Fonts.

Pairing & Palette:

Usually use no more than three typefaces per project. One is often enough.
Pair by contrast: a bold, characterful display face with a quiet, readable body face.
If using a single typeface, create hierarchy through weight, size, and style variation.
Avoid generic defaults. Reach for typefaces with genuine personality. The choice should feel considered, not defaulted to.

Part 3: Aesthetic Execution

3.1 Spatial Composition

Move beyond standard grid layouts. Explore:

Asymmetry and overlap: Elements that cross boundaries or break the grid create dynamism.
Diagonal flow: Leading the eye along a diagonal rather than straight down creates energy.
Generous negative space OR controlled density: Both work. What fails is accidental clutter or accidental emptiness.
Rule of Thirds: It's often good to divide the composition into a 3×3 grid. Place focal points near intersections. The eye naturally follows this path.

3.2 Shape Language

Geometric: Circles and squares are dependable, structured and universal for components and UI containers.
Organic: Free-form shapes are best for illustration, branding moments, or softening otherwise rigid layouts.
Shapes organize, separate, and give content visual "weight." Use them intentionally.

3.3 Texture & Form

Texture adds tactility and depth to flat designs. Use for backgrounds, icons, and accent areas - never everywhere at once.
Form implies three-dimensionality through light, shadow, and perspective.

3.4 Repetition & Consistency

Repeat visual elements (color palette, header styles, icon library, corner radii, spacing patterns) throughout a design. Repetition is not laziness - it is branding. It lets users relax and engage with content rather than decode the interface.

Part 4: Anti-Patterns to Avoid

These are common failure modes that immediately mark a design as amateur.

4.1 Visual Noise

Rainbow gradients: Multi-hue gradients almost always look unintentional. Limit gradients to tonal variations of a single color family.
Unnecessary strokes/borders: Remove borders that don't serve a specific contrast or containment purpose. When in doubt, remove it.
Effect overload: Each visual effect competes for attention. Use effects sparingly so meaningful ones land.

4.2 Inconsistency

Corner radius chaos: Mixing 4px, 8px, 16px, and 24px radii across components without logic looks broken, not dynamic.
Mismatched assets: Icons from different libraries, or illustrations with conflicting lighting and stroke styles, destroy visual coherence.
Redundant affordances: Don't show swipe arrows on touch interfaces or label buttons that already have universal icons.

4.3 User Flow Gaps

Missing escape routes: Every optional flow needs a "Skip" or "Not now" path. Trapping users is a trust violation.
Blank search states: Never show an empty screen when a user opens search. Provide recent searches, suggestions, or categories.

4.4 Generic Aesthetics

Avoid the convergent defaults that make designs indistinguishable from each other:

Overused typefaces that have become visual wallpaper
Purple gradients on white backgrounds
Predictable card-based layouts with no compositional tension
Safe, forgettable color palettes that feel chosen by elimination rather than intention

Every design should feel like it was made for this specific context.

Part 5: Advanced UX Strategy

5.1 User Bases

Design for different user bases:

New users: Prioritize simplicity and clear "getting started" pathways. Reduce cognitive load.
Returning users: Surface current progress, quick-access features, and continuations of prior sessions.
Power users: Expose advanced stats, shortcuts, and optimization tools. Don't hide capability behind beginner guardrails.

5.2 Progress & Trust

Visual timelines: Use staged progress indicators (Processing → Shipped → Delivered) rather than raw dates or text status updates. People understand journey better than timestamp.
Humanizing data: Include names, photos, or personal details for service providers or counterparties. It transforms transactions into interactions.

5.3 Input Method Selection

Sliders: Use for casual, range-based, or exploratory input (age ranges, filters, approximate values).
Text fields: Use for precise, repetitive, or high-accuracy input (weights, quantities, identifiers).

5.4 Alignment Discipline

Elements that are visually "almost" aligned create tension that reads as disorder.

Part 6: Motion Design

Motion is communication. All UI movement must justify itself against these five criteria:

Responsiveness: Interactions must feel immediate and fluid. Latency in motion reads as lag even when performance is fine.
Intention: Motion should guide focus; toward a key action, toward new content, away from what just resolved.
Awareness: Elements should behave differently based on their position and context on screen. Motion is spatial.
Consistency: Repeated motion patterns build familiarity. Users learn interface "physics".
Physical Intuition: Movement should feel grounded. Paper-like physics for document metaphors. Elastic snap for playful UI. Parallax depth for epic scale. Match the motion vocabulary to the world of the product.

Practical priorities:

One well-orchestrated entrance with staggered reveals creates more delight than dozens of scattered micro-interactions.
Hover states and scroll-triggered reveals should surprise.
Animate meaning, not decoration. If removing the animation loses nothing, remove it.

Part 7: Game UI & Immersive Interfaces

7.1 Diegetic vs. Non-Diegetic UI

Diegetic: UI that exists within the game world (a holographic HUD inside a helmet visor, a health bar on a character). Creates immersion.
Non-diegetic: Traditional overlay UI that floats above the world. Familiar and legible, but breaks fiction.

Choose deliberately. Mixed approaches require strong thematic justification.

7.2 Unified Thematics

Define a visual "world", a set of recurring motifs (shape language, texture, color temperature, typographic character), and enforce it across every element: icons, typography, backgrounds, particle effects, and transitions. If the UI could be lifted out and placed in a different product without looking wrong, it isn't themed.

7.3 Platform Adaptation

Pointer interfaces: Support precision, density, and keyboard shortcuts. Small targets are acceptable.
Touch interfaces: Minimum 44×44pt touch targets. Simplified layouts. Remove affordances that assume hover states.

7.4 Information Speed

In high-intensity contexts, layout must allow the user to extract critical information in milliseconds without conscious eye movement. Proximity encodes meaning: a bar next to a name reads as "health"; a counter next to a bar reads as "progress." Design these relationships deliberately.

About