This is a set of scripts used to manage precisely time synchronized motions of objects in club lighting, dynamic art, and other moving displays in Sansar.

Version 2 of Clockworks introduces dramatic new features. To see the system in action, visit the Clockworks Club experience.

If you're a hands-on learner and want to create some concrete demos before you study the rest of this documentation, try our walk-through examples.

Where to get the scripts

What's the big idea?

3D designers have the ability to create arbitrary animations using modern 3D modeling software. Clockworks was created before Sansar introduced animated mesh, so Clockworks offered Sansar creators the first complex animation system they could use without having to script motion from scratch.

However, it's very important to clarify that Clockworks is not a general purpose animation tool. For one thing, it cannot deform mesh models. Clockworks machines generally stay rooted in place (though they can be moved using scripting). They are not designed to make objects follow arbitrary Bézier curve paths. And there is presently no graphical tool for designing Clockworks animations.

However, Clockworks excels at cyclic motion in multi-segmented, rigid-body machines. If you want to simulate a mechanical clock's gearing, a dancing robot arm, a complex door mechanism, and so on, Clockworks is for you.

Clockworks breaks down the problem of complex motion by treating a machine as a series of rigid bodies (e.g., gears, arms), which we call "segments", and actuators (think "motors") that articulate joints connecting them. Those actuators can either rotate around an axis fixed relative to the parent segment or slide along an invisible track, again fixed relative to the parent segment. Then, each actuator's motion can be "programmed" separately.

Clockworks introduces a simple language for programming joint articulation. Here's an example that describes a simple oscillation:

S:1/4 | S:-1/4

For a rotator, the above can thus be read as "a quarter turn counter-clockwise, then a quarter turn clockwise, then repeat." For a linear actuator, it can be read as "travel a quarter of the full track length out, then travel a quarter of the full track length back, then repeat."

Each joint gets its own program and the joint programs never talk to each other. This helps keep Clockworks programs simple.

Timing is everything. But notice how the above sample program has nothing to say about it? Clockworks was designed with music in mind. In music, the speed, or tempo, of music is often measured in beats per minute (BPM). A fast dance song might have a speed of 120 BPM, or two beats per second. In such dance music, these beats are typically reflected directly by the bass drum or other main percussion instrument.

Even when there is no music, Clockworks machines dance to this invisible beat. You craft your programs (for joint articulation) to express what happens during each successive beat and (typically) the program keeps looping indefinitely. Then you can easily control how fast all the joint programs in a set of machines run. You can even manually change the BPM rate during a live performance as the music changes.

And for each beat, you can choose from a variety of easing functions. Following illustrates objects all moving back and forth at the same rate, but using different easing functions:

Another key innovation is the idea that there is a distinction between the abstract segments in a machine and the moving 3D objects, or "units", that users see. It's best to think of these 3D objects as being attached, like pieces of armor, to that abstractly defined machine. One consequence is that the individual units work fine, even when any number of attached units are removed from it.

In order to compute where it needs to be at some time, each unit computes where its parent segment, that one's parent segment, and so on are, first. The units never need to talk to each other; each is self-contained. This maximizes smooth precision of motion and minimizes expensive script-to-script communication. Only the controller ever talks to them, and only to relay configuration changes.

As a bonus, Clockworks scripts can interact with Reflex scripts to add interactivity. For example, a People sensor could be used to trigger a flower to start dancing.

So to set up a machine using Clockworks, you:

  1. Add 3D models to the scene and mark them as dynamic
  2. Add 1 unit script to each unit (3D model)
  3. Uniquely name each unit via script settings
  4. Add a Clockworks controller script to any object
  5. Create (or buy) and add one or more custom control scripts to:
  6. Add optional Reflex scripts to trigger animation programs