Makepad 2.0 Performance & Debugging Skill

1. Overview

Makepad 2.0 uses a unique rendering pipeline combined with the Splash script VM. Performance depends on understanding three critical subsystems:

1. Draw Batching - How Makepad groups GPU draw calls and why

   new_batch: true

   matters
2. Garbage Collection - The Splash VM's mark-sweep GC with per-type-bucket thresholds
3. Render Triggers - The

   on_render

   /

   .render()

   system that controls when sub-trees rebuild

Unlike traditional retained-mode UI frameworks, Makepad uses an immediate-mode-inspired draw pipeline where widgets emit draw commands into a sorted batch list. Understanding this pipeline is essential for diagnosing invisible text, flickering, and performance regressions.

2. Draw Batching System

How It Works

Makepad automatically batches consecutive draw calls that use the same shader into a single GPU draw call. This is a major performance optimization, but it has a critical side effect: draw order can be surprising.

Draw pipeline (simplified):

Widget tree:          GPU batches (default):

  View (bg shader)      Batch 1: all bg shaders
    Label (text)   -->  Batch 2: all text shaders
  View (bg shader)
    Label (text)        Result: ALL backgrounds draw first,
                                then ALL text draws second

When a View has

show_bg: true

new_batch: true

Setting

new_batch: true

ViewOptimize::DrawList

// PROBLEM: Label text is invisible - batched behind the background
RoundedView{
    width: Fill height: Fit
    draw_bg.color: #1e1e2e
    Label{text: "This text is INVISIBLE"}
}

// FIX: new_batch ensures background draws before text
RoundedView{
    width: Fill height: Fit
    new_batch: true
    draw_bg.color: #1e1e2e
    Label{text: "This text is VISIBLE"}
}

When

new_batch: true

Is Required

show_bg: true

show_bg

Hover Effects and

new_batch

This is the number one mistake with hoverable list items. When a View has

show_bg: true

#0000

// CORRECT: Hoverable item with new_batch
let HoverItem = View{
    width: Fill height: Fit
    new_batch: true
    show_bg: true
    draw_bg +: {
        color: uniform(#0000)
        color_hover: uniform(#fff2)
        hover: instance(0.0)
    }
    animator: Animator{
        hover: {
            default: {
                from: {all: Forward{duration: 0.1}}
                apply: {draw_bg: {hover: 0.0}}
            }
            on: {
                from: {all: Forward{duration: 0.1}}
                apply: {draw_bg: {hover: 1.0}}
            }
        }
    }
    label := Label{text: "item" draw_text.color: #fff}
}

// Parent container of hover items also needs new_batch
RoundedView{
    flow: Down height: Fit new_batch: true
    draw_bg.color: #2a2a3d
    draw_bg.border_radius: 8.0
    HoverItem{label.text: "First item"}
    HoverItem{label.text: "Second item"}
}

ViewOptimize Internals

The

new_batch

texture_caching

ViewOptimize

ViewOptimize::None      - Default. No special draw ordering.
ViewOptimize::DrawList  - Created by new_batch: true. Starts a new DrawList2d.
ViewOptimize::Texture   - Created by texture_caching: true. Renders to offscreen texture.

Priority:

texture_caching

new_batch

3. Texture Caching

How It Works

Setting

texture_caching: true

// Cache a complex but rarely-changing sidebar
sidebar := View{
    width: 280 height: Fill
    texture_caching: true
    flow: Down spacing: 4
    // ... many child widgets ...
}

Pre-Built Cached Views

Makepad provides pre-styled cached views:

CachedView

CachedRoundedView

When to Use Texture Caching

Good candidates:

• Complex static sidebars or toolbars that rarely change
• Large widget sub-trees with many nested backgrounds and text
• Decorative panels with shader effects

Bad candidates:

• Frequently updating views (e.g., animation targets, live data)
• Small simple views (overhead exceeds benefit)
• Views that contain scrolling content (CachedView wraps the whole content, not the viewport)

Trade-offs

4. Garbage Collection (mod.gc)

Architecture

The Splash VM uses a mark-and-sweep garbage collector with isolated heaps for different value types:

Heap Layout:
  +-- Objects (ScriptObject)    -- Primary allocation type
  +-- Arrays  (ScriptArray)     -- Typed arrays and value arrays
  +-- Strings (ScriptString)    -- Interned strings
  +-- Pods    (ScriptPod)       -- Pod values (vec2, vec3, vec4, etc.)
  +-- Handles (ScriptHandle)    -- Native Rust handles
  +-- Regexes (ScriptRegex)     -- Interned regex patterns

Automatic GC Triggering

The GC uses a growth-based heuristic similar to Lua and V8:

• Growth Factor: 2x - GC triggers when any heap category doubles since last GC
• Minimum Thresholds (to avoid thrashing on small heaps):

GC triggers when:

current_count >= MIN_THRESHOLD AND current_count >= last_gc_count * 2

Script API

mod.gc.run()

mod.gc.run_status()

GC 142us: obj[S:1200 A:340 R:89] arr[S:45 A:12 R:3] str[S:890 A:120 R:15] ...

Where S=static (permanent), A=alive (survived), R=removed (freed).

mod.gc.set_static(value)

• Are never collected by GC (permanent)
• Are skipped during GC mark phase (faster GC traversal)
• Cannot be un-marked (irreversible within the VM lifetime)

mod.gc.dump_tag(value)

Best Practices

Pattern: Static UI Trees

For large, stable UI tree definitions (like a Dock with many tabs), mark them as static immediately after definition. This is the standard pattern used in the Studio and UIZoo examples:

// Define a large widget tree
let AppDock = Dock{
    // ... tabs, splitters, content templates ...
    TabEditor := TabEditor{}
    TabFileTree := TabFileTree{}
    TabSettings := TabSettings{}
}

// Mark the entire tree as static - it will never be GC'd
mod.gc.set_static(AppDock)

// Run GC immediately to clean up any temporaries from tree construction
mod.gc.run()

// Now start the app
startup() do #(App::script_component(vm)){
    ui: Root{
        main_window := Window{
            body +: {
                // ... use AppDock here ...
            }
        }
    }
}

Pattern: Dynamic Content

For dynamic content (lists, user-generated items, chat messages), let the automatic GC handle cleanup:

// Dynamic data - no need to call mod.gc manually
var todos = []

fn add_todo(text) {
    todos.push({text: text done: false})
    ui.main_view.render()
    // Automatic GC will clean up old unreachable objects
}

fn delete_todo(index) {
    todos.splice(index, 1)
    ui.main_view.render()
    // Old todo object becomes unreachable, will be collected automatically
}

Pattern: Periodic Manual GC for Long-Running Apps

For apps that create and destroy many objects (e.g., chat applications with streaming responses):

var message_count = 0

fn on_new_message(msg) {
    messages.push(msg)
    message_count += 1

    // Every 100 messages, run GC to reclaim temporary parsing objects
    if message_count % 100 == 0 {
        mod.gc.run()
    }

    ui.message_list.render()
}

GC Mark Phase Details

The mark phase traverses from roots:

1. Type check prototypes
2. Type defaults objects
3. Pod type defaults and objects
4. Root objects (held by Rust via

   ScriptObjectRef

   )
5. Root arrays (held by Rust via

   ScriptArrayRef

   )
6. Root handles (held by Rust via

   ScriptHandleRef

   )
7. Thread stacks (all live values on VM execution stacks)
8. Thread scopes
9. Method call contexts
10. Loop source values
11. Trap error/return/bail values
12. Script body scopes and tokenizer string literals
13. Native type table objects

Static objects are skipped during traversal since they only reference other static values.

5. Render Optimization

The

on_render

/

.render()

System

Makepad 2.0 uses a pull-based rendering model for dynamic content. The

on_render

.render()

// Define a reactive view
counter_view := View{
    on_render: || {
        Label{
            text: "Count: " + state.counter
            draw_text.color: #fff
        }
    }
}

// In event handler - only re-render what changed
fn increment() {
    state.counter += 1
    ui.counter_view.render()   // Only this view re-renders
}

Rules for Efficient Rendering

1. NEVER call

   .render()

   unnecessarily - Each call completely rebuilds that sub-tree's widget output.

2. Render only affected sub-trees - If only a list changed, render only the list view, not the entire UI.

3. Avoid rendering in tight loops - Batch state changes, then render once:

// BAD: renders 100 times
for i in 0..100 {
    items[i].value = compute(i)
    ui.item_list.render()    // WASTEFUL - rebuilds list 100 times
}

// GOOD: render once after all changes
for i in 0..100 {
    items[i].value = compute(i)
}
ui.item_list.render()        // Render once with all changes applied

4. Use

   on_startup

   for initial render - Trigger the first render when the app starts:

ui: Root{
    on_startup: || {
        ui.main_view.render()
    }
    main_window := Window{
        body +: {
            main_view := View{
                on_render: || {
                    // ... dynamic content ...
                }
            }
        }
    }
}

Render Scope

When

.render()

on_render

on_render

.render()

on_render

6. Debug Logging

Rust-Side Logging

Use the

log!

use makepad_widgets::*;

// In Rust code
log!("Button clicked, counter = {}", self.counter);
log!("Widget action: {:?}", action);

Script-Side Logging

In Splash scripts, you can use

log()

fn handle_click() {
    let value = compute_something()
    // Log values during development
    log("computed value: " + value)
}

GC Status Logging

Use

mod.gc.run_status()

// Output example:
// GC 142us: obj[S:1200 A:340 R:89] arr[S:45 A:12 R:3] str[S:890 A:120 R:15]
//           hdl[S:8 A:2 R:0] pod[S:200 A:45 R:10] rex[S:3 A:0 R:0]

Fields:

• Time (142us) - GC cycle duration in microseconds
• S (Static) - Objects permanently marked, never collected
• A (Alive) - Objects that survived this GC cycle
• R (Removed) - Objects freed in this cycle

Tag Debugging

For deep debugging of specific objects, use

mod.gc.dump_tag(value)

let my_widget = View{...}
mod.gc.dump_tag(my_widget)
// Output: obj 4523 type_index=Some(12) is_static=false proto=Some(89) ...

7. Common Performance Issues & Fixes

new_batch

new_batch: true

show_bg: true

new_batch: true

.render()

mod.gc.set_static()

PortalList

show_bg: true

show_bg: true

:=

:

+:

:

height: Fit

height: Fit

8. PortalList for Large Lists

Why PortalList

PortalList

Script-Side PortalList (with on_render)

For Splash-driven lists, define the PortalList with templates and use

on_render

list := PortalList{
    width: Fill height: Fill
    flow: Down spacing: 4
    scroll_bar: ScrollBar{}
    Item := View{
        width: Fill height: Fit
        padding: 8
        new_batch: true
        draw_bg.color: #2a2a3d
        label := Label{text: "" draw_text.color: #ddd}
    }
}

Rust-Side PortalList (with Widget trait)

For Rust-driven rendering, implement the Widget trait:

impl Widget for MyList {
    fn draw_walk(&mut self, cx: &mut Cx2d, scope: &mut Scope, walk: Walk) -> DrawStep {
        while let Some(item) = self.view.draw_walk(cx, scope, walk).step() {
            if let Some(mut list) = item.borrow_mut::<PortalList>() {
                list.set_item_range(cx, 0, self.items.len());

                while let Some(item_id) = list.next_visible_item(cx) {
                    let template = id!(Item);
                    let item = list.item(cx, item_id, template);
                    item.label(ids!(label)).set_text(cx, &self.items[item_id].text);
                    item.draw_all(cx, &mut Scope::empty());
                }
            }
        }
        DrawStep::done()
    }
}

FlatList vs PortalList

9. ViewOptimize Options Summary

None

new_batch: true

DrawList

texture_caching: true

Texture

visible: false

Priority: If both

texture_caching

new_batch

texture_caching

ViewOptimize::Texture

10. Debugging Checklist

UI Not Showing

• Check

  height: Fit

  on all containers (default

  height: Fill

  inside a

  Fit

  parent = 0 height)
• Check

  width: Fill

  on root container (never use fixed pixel width on outermost element)
• Verify

  use mod.prelude.widgets.*

  is at the top of the script

Text Invisible

• Add

  new_batch: true

  to any View with

  show_bg: true

  that contains text
• Check

  draw_text.color

  is not transparent or same as background
• Verify the Label is a direct or properly-batched child

Text Disappears on Hover

• Add

  new_batch: true

  to the hoverable View
• Ensure the container of hoverable items also has

  new_batch: true

Clicks Not Working

• Check

  :=

  vs

  :

  -- use

  :=

  for named/dynamic children you reference
• Verify

  show_bg: true

  is set for Views that need mouse events
• Check

  grab_key_focus

  if keyboard events are needed

Widget Not Found

• Verify

  #(WidgetName::register_widget(vm))

  registration in script_mod
• Check that

  crate::makepad_widgets::script_mod(vm)

  is called before custom registrations
• Verify widget crate is a dependency in Cargo.toml

Script Errors

• Use

  log()

  to debug values during execution
• Use

  mod.gc.run_status()

  to check heap statistics
• Use

  mod.gc.dump_tag(value)

  to inspect object internals

Style Not Applying

• Use

  +:

  merge operator for extending existing styles:

  draw_bg +: { color: #fff }

• Use

  :

  only when you want to fully replace a property
• Check dot-path syntax:

  draw_bg.color: #fff

  is shorthand for

  draw_bg +: { color: #fff }

11. Profiling with Studio

Makepad Studio includes a built-in profiler for monitoring application performance.

Studio Remote Protocol

Studio can connect to running applications and provide:

• Screenshots - Capture current frame state
• Widget Tree Dumps - Inspect the live widget hierarchy
• Widget Queries - Find specific widgets by ID
• Performance Monitoring - Frame times, draw call counts

Using Studio for Performance Debugging

1. Start Studio remote:

cargo run -p cargo-makepad --release -- studio --studio=127.0.0.1:8001

2. Run your app through Studio:

{"Run":{"mount":"makepad","process":"makepad-example-myapp","args":[]}}

3. Capture widget tree to identify render structure:

{"WidgetTreeDump":{"build_id":BUILD_ID}}

4. Take screenshots to verify visual state:

{"Screenshot":{"build_id":BUILD_ID}}

Identifying Hot Render Paths

• Use

  WidgetTreeDump

  to see how many widgets are in the tree
• Look for deeply nested View hierarchies that could benefit from

  texture_caching

• Identify repeated items that should use

  PortalList

  instead of manual loops
• Check for Views with

  new_batch: true

  that might not need it (each new batch = new draw list)

12. Quick Reference Card

Performance Properties on View

// Force new GPU draw batch (fixes text-behind-background)
new_batch: true

// Cache children to GPU texture (reduces draw calls for stable subtrees)
texture_caching: true

// Hide without removing from tree (skip rendering entirely)
visible: false

GC API

mod.gc.set_static(value)    // Mark value tree as permanent
mod.gc.run()                // Force GC cycle (silent)
mod.gc.run_status()         // Force GC cycle with log output
mod.gc.dump_tag(value)      // Debug: print object tag info

Render API

ui.widget_name.render()     // Trigger on_render for specific widget

GC Thresholds (Automatic Trigger)

Objects:  >= 1024 AND >= 2x since last GC
Strings:  >= 256  AND >= 2x since last GC
Arrays:   >= 128  AND >= 2x since last GC
Pods:     >= 128  AND >= 2x since last GC
Handles:  >= 64   AND >= 2x since last GC