ply-engine

name	ply-engine
description	Complete implementation and design guide for Ply. Use this skill whenever a task involves ply-engine APIs, plyx workflows, or building UI in Rust with Ply.

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/.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:

1. Responsiveness: Interactions must feel immediate and fluid. Latency in motion reads as lag even when performance is fine.
2. Intention: Motion should guide focus; toward a key action, toward new content, away from what just resolved.
3. Awareness: Elements should behave differently based on their position and context on screen. Motion is spatial.
4. Consistency: Repeated motion patterns build familiarity. Users learn interface "physics".
5. 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.