### Full Application Setup with Ply Engine

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/configuration.md

This example demonstrates the complete setup of a Ply Engine application. It covers initialization, configuration of debug mode, element count, and text measurement, followed by the main application loop for building and rendering the UI. Includes examples of text input, buttons, and a modal dialog.

```rust
use ply_engine::{Ply, prelude::*};

#[macroquad::main("My Application")]
async fn main() {
    // Initialize
    let font = &my_font_asset();
    let mut ply = Ply::new(font).await;
    
    // Configure
    ply.set_debug_mode(cfg!(debug_assertions));
    ply.max_element_count(5000);
    ply.set_measure_text_function(my_text_measure_fn);
    
    // Application state
    let mut input_text = String::new();
    let mut show_modal = false;
    
    // Main loop
    loop {
        let mut ui = ply.begin();
        
        // Build UI tree
        build_main_window(&mut ui, &mut input_text, &mut show_modal, &ply);
        
        // Render
        ply.show(|cmd| {
            handle_custom_render_commands(cmd);
        }).await;
    }
}

fn build_main_window(
    ui: &mut Ui,
    input_text: &mut String,
    show_modal: &mut bool,
    ply: &Ply,
) {
    ui.element()
        .width(grow!())
        .height(grow!())
        .layout(|l| l
            .direction(LayoutDirection::TopToBottom)
            .padding(Padding::all(20))
            .gap(16)
        )
        .children(|ui| {
            // Title
            ui.text("My App", |t| t.font_size(32).color(0x333333));
            
            // Input
            ui.element()
                .id("text_input")
                .width(grow!())
                .height(fixed!(40.0))
                .text_input(|t| t
                    .placeholder("Enter text...")
                    .font_size(14)
                )
                .empty();
            
            // Button
            ui.element()
                .id("submit_btn")
                .width(fixed!(120.0))
                .height(fixed!(40.0))
                .background_color(0x4488DD)
                .layout(|l| l.align(AlignX::CenterX, AlignY::CenterY))
                .children(|ui| {
                    ui.text("Submit", |t| t.font_size(14).color(0xFFFFFF));
                });
            
            if ply.is_just_pressed("submit_btn") {
                *show_modal = true;
            }
        });
    
    if *show_modal {
        build_modal(ui, ply, show_modal);
    }
}

fn build_modal(ui: &mut Ui, ply: &Ply, show_modal: &mut bool) {
    ui.element()
        .width(grow!())
        .height(grow!())
        .background_color(Color::rgba(0.0, 0.0, 0.0, 128.0))
        .floating(|f| f.attach_root().z_index(100)) 
        .empty();
    
    ui.element()
        .width(fixed!(300.0))
        .height(fixed!(200.0))
        .floating(|f| f
            .attach_root()
            .anchor((AlignX::CenterX, AlignY::CenterY), (AlignX::CenterX, AlignY::CenterY))
            .z_index(101)
        )
        .background_color(0xFFFFFF)
        .corner_radius(8.0)
        .layout(|l| l
            .direction(LayoutDirection::TopToBottom)
            .padding(Padding::all(20))
            .gap(12)
        )
        .children(|ui| {
            ui.text("Confirmation", |t| t.font_size(18));
            ui.text("Are you sure?", |t| t.font_size(14).color(0x666666));
            
            ui.element()
                .width(grow!())
                .layout(|l| l.direction(LayoutDirection::LeftToRight).gap(8))
                .children(|ui| {
                    ui.element()
                        .id("ok_btn")
                        .width(grow!())
                        .height(fixed!(36.0))
                        .background_color(0x4488DD)
                        .empty();
                    
                    ui.element()
                        .id("cancel_btn")
                        .width(grow!())
                        .height(fixed!(36.0))
                        .background_color(0xCCCCCC)
                        .empty();
                });
        });
    
    if ply.is_just_pressed("ok_btn") {
        *show_modal = false;
        // Handle confirmation
    }
    if ply.is_just_pressed("cancel_btn") {
        *show_modal = false;
    }
}

```

--------------------------------

### HTTP GET Request Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Initiates an HTTP GET request to a specified URL. Configuration options for headers and body can be provided.

```Rust
net::get(id, url, |HttpConfig| ...)
```

--------------------------------

### Padding Creation Examples

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Demonstrates various methods for creating Padding instances. These examples show how to set uniform padding, individual side paddings, and horizontal/vertical paddings.

```rust
Padding::all(16)
```

```rust
Padding::new(10, 20, 15, 25)
```

```rust
Padding::horizontal(12)
```

```rust
Padding::vertical(8)
```

--------------------------------

### Install and Initialize Ply

Source: https://github.com/thereddeveloper/ply-engine/blob/main/README.md

Use cargo to install the plyx CLI tool and then initialize a new project.

```bash
cargo install plyx
plyx init
```

--------------------------------

### Grow Weight Distribution Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/layout.md

Demonstrates how elements with `Grow` sizing distribute remaining space proportionally based on their weights. This example assumes a 600px container width.

```rust
// Example: 600px container
ui.element().layout(|l| l.direction(LayoutDirection::LeftToRight))
    .children(|ui| {
        ui.element().width(fixed!(100.0)).empty();      // 100px
        ui.element().width(grow!(0.0, f32::MAX, 1.0)).empty(); // 250px (1/3 of 500)
        ui.element().width(grow!(0.0, f32::MAX, 2.0)).empty(); // 500px (2/3 of 500)
    });
```

--------------------------------

### Sizing Enum Examples

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Illustrates common ways to instantiate the Sizing enum for different layout behaviors. These examples show how to specify fixed sizes, growth parameters, and percentage-based sizing.

```rust
Sizing::Fixed(100.0)
```

```rust
Sizing::Grow(0.0, f32::MAX, 1.0)
```

```rust
Sizing::Percent(0.5)
```

```rust
Sizing::Fit(50.0, 200.0)
```

--------------------------------

### CornerRadius Creation Examples

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Shows different ways to initialize a CornerRadius. Examples include creating a default (zero) radius, setting all corners to a uniform value using `into()`, and specifying individual corners.

```rust
CornerRadius::default()
```

```rust
let cr: CornerRadius = 10.0.into();
```

```rust
let cr: CornerRadius = (10.0, 10.0, 0.0, 0.0).into();
```

--------------------------------

### WebSocket Connection Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Establishes a WebSocket connection to a specified URL. Configuration options for headers and security can be provided.

```Rust
net::ws_connect(id, url, |WsConfig| ...)
```

--------------------------------

### HTTP POST Request Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Initiates an HTTP POST request. Configuration options for headers and body can be provided.

```Rust
net::post(...)
```

--------------------------------

### HTTP PUT Request Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Initiates an HTTP PUT request. Configuration options for headers and body can be provided.

```Rust
net::put(...)
```

--------------------------------

### ShaderAsset Source Variant Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/shaders-and-effects.md

Example of creating a ShaderAsset using GLSL fragment source code. Ensure the GLSL version and precision are compatible with the target environment.

```rust
let my_shader = ShaderAsset::Source {
    file_name: "wave.glsl",
    fragment: r#"#version 100
        precision lowp float;
        
        varying vec2 uv;
        uniform sampler2D Texture;
        uniform float time;
        
        void main() {
            vec2 wave_uv = uv + vec2(sin(uv.y * 10.0 + time), 0.0) * 0.1;
            gl_FragColor = texture2D(Texture, wave_uv);
        }
    "#,
};
```

--------------------------------

### Dropdown Menu Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/alignment-and-positioning.md

Creates a dropdown menu that appears when a button is pressed. The menu is anchored to the button and floats below it.

```rust
ui.element()
    .id("dropdown_button")
    .width(fixed!(150.0))
    .height(fixed!(36.0))
    .children(|ui| {
        ui.text("Options", |t| t.font_size(14));
        
        if ui.pressed() {
            ui.element()
                .id("dropdown_menu")
                .width(fixed!(150.0))
                .floating(|f| f
                    .anchor(
                        (AlignX::Left, AlignY::Top),
                        (AlignX::Left, AlignY::Bottom)
                    )
                    .offset((0.0, 4.0))
                    .z_index(10)
                )
                .background_color(0xFFFFFF)
                .border(|b| b.color(0xCCCCCC).all(1))
                .children(|ui| {
                    ui.text("Option 1", |t| t.font_size(14));
                    ui.text("Option 2", |t| t.font_size(14));
                });
        }
    });
```

--------------------------------

### Create Default TextConfig

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/color-and-text.md

Instantiate a TextConfig with default settings. This is the starting point for customizing text styles.

```rust
let config = TextConfig::new();
```

--------------------------------

### Accessibility Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Configure accessibility properties for UI elements, including button labels, tab indices, and focus navigation.

```rust
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));  });
```

--------------------------------

### Tooltip Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/alignment-and-positioning.md

Displays a tooltip when the user hovers over a button. The tooltip is anchored to the center of the button and floats above it.

```rust
ui.element()
    .id("button_with_tooltip")
    .width(fixed!(100.0))
    .height(fixed!(36.0))
    .children(|ui| {
        ui.text("Hover me", |t| t.font_size(14));
        
        if ui.hovered() {
            ui.element()
                .floating(|f| f
                    .anchor(
                        (AlignX::CenterX, AlignY::Top),
                        (AlignX::CenterX, AlignY::Bottom)
                    )
                    .offset((0.0, 8.0))
                    .z_index(999)
                )
                .background_color(0x333333)
                .corner_radius(4.0)
                .children(|ui| {
                    ui.text(
                        "This is a tooltip!",
                        |t| t.font_size(12).color(0xFFFFFF)
                    );
                });
        }
    });
```

--------------------------------

### Scroll to Position Examples

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/overflow-and-scrolling.md

Demonstrates how to programmatically scroll a container to the top, middle, or bottom by setting its scroll position.

```rust
// Scroll to top
ply.set_scroll_position("list", (0.0, 0.0));

// Scroll to middle
if let Some(data) = ply.scroll_container_data("list") {
    let middle_y = data.max_offset.y / 2.0;
    ply.set_scroll_position("list", (0.0, middle_y));
}

// Scroll to bottom
if let Some(data) = ply.scroll_container_data("list") {
    ply.set_scroll_position("list", (0.0, data.max_offset.y));
}
```

--------------------------------

### Screen Reader Announcement Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/accessibility.md

Configure element labels and descriptions for screen readers. Ensure elements have clear and concise labels and descriptive text for better accessibility.

```rust
ui.element()
    .id("download_btn")
    .accessibility(|a| a
        .button("Download Report")
        .description("Download the latest monthly report (PDF, 2.5 MB)")
    )
    .on_press(|_, _| {
        start_download();
    })
    .empty();
```

--------------------------------

### HTTP DELETE Request Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Initiates an HTTP DELETE request. Configuration options for headers and body can be provided.

```Rust
net::delete(...)
```

--------------------------------

### Modal Dialog Example (Root-Attached)

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/alignment-and-positioning.md

Implements a modal dialog that is attached to the root of the UI. It includes a semi-transparent backdrop and the modal content itself, both centered on the screen.

```rust
let show_modal = true;

if show_modal {
    // Semi-transparent backdrop
    ui.element()
        .width(grow!())
        .height(grow!())
        .background_color(Color::rgba(0.0, 0.0, 0.0, 128.0))
        .floating(|f| f
            .attach_root()
            .z_index(100)
        )
        .empty();
    
    // Modal content
    ui.element()
        .width(fixed!(400.0))
        .height(fixed!(300.0))
        .floating(|f| f
            .attach_root()
            .anchor((AlignX::CenterX, AlignY::CenterY), (AlignX::CenterX, AlignY::CenterY))
            .z_index(101)
        )
        .background_color(0xFFFFFF)
        .corner_radius(8.0)
        .border(|b| b.color(0x333333).all(2))
        .layout(|l| l
            .direction(LayoutDirection::TopToBottom)
            .padding(Padding::all(24))
            .gap(16)
        )
        .children(|ui| {
            ui.text("Confirm Action", |t| t.font_size(18));
            ui.text("Are you sure?", |t| t.font_size(14).color(0x666666));
            
            ui.element()
                .width(grow!())
                .layout(|l| l.direction(LayoutDirection::LeftToRight).gap(8))
                .children(|ui| {
                    ui.element()
                        .width(grow!())
                        .background_color(0x4488DD)
                        .empty();
                    ui.element()
                        .width(grow!())
                        .background_color(0xCCCCCC)
                        .empty();
                });
        });
}
```

--------------------------------

### ShaderAsset Compiled Variant Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/shaders-and-effects.md

Example of creating a ShaderAsset using pre-compiled shader bytecode. This requires the 'shader-build' feature to compile GLSL to bytecode at build time.

```rust
let compiled_shader = ShaderAsset::Compiled {
    file_name: "precompiled",
    vertex: include_bytes!("../shaders/vertex.spv"),
    fragment: include_bytes!("../shaders/fragment.spv"),
};
```

--------------------------------

### Get and Use BoundingBox

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Illustrates how to retrieve an element's bounding box and access its position and size properties. Requires an element ID.

```rust
if let Some(bbox) = ply.bounding_box("element_id") {
    println!("Position: ({}, {})", bbox.x, bbox.y);
    println!("Size: {}x{}", bbox.width, bbox.height);
}
```

--------------------------------

### Start a New Frame with Ui Handle

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Begins a new frame for UI building and returns a `Ui` handle. This must be called once per frame before adding elements. It automatically updates layout, timing, and pointer state.

```rust
loop {
    let mut ui = ply.begin();
    
    ui.element()
        .width(grow!())
        .height(grow!())
        .children(|ui| {
            ui.text("Frame content", |t| t.font_size(16));
        });
    
    ply.show(|_| {}).await;
}
```

--------------------------------

### Create a UI element with Ply

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Use `Ui::element()` to start building a new UI element. Configure its properties like size, color, and children using the returned `ElementBuilder`.

```rust
let mut ui = ply.begin();
ui.element()
    .width(fixed!(100.0))
    .height(fixed!(50.0))
    .background_color(0xFF0000)
    .children(|ui| {
        ui.text("Click me", |t| t.font_size(16));
    });
```

--------------------------------

### Text Input with Styling and Cursor Helpers

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Implement a multiline text input field with drag selection and custom movement behavior. This example also shows how to dynamically update text content, apply styling, and manage cursor position.

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

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);
}
```

--------------------------------

### Set Text Opacity

Source: https://github.com/thereddeveloper/ply-engine/blob/main/text-styling.md

Use the `opacity` property with a float value between 0.0 and 1.0 to control text transparency. Example sets 50% opacity.

```text
{opacity=0.5|50% Transparent Text}
```

--------------------------------

### Floating Tooltip Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Create a tooltip that appears when hovering over a target element. The tooltip is positioned relative to its parent and can be offset.

```rust
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));
        });
    }
  });
```

--------------------------------

### plyx skill

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Manages skills, either printing the bundled skill text to stdout or installing it to a local directory.

```APIDOC
## plyx skill

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

--------------------------------

### plyx apk command

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Build an Android APK. Supports Docker or native builds, with options to install the APK and run in non-interactive mode.

```bash
plyx apk [--native] [--install] [--auto]
```

--------------------------------

### Make HTTP Request (Net Feature)

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/configuration.md

Initiates a non-blocking HTTP GET request. Results are handled via a completion callback. Ensure the 'net' feature is enabled.

```rust
#[cfg(feature = "net")]
use ply_engine::net;

// Make request (doesn't block)
net::http::request(
    net::http::Method::Get,
    "https://api.example.com/data",
    None,
    None,
    |result| {
        match result {
            Ok(response) => println!("Status: {}", response.status),
            Err(err) => println!("Error: {}", err),
        }
    },
);
```

--------------------------------

### Popover Example (Element-Attached)

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/alignment-and-positioning.md

Shows a popover that is attached to a specific UI element. The popover appears when the trigger element is pressed and is anchored below its center.

```rust
ui.element()
    .id("trigger")
    .width(fixed!(100.0))
    .height(fixed!(40.0))
    .background_color(0x4488DD)
    .empty();

if ply.is_pressed("trigger") {
    ui.element()
        .width(fixed!(200.0))
        .floating(|f| f
            .attach_id("trigger")
            .anchor(
                (AlignX::CenterX, AlignY::Top),
                (AlignX::CenterX, AlignY::Bottom)
            )
            .offset((0.0, 12.0))
            .z_index(50)
        )
        .background_color(0xFFFFFF)
        .border(|b| b.color(0x999999).all(1))
        .children(|ui| {
            ui.text("Popover Content", |t| t.font_size(14));
        });
}
```

--------------------------------

### GLSL Fragment Shader Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/shaders-and-effects.md

A GLSL fragment shader demonstrating texture sampling, distortion using sine waves, and outputting the final color. Supports GLSL 100.

```glsl
#version 100
precision lowp float;

// Built-in uniforms (automatically provided)
uniform sampler2D Texture;      // Element texture
uniform vec2 uv_offset;         // UV offset for scroll
uniform vec2 viewport_size;     // Viewport dimensions

// Varyings (from vertex shader)
varying vec2 uv;                // Texture UV coordinates
varying vec2 position;          // Fragment position
varying vec4 color;             // Vertex color

// User-defined uniforms (set via .uniform())
uniform float time;
uniform vec3 custom_color;

void main() {
    // Sample texture at UV
    vec4 tex = texture2D(Texture, uv);
    
    // Apply effects
    vec2 wave = sin(uv * 10.0 + time) * 0.1;
    vec4 distorted = texture2D(Texture, uv + wave);
    
    // Output color
    gl_FragColor = distorted;
}
```

--------------------------------

### Render to Texture with Custom Shaders

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Utilize `render_to_texture` to create dynamic textures and apply custom shaders for visual effects. This example demonstrates rendering a simple scene to a texture and applying a tint shader with configurable uniforms.

```rust
static TINT_SHADER: ShaderAsset = ShaderAsset::Source {
  file_name: "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();
```

--------------------------------

### Get Selection Range from TextEditState

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/text-input.md

Retrieves the ordered selection range (start, end) if a selection is currently active in the text input.

```rust
if let Some((start, end)) = state.selection_range() {
    println!("Selected: {} to {}", start, end);
}
```

--------------------------------

### Get Selection Range

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Retrieve the current selection range (start and end character indices) within a text input. Returns None if no text is currently selected.

```rust
if let Some((start, end)) = ply.get_selection_range("text_input") {
    println!("Selected: {} to {}", start, end);
}
```

--------------------------------

### Fade Animation Example

Source: https://github.com/thereddeveloper/ply-engine/blob/main/text-styling.md

The 'fade' animation creates an opacity transition. Adjust the 'speed' for how quickly the text fades and 'trail' for the gradient length. A delay can be set before the animation starts.

```ply-engine
{fade_out_id=bar_speed=5|Fade this text out quickly}
```

--------------------------------

### Evaluate Layout and Get Render Commands

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Calculates element positions and sizes after the UI tree is built, returning a vector of render commands. This is useful for custom rendering or debugging.

```rust
let mut ui = ply.begin();
ui.element().width(fixed!(100.0)).height(fixed!(100.0)).empty();
let commands = ply.eval();
for cmd in commands {
    println!("Render: {:?}", cmd.config);
}
```

--------------------------------

### Get and Set Text Selection

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/text-input.md

Retrieve the start and end indices of the currently selected text in an input field, or programmatically set a text selection range. Useful for copy/paste operations or highlighting text.

```rust
if let Some((start, end)) = ply.get_selection_range("email") {
    println!("Selected: {} to {}", start, end);
}

ply.set_selection("email", 0, 10);  // Select first 10 chars
```

--------------------------------

### Float an Element

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/README.md

Configure an element to float, which is useful for tooltips, modals, or dropdowns. This example attaches the element to the root, anchors it to specific alignment points, and sets its z-index.

```rust
ui.element()
    .floating(|f| f
        .attach_root()
        .anchor((AlignX::CenterX, AlignY::CenterY), (AlignX::CenterX, AlignY::CenterY))
        .z_index(100)
    )
    .children(|ui| { /* ... */ });
```

--------------------------------

### Implement a Custom Button Component

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Create a reusable button component using a Rust function that abstracts styling and interaction logic. This example demonstrates dynamic background coloring based on button state.

```rust
fn button(ui: &mut Ui, id: (&str, u32), label: &str, mut on_click: impl FnMut() + 'static) {
  ui.element().id(id).width(fit!()).height(fit!()) 
    .on_press(move |_, _| on_click())
    .accessibility(|a| a.button(label))
    .children(|ui| {
      let bg = if ui.pressed() {
        LIGHT_PRIMARY_COLOR
      } else if ui.hovered() || ui.focused() {
        DARK_PRIMARY_COLOR
      } else {
        PRIMARY_COLOR
      };

      ui.element().width(fit!()).height(fit!()) 
        .background_color(bg)
        .corner_radius(SOME_RADIUS)
        .layout(|l| l.padding(SOME_PADDING).align(CenterX, CenterY))
        .children(|ui| {
          ui.text(label, |t| t.font_size(24).color(0xFFFFFF));
        });
    });
}
```

--------------------------------

### Create and Convert Vector2

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Demonstrates common ways to create Vector2 instances, including direct struct initialization, using a constructor, and converting from a tuple.

```rust
Vector2::new(100.0, 200.0)
```

```rust
Vector2 { x: 50.0, y: 75.0 }
```

```rust
let v: Vector2 = (100.0, 200.0).into();  // From tuple
```

--------------------------------

### plyx init command

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Initialize a new project using the plyx CLI. This command sets up the project structure, selects a Google Font, and configures feature flags.

```bash
plyx init
```

--------------------------------

### Create Color Instances

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Demonstrates various ways to create Color instances, including RGB and RGBA constructors, and conversion from hexadecimal values.

```rust
Color::rgb(255.0, 0.0, 0.0)                // Red
```

```rust
Color::rgba(0.0, 255.0, 0.0, 128.0)        // Semi-transparent green
```

```rust
0xFF0000.into()                            // Red from hex
```

--------------------------------

### Get HTTP Response Status

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Retrieves the HTTP status code from a response.

```Rust
status() -> u16
```

--------------------------------

### plyx completions

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Generates shell completion scripts for various shells, with an option to install them.

```APIDOC
## plyx completions <shell>

### Description
Generates shell completion scripts for various shells, with an option to install them.

- `plyx completions <shell> [--install]`
```

--------------------------------

### Get HTTP Response Body as Bytes

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Retrieves the response body as a byte slice.

```Rust
bytes() -> &[u8]
```

--------------------------------

### Get HTTP Response Body as Text

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Retrieves the response body as a string slice.

```Rust
text() -> &str
```

--------------------------------

### Layout Type Conversions in Rust

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Illustrates creating Sizing, Padding, and CornerRadius instances. Sizing can be fixed, padding can be applied to all sides, and corner radius can be set directly.

```rust
let sizing: Sizing = Sizing::Fixed(100.0);
let padding: Padding = Padding::all(16);
let radius: CornerRadius = 10.0.into();
```

--------------------------------

### Create a Basic UI Element in Rust

Source: https://github.com/thereddeveloper/ply-engine/blob/main/README.md

Demonstrates creating a simple UI element with text using the Ply engine's builder pattern.

```rust
ui.element().width(grow!()).height(grow!())  .background_color(0x262220)  .corner_radius(12.0)  .layout(|l| l.direction(TopToBottom).padding(24))  .children(|ui| {    ui.text("Hello, Ply!", |t| t.font_size(32).color(0xFFFFFF));  });
```

--------------------------------

### Get WebSocket Object

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Retrieves a WebSocket object by its ID, allowing for sending and receiving messages.

```Rust
net::ws(id) -> Option<WebSocket>
```

--------------------------------

### Responsive Image in Layout

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/borders-and-images.md

Demonstrates how to make an image responsive within a parent layout. The image uses `grow!()` for width and `aspect_ratio` to maintain its proportions, fitting within the available space.

```rust
ui.element()
    .width(grow!())
    .height(grow!())
    .layout(|l| l.direction(LayoutDirection::TopToBottom))
    .children(|ui| {
        ui.element()
            .width(grow!())
            .aspect_ratio(16.0 / 9.0)
            .image(&HEADER_IMAGE)
            .empty();
        
        ui.element()
            .width(grow!())
            .height(grow!())
            .background_color(0xFFFFFF)
            .layout(|l| l.padding(Padding::all(20)))
            .children(|ui| {
                ui.text("Content", |t| t.font_size(16));
            });
    });
```

--------------------------------

### Getting Text Value

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/text-input.md

Retrieves the current text value of a specified text input field.

```APIDOC
## Getting Text Value

Retrieves the current text value of a specified text input field.

### Method Signature
```rust
ply.get_text_value("field_name") -> String
```

### Parameters
*   **field_name** (string) - Required - The name of the text input field.

### Request Example
```rust
let text = ply.get_text_value("email");
println!("Current input: {}", text);
```

### Response
*   Returns the current text content of the input field as a String.
```

--------------------------------

### plyx completions command

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Generate shell completion scripts for plyx. Supports installation for various shells.

```bash
plyx completions <shell> [--install]
```

--------------------------------

### Ply::begin

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Initiates a new frame, returning a `Ui` handle for constructing the element tree. It automatically updates layout, timing, and input states.

```APIDOC
## Ply::begin

### Description
Starts a new frame and returns a `Ui` handle for building the element tree.

Must be called once per frame before adding any elements. Automatically updates layout dimensions, timing, and pointer state from macroquad.

### Method
`Ply::begin() -> Ui<'_, CustomElementData>`

### Parameters
None

### Request Example
```rust
loop {
    let mut ui = ply.begin();
    
    ui.element()
        .width(grow!())
        .height(grow!())
        .children(|ui| {
            ui.text("Frame content", |t| t.font_size(16));
        });
    
    ply.show(|_| {}).await;
}
```

### Response
#### Success Response (Ui<'_, CustomElementData>)
- `Ui<'_, CustomElementData>` - UI builder handle for this frame

#### Response Example
None
```

--------------------------------

### Get Bounding Box

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Retrieve the position and dimensions of a UI element. Returns None if the element does not exist.

```rust
if let Some(bbox) = ply.bounding_box("my_rect") {
    println!("Position: ({}, {}), Size: {}x{}", 
        bbox.x, bbox.y, bbox.width, bbox.height);
}
```

--------------------------------

### TextConfig::new()

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/color-and-text.md

Creates a new TextConfig with default settings.

```APIDOC
## TextConfig::new()

### Description
Creates a default text configuration.

### Returns
`Self` — Text config with defaults
```

--------------------------------

### Get Currently Focused Element

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Returns the ID of the currently focused element, or None if no element is focused.

```rust
if let Some(focused_id) = ply.focused_element() {
    println!("Focused: {:?}", focused_id);
}
```

--------------------------------

### Desktop Initialization (macroquad)

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/configuration.md

Initialize the Ply engine for desktop applications using macroquad. Handles window, input, and accessibility automatically.

```rust
#[macroquad::main("App Title")]
async fn main() {
    let font = &my_font_asset();
    let mut ply = Ply::new(font).await;
    
    loop {
        let mut ui = ply.begin();
        // Build UI
        ply.show(|_| {}).await;
    }
}
```

--------------------------------

### HTTP Requests

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/configuration.md

Make non-blocking HTTP requests and handle results via callbacks. Supports GET requests.

```APIDOC
## HTTP Requests

### Description
Make non-blocking HTTP requests and handle results via callbacks. Supports GET requests.

### Method
GET

### Endpoint
https://api.example.com/data

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```rust
#[cfg(feature = "net")]
use ply_engine::net;

net::http::request(
    net::http::Method::Get,
    "https://api.example.com/data",
    None,
    None,
    |result| {
        match result {
            Ok(response) => println!("Status: {}", response.status),
            Err(err) => println!("Error: {}", err),
        }
    },
);
```

### Response
#### Success Response (200)
- **status** (integer) - The HTTP status code of the response.

#### Response Example
```json
{
  "status": 200
}
```
```

--------------------------------

### Loading Images

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/borders-and-images.md

Demonstrates various methods for loading image assets, including from embedded bytes, file paths at runtime, and through a file dialog using the 'storage' feature.

```rust
// From embedded bytes
const PNG_DATA: &[u8] = include_bytes!("../assets/image.png");

// From file path (runtime)
#[cfg(not(target_arch = "wasm32"))]
let texture = macroquad::texture::load_texture("assets/image.png").await;

// From file dialog (requires `storage` feature)
#[cfg(feature = "storage")]
let texture = storage::load_texture("user_selected_image.png").await;
```

--------------------------------

### Load and Play Sound (Audio Feature)

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/configuration.md

Loads a sound file and provides methods to play, set volume, and loop it. Ensure the 'audio' feature is enabled.

```rust
#[cfg(feature = "audio")]
use ply_engine::audio;

// Load sound
let sound = audio::load_sound("audio/effect.wav").await;

// Play
sound.play();
sound.set_volume(0.8);
sound.set_looped(true);
```

--------------------------------

### Create New Storage Instance

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Initializes a new storage instance at the specified path. This operation is asynchronous.

```Rust
Storage::new(path).await
```

--------------------------------

### plyx init

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Initializes a new project, allowing selection of a Google Font and feature flags. It generates essential project files like Cargo.toml, src/main.rs, and optionally build.rs and shader files.

```APIDOC
## plyx init

### Description
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`
```

--------------------------------

### Networking HTTP Methods

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Functions for making HTTP requests (GET, POST, PUT, DELETE) and retrieving request status.

```APIDOC
## HTTP Methods

### `net::get(id, url, |HttpConfig| ...)`
Performs an HTTP GET request.

### `net::post(...)`
Performs an HTTP POST request.

### `net::put(...)`
Performs an HTTP PUT request.

### `net::delete(...)`
Performs an HTTP DELETE request.

### `net::request(id) -> Option<Request>`
Retrieves a request object by its ID.
```

--------------------------------

### Get HTTP Response

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Retrieves the response from an HTTP request. This can be an error or a successful response containing status, text, and bytes.

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

--------------------------------

### Ply Engine Application Entry Point

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/README.md

This is the typical entry point for a Ply Engine application using Macroquad. It initializes the engine, enters a loop to handle UI updates, and displays the UI.

```rust
use ply_engine::{Ply, prelude::*};

#[macroquad::main("App")]
async fn main() {
    let mut ply = Ply::new(&my_font).await;
    
    loop {
        let mut ui = ply.begin();
        ui.element().width(grow!()).height(grow!()).empty();
        ply.show(|_| {}).await;
    }
}
```

--------------------------------

### ShaderBuild API for build.rs

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Configure the shader build process in build.rs. Specify source and output directories, slang compiler path, and custom file type handlers.

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

--------------------------------

### Create Ply with Default Font

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/configuration.md

Initializes the Ply engine with a default font. This is the standard way to start a new application.

```rust
use ply_engine::{Ply, prelude::*};

#[macroquad::main("My App")]
async fn main() {
    let default_font = &text_font();  // Provide your font asset
    let mut ply = Ply::new(default_font).await;
    
    loop {
        let mut ui = ply.begin();
        ui.element().width(grow!()).height(grow!()).empty();
        ply.show(|_| {}).await;
    }
}
```

--------------------------------

### plyx apk

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Builds an Android APK. Supports Docker or native builds, with options to install the APK and run in non-interactive mode.

```APIDOC
## plyx apk

### Description
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`
```

--------------------------------

### plyx web command

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Build a release WebAssembly version of the project. Outputs to build/web/ including app.wasm, index.html, and ply_bundle.js.

```bash
plyx web
```

--------------------------------

### Text Input State

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Methods for getting and setting text content, cursor position, and selection range for text input elements.

```APIDOC
## Ply::get_text_value

### Description
Returns the text content of a text input element.

### Method
`get_text_value`

### Parameters
#### Path Parameters
- **id** (`impl Into<Id>`) - Required - Text input element ID

### Returns
- `&str` - Text content (empty string if not a text input)

### Request Example
```rust
let username = ply.get_text_value("username_field");
println!("Username: {}", username);
```
```

```APIDOC
## Ply::set_text_value

### Description
Sets the text content of a text input element.

### Method
`set_text_value`

### Parameters
#### Path Parameters
- **id** (`impl Into<Id>`) - Required - Text input element ID
- **value** (`&str`) - Required - New text content

### Request Example
```rust
ply.set_text_value("username_field", "alice");
```
```

```APIDOC
## Ply::get_cursor_pos

### Description
Returns the cursor position (in characters) in a text input.

### Method
`get_cursor_pos`

### Parameters
#### Path Parameters
- **id** (`impl Into<Id>`) - Required - Text input element ID

### Returns
- `usize` - 0-based character index (0 = before first char)

### Request Example
```rust
let pos = ply.get_cursor_pos("text_input");
```
```

```APIDOC
## Ply::set_cursor_pos

### Description
Sets the cursor position and clears selection.

### Method
`set_cursor_pos`

### Parameters
#### Path Parameters
- **id** (`impl Into<Id>`) - Required - Text input element ID
- **pos** (`usize`) - Required - Character index (clamped to text length)

### Request Example
```rust
ply.set_cursor_pos("text_input", 5);
```
```

```APIDOC
## Ply::get_selection_range

### Description
Returns the selection range (start, end) if active.

### Method
`get_selection_range`

### Parameters
#### Path Parameters
- **id** (`impl Into<Id>`) - Required - Text input element ID

### Returns
- `Option<(usize, usize)>` - (anchor, cursor) if selected, else None

### Request Example
```rust
if let Some((start, end)) = ply.get_selection_range("text_input") {
    println!("Selected: {} to {}", start, end);
}
```
```

```APIDOC
## Ply::set_selection

### Description
Sets the selection range for a text input.

### Method
`set_selection`

### Parameters
#### Path Parameters
- **id** (`impl Into<Id>`) - Required - Text input element ID
- **anchor** (`usize`) - Required - Selection start (character index)
- **cursor** (`usize`) - Required - Selection end (character index)

### Request Example
```rust
ply.set_selection("text_input", 0, 10);
```
```

--------------------------------

### Audio Methods

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Functions for loading and playing sounds, with options for playback parameters and volume control.

```APIDOC
## Audio Methods

### `load_sound(path).await`
Loads a sound from a file path.

### `load_sound_from_bytes(bytes).await`
Loads a sound from a byte slice.

### `play_sound_once(&sound)`
Plays a sound once.

### `play_sound(&sound, PlaySoundParams { .. })`
Plays a sound with specified parameters.

### `stop_sound(&sound)`
Stops the playback of a sound.

### `set_sound_volume(&sound, volume)`
Sets the playback volume for a sound.
```

--------------------------------

### Get Cursor Position

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Obtain the current cursor position within a text input field. The position is a 0-based character index.

```rust
let pos = ply.get_cursor_pos("text_input");
```

--------------------------------

### Get IDs of Elements Under Pointer

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/ply.md

Returns a Z-sorted list of all elements the pointer is currently over. Elements are ordered by Z-index from back to front.

```rust
let hover_stack = ply.pointer_over_ids();
for id in hover_stack {
    println!("Hovering: {:?}", id);
}
```

--------------------------------

### Create Dimensions

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/types.md

Shows common methods for creating Dimensions instances, including using a constructor or direct struct initialization.

```rust
Dimensions::new(800.0, 600.0)
```

```rust
Dimensions { width: 1920.0, height: 1080.0 }
```

--------------------------------

### Sizing Macros

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

APIs for defining how elements should size themselves within a layout.

```APIDOC
## Sizing Macros

### `fit!()`

- `fit!()`
- `fit!(min, max)`
- `fit!(min: value, max: value)`

### `grow!()`

- `grow!()`
- `grow!(min, max, weight)`
- `grow!(min: value, max: value, weight: value)`

### `fixed!()`

- `fixed!(px: value)`

### `percent!()`

- `percent!(0.0..=1.0)`

**Notes:**
- `grow!(weight: 0.0)` behaves as `fit` internally.
- Negative grow weights are invalid.
```

--------------------------------

### Get HTTP Request Object

Source: https://github.com/thereddeveloper/ply-engine/blob/main/SKILL.md

Retrieves an HTTP request object by its ID, allowing for further interaction like checking the response or cancelling.

```Rust
net::request(id) -> Option<Request>
```

--------------------------------

### Get Selected Text from TextEditState

Source: https://github.com/thereddeveloper/ply-engine/blob/main/_autodocs/api-reference/text-input.md

Returns a string slice of the currently selected text. Returns an empty string if no text is selected.

```rust
let selected = state.selected_text();
```