CRITICAL: Use for Makepad 2.0 Splash scripting language. Triggers on: splash language, makepad script, script_mod!, makepad scripting, splash 脚本, makepad 2.0 script, mod.state, on_render, script_eval, streaming evaluation, splash syntax, splash vm, let binding, splash functions, hot reload, live reload, ScriptModKey, script_mod_overrides, checkpoint, incremental parsing, canvas splash, POST splash, fn tick, on_audio, set_text, tab switching, 音乐播放器, token monitor, driver script, audio API, 热重载, 脚本引擎, 增量解析
Splash is Makepad 2.0's core runtime UI scripting language, released February 12, 2026. It replaces the old compile-time live_design! macro system with a runtime script_mod! macro that enables hot reload, streaming evaluation, and AI-first code generation.
Every Splash script starts with a use import and is embedded in Rust via the script_mod!{} macro:
use makepad_widgets::*;
app_main!(App);
script_mod! {
use mod.prelude.widgets.*
// let bindings, functions, state, and UI definitions go here
startup() do #(App::script_component(vm)){
ui: Root{
main_window := Window{
window.inner_size: vec2(800, 600)
body +: {
// UI content
}
}
}
}
}
key: valuedraw_bg.color: #f00 (equivalent to draw_bg +: { color: #f00 })key +: { ... } extends parent without replacingname := Widget{...} (addressable, overridable per-instance)let MyTemplate = Widget{...} (local scope, must be defined before use)#(Struct::register_widget(vm)) connects Splash to Rust structs~expression logs value during evaluationState is managed via the mod.state object and reactive on_render callbacks:
// Define state
let state = { counter: 0 }
mod.state = state
// Reactive rendering -- re-runs when .render() is called
main_view := View{
on_render: ||{
Label{ text: "Count: " + state.counter }
}
}
Events are handled both inline in Splash and from Rust:
// Inline event handlers in Splash
add_button := Button{
text: "Add"
on_click: ||{
add_todo(ui.todo_input.text(), "")
ui.todo_input.set_text("")
}
}
// TextInput return key
todo_input := TextInput{
on_return: || ui.add_button.on_click()
}
// Startup event
on_startup: ||{
ui.main_view.render()
}
From Rust, use script_eval! to execute Splash code:
impl MatchEvent for App {
fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) {
if self.ui.button(cx, ids!(increment_button)).clicked(actions) {
script_eval!(cx, {
mod.state.counter += 1
ui.main_view.render()
});
}
}
}
fn tag_color(tag) {
if tag == "dev" theme.color_highlight
else if tag == "design" theme.color_selection_focus
else theme.color_highlight
}
fn add_todo(text, tag) {
todos.push({text: text, tag: tag, done: false})
ui.todo_list.render()
}
// If/else
if todos.len() == 0
EmptyState{}
else for i, todo in todos {
TodoItem{ label.text: todo.text }
}
// For loops
for i, item in array {
Label{ text: item.name }
}
// While
while condition { ... }
let req = net.HttpRequest{
url: "https://api.example.com/data"
method: net.HttpMethod.GET
headers: {"User-Agent": "MakepadApp/1.0"}
}
net.http_request(req) do net.HttpEvents{
on_response: |res| {
let text = res.body.to_string()
let json = res.body.parse_json()
}
on_error: |e| { /* handle error */ }
}
Streaming responses use is_streaming: true with on_stream and on_complete callbacks.
let doc = html_string.parse_html()
doc.query("p") // all <p> elements
doc.query("#main") // by id
doc.query("p.bold") // by class
doc.query("div > p") // direct children
doc.query("p[0]").text // text content
doc.query("a@href") // attribute value
Splash's parser supports checkpoint-based incremental parsing, designed for AI/LLM streaming code generation:
// Rust API for streaming evaluation
vm.eval_with_append_source(script_mod, &code, NIL.into())
This enables real-time UI updates as code is generated token-by-token, without requiring a complete script before evaluation.
Splash scripts support hot reload via the --hot flag. The VM tracks each script_mod! block with a unique ScriptModKey (file, line, column):
// Internal: ScriptModKey uniquely identifies a script_mod! block
ScriptModKey { file: "src/app.rs", line: 5, col: 1 }
// Runtime substitution via overrides
ScriptCode::script_mod_overrides // HashMap of ScriptModKey -> updated source
How hot reload works:
makepad_live_reload_core) detects source file changesscript_mod! blocks are extracted from Rust source (handles raw strings, comments, char literals)#(...)) are tracked -- adding/removing placeholders requires full rebuildscript_mod_overridesScriptSource variants:
ScriptSource::Mod -- Standard module evaluation (startup)ScriptSource::Streaming -- Incremental streaming evaluation (AI/LLM)height: Fit on containers -- default height: Fill causes invisible UI (0px height)width: Fill on the root container -- never fixed pixel width at the top levelnew_batch: true on any View with show_bg: true that contains text children:= for named children in templates -- without it, text overrides fail silentlydraw_bg.border_radius takes a float, not an Inset -- draw_bg.border_radius: 16.0RoundedView, SolidView) instead of raw View{show_bg: true}Core containers: View, SolidView, RoundedView, RectView, RoundedShadowView, CircleView, GradientXView, GradientYView, ScrollXYView, ScrollXView, ScrollYView
Text: Label, H1-H4, P, TextBox, TextInput, LinkLabel, Markdown, Html
Controls: Button, ButtonFlat, ButtonFlatter, CheckBox, Toggle, RadioButton, Slider, DropDown
Layout: Splitter, FoldHeader, Hr, Vr, Filler
Lists: PortalList, FlatList
Navigation: Modal, Tooltip, PopupNotification, SlidePanel, ExpandablePanel, PageFlip, StackNavigation
Dock: Dock, DockSplitter, DockTabs, DockTab
Media: Image, Icon, LoadingSpinner, Vector, MathView, MapView
Makepad Canvas (tools/canvas/) is a standalone app that renders Splash code received via HTTP/WS. Used by Claude Code for visual output.
PORT=$(cat /tmp/makepad-canvas.port)
# Full render
curl -s -X POST "http://127.0.0.1:$PORT/splash" -d 'View{width:Fill height:Fit Label{text:"Hello"}}'
# Streaming render
curl -s -X POST "http://127.0.0.1:$PORT/splash/stream" # begin
curl -s -X POST "http://127.0.0.1:$PORT/splash/stream" -d 'View{...' # append
curl -s -X POST "http://127.0.0.1:$PORT/splash/end" # end
# Clear
curl -s -X POST "http://127.0.0.1:$PORT/clear"
# Long-lived WS connection receives button click events as JSON
mkfifo /tmp/ws_fifo; (sleep 99999 > /tmp/ws_fifo &)
websocat ws://127.0.0.1:$PORT < /tmp/ws_fifo > /tmp/canvas_events &
# Events arrive as: {"event":"click","widget":"btn_name"}
Use name := Button{...} to create clickable buttons. The name is sent in click events:
View{width:Fill height:Fit flow:Right spacing:12
btn_save := Button{text:"Save"}
btn_cancel := Button{text:"Cancel"}
}
When clicked: {"event":"click","widget":"btn_save"}
// Pulsing dot (loop_:true = indefinite, NOT "indefinite"!)
Vector{width:16 height:16
Circle{cx:8 cy:8 r:6 fill:#x44ddaa opacity:Tween{from:0.3 to:1.0 dur:1.5 loop_:true}}
}
// Moving dot with color change
Vector{width:Fill height:30
Path{d:"M 20 15 L 400 15" stroke:#x222244 stroke_width:1.}
Circle{cx:Tween{from:20 to:400 dur:3.0 loop_:true} cy:15 r:4 fill:Tween{from:#x44ddaa to:#xffaa44 dur:3.0 loop_:true}}
}
When generating Splash for Canvas HTTP rendering (POST /splash), use these EXACT patterns. Canvas Splash syntax differs from script_mod! macro context in several critical ways:
1. Properties use dot-path inline, NOT nested blocks:
// WRONG -- nested block syntax does not render backgrounds
RoundedView{height: Fit draw_bg: { color: #x1a1a2e border_radius: 8.0 } }
// CORRECT -- dot-path inline
RoundedView{width: Fill height: Fit draw_bg.color: #x1a1a2e draw_bg.radius: 8.}
2. Border radius is draw_bg.radius, NOT draw_bg.border_radius:
// WRONG
draw_bg.border_radius: 8.0
// CORRECT
draw_bg.radius: 8.
3. Padding uses explicit Inset{} type with trailing-dot floats:
// WRONG -- bare number or nested block