Ply Engine

Ply Engine

This part is the ultimate guide for writing Ply applications.

Part 1: Non-Negotiable Rules

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

use ply_engine::prelude::*;

3. Respect feature gates. If an API requires a feature, make sure the feature is enabled before using it.
4. 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.

5. Prefer explicit IDs for interactive elements and list items.
6. Every element should have explicit sizing configured.
7. 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/<font>.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.