Skip to content

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

  1. 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.
  2. autotune-settings from preset or defaults.
  3. Render the current preset as the base: render-and-grade for this scene alone, from a clean checkout. Keep its run dir.
  4. Assemble the candidate on its own branch or worktree (the base checkout stays untouched): copy final_settings into 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.
  5. 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.
  6. 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.json facts.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, baumgarte 0.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.