← Back to Docs
  • index.html
  • Clayground
  • Clayground.Lab
  • SimClock
  • Clayground 2026.7

    • Contents

    SimClock QML Type

    Seeded simulation clock driving deterministic probe sampling. More...

    Import Statement: import Clayground.Lab

    Properties

    Signals

    Methods

    Detailed Description

    The heart of the determinism contract: all lab randomness must come from this clock's seeded generator, and probes are sampled on a fixed sim-time grid. With a world assigned, sim time advances with the physics steps (exact under the inspector's time/step action); without one, a frame ticker advances it, honoring Clayground.paused and Clayground.timeScale.

    Example usage:

    import Clayground.Lab

SimClock { id: clock; seed: 42; world: theWorld }

    See also Lab and Probe.

    Property Documentation

    fixedStep : real

    Length of a fixed simulation step; 0 disables stepped.

    A time-driven lab must advance its model in FIXED steps or it is not reproducible: variable frame times make the run depend on the machine it ran on. Set this and handle stepped instead of reading time in a frame handler.


    maxStepsPerAdvance : int

    Fixed steps allowed per advance, so a hitch cannot become a freeze.


    sampleInterval : real

    Sim-time seconds between probe samples.


    seed : int

    Seed for the deterministic random generator; changing it resets the clock.


    time : real [read-only]

    Simulated seconds since the last reset.


    timeScale : real

    Slow-motion/fast-forward factor for live (frame-driven) mode.

    Composes with Clayground.timeScale; ignored while stepping, which always advances fixed frames for reproducibility.


    world : var

    Optional ClayWorld2d; when set, time advances with physics steps.


    Signal Documentation

    stepped(real dt)

    Emitted once per fixed step, dt being fixedStep.

    Guaranteed to arrive in whole steps and never to run backwards: a reset() rewinds time, and the rewind is swallowed here rather than replayed as a negative step by every lab that forgot to.

    Note: The corresponding handler is onStepped.


    wasReset()

    Emitted after a reset; sensors/estimators snap their state here.

    Note: The corresponding handler is onWasReset.


    Method Documentation

    real random()

    Deterministic uniform random number in [0, 1) (mulberry32).


    real randomGaussian()

    Deterministic standard-normal random number (Box-Muller).


    real randomRange(real from, real to)

    Deterministic uniform random number in [from, to).


    void reset()

    Resets time, random state and all probe samples.