Tune a scene
Workflow
- Goal
- a Steel preset for one scene that is correct over the whole task first and as fast as it stays correct second.
- Use when
- asked to make a Steel scene stable or faster, to pick Steel settings or a preset, or to check whether a setting is safe to ship.
- Done when
- the settings you ship pass
shelf check, cover the whole task with zero dropped rows, and their frames look right.
Any coding agent, or a person, can follow this workflow from agents/workflows/tune-a-scene/README.md. Tools that discover skill folders also find it assteel-tune-a-scene.
Inputs. An example (uv run python -m shelf list from examples/) or a scene of your own; where to start
(preset or defaults); the world count you will use. Read the tuning guide
sections 1-3 first.
Steps
- run-trial at the current preset, to see where you start.
- A critical flag names a scene bug (start state written to body arrays only, shapes overlapping at rest, non-finite contact geometry) → fix the example’s code; settings cannot. If you cannot tell what is wrong → debug-instability.
- autotune-settings from
presetordefaults.final_healthy: false→ debug-instability with the last trial.
- Render the current preset as the base: render-and-grade for this scene alone, from a clean checkout. Keep its run dir.
- Assemble the candidate on its own branch or worktree (the base checkout stays untouched): copy
final_settingsinto the example’s[steel]table, then apply size-capacities at the world count you will ship, so the capacities you measure are the last change to the table. Commit it. - In the candidate checkout: check-example, then
render-and-grade for the scene with
collect.py --previous BASE_RUN_DIR, then visual-review, comparing its sheet with the base’s. A cheaper setting can change the motion without failing a metric.- The motion changed in a way the task does not allow → go back to the last kept setting, or tune-one-knob from it, and repeat steps 4-5.
- Optional: benchmark-throughput, base preset against the candidate preset, at the shipping world count.
Before shipping
- The example’s own check passes at the settings you ship, never at cheaper test settings.
- The run covers the whole task, through the load (impact, grasp, pour, settling).
- Zero overflowing world-steps and
check_constraint_capacity()passes, at the world count you will use: rare failures show only at scale (one world in 64, or a few in 256). - The settings reached the solver:
trial.jsonfacts.solver_kwargs. Examples that build their own solver ignore preset keys, and the advisor flags it.
Rules of thumb (details in the guide)
- Never turn off physics the scene relies on (limits, velocity limits, friction anchors that hold a grasp, torsion, collision, self-collision) to win time.
- Capacities: 1.3x the requested high-water mark of a run that did not overflow.
- Heavy impactor (mass ratio above about 1000:1): 2x substeps, 2x iterations,
baumgarte0.5. Resting stack (100-1000:1): momentum, then a sweep budget spent as iterations in the fewest substeps. - Anything held or carried: friction anchors on, warm start off.
- Fewer substeps is the usual throughput lever; a time-step-limited scene (ropes, fast chains) refuses it.
Deliverables
The edited presets.toml (with a comment per setting saying why), tune.json, the gallery for the scene, and a
short report: settings, trials to the first healthy one and in total, frame time against where you started, every
fix and cost change kept or rejected, what you looked at.
Steps it uses
- Run a trial runs one example's whole episode with Steel at given settings and lists what is wrong, in fix order.
- Autotune settings repeats trials until no fix is left, then keeps only cheaper settings that stay healthy.
- Render and grade renders examples with their Steel presets on one or more GPUs, records stability metrics, and grades each scene ok, suspect, unstable or failed.
- Size capacities sets Steel's constraint-row capacities so no row is ever dropped, with headroom, from measured demand.
- Check an example runs an example's own test headless with a preset and records the result in
presets.toml. - Visual review looks at frames across each episode and records a grade and a note per scene the metrics may have misjudged.
- Tune one knob changes a single setting, holding everything else fixed, and keeps it only if every gate still passes.
- Benchmark throughput measures simulation and application throughput and memory for two configurations (two backends, or two settings) under one timing contract, and tunes Steel in a fixed order.
Source: agents/workflows/tune-a-scene/README.md, the copy agents read.
Steel docs and tutorials are licensed under Apache-2.0. Third-party notices. "Skild", "Skild AI" and the Skild logo are trademarks of Skild AI and are not licensed under Apache-2.0.