ASYNC

A 3D application in two halves: a C++ engine that owns the scene, and an interface that draws it. This is the reference for the two surfaces you can build on — Python for scripting, C++ for plug-ins.

The two repositories

The one rule worth reading first

Only a command changes the document — decision D4, and everything else follows from it. A command is the single thing that travels to the other people in a session, goes on the undo stack, and tells the panels something happened. Anything that changed the scene another way would exist on one machine only, undo to nothing, and be invisible to every panel: that is not a style preference, it is the shape of every desync this project has had.

So cmds.polyCube() is not a function that makes a cube. It is a function that runs the command that makes a cube — which is why it undoes, replicates and redraws without you asking for any of it.

Two surfaces, and why they are different languages

Running a script

Two places, the same module.

In the application

The Script Editor is a dock at the bottom of the window — the console icon, or Window › Panels. cmds is already imported. Ctrl+Return runs the selection, or the whole tab if nothing is selected. (Every key is in Settings › Hotkeys and can be moved.)

Headless

The module is async_core_py, built into build/. Nothing here needs a window, a GL context or a running application — which is what makes it usable from a test, a build step or a machine with no screen.

PYTHONPATH=build python3
>>> from async_core_py import cmds
>>> cmds.polyCube(1.0, name="crate")
|crate

Build it first with ./run.sh, which configures CMake and starts the application, or run CMake yourself against build/.

Finding your way around

cmds.help() lists what is there and cmds.help("polyBevel") explains one verb. Everything on the next page is that same text, read out of the module.

cmds

The scripting surface, grouped by what it is for. Read out of the compiled module — what is written here is what the build you have answers.

Answers

A refusal is a value, not an exception.

Every verb answers with an Answer: truthy when it worked, carrying what it made and, when it did not, a sentence you can show somebody. Nothing raises for an ordinary "no" — a layer that is locked, a node that is gone, a file that is not a scene are all answers, because all three are things a person did rather than things the program got wrong.

a = cmds.polyCube(1.0, name="crate")
if a:
    print(a.node)          # '|crate'
else:
    print(a.message)       # why not, in words

str(a)                     # '|crate', or 'rejected: "props" is locked'

A worked example

Make a crate, move it, bevel two of its edges and put a subdivision on top — destructive nothing, undoable everything:

from async_core_py import cmds

crate = cmds.polyCube(1.0, name="crate").node
cmds.xform(crate, translation=(0, 1, 0))

shape = cmds.ls(crate, shapes=True)[0]
cmds.polyBevel(shape=shape, edges=[0, 1], width=0.1, segments=2)
cmds.polyAddModifier(crate, "subdivision")

cmds.polyEvaluate(shape)
# {'vertices': 8, 'edges': 12, 'faces': 6, 'valid': True, 'version': 0}

Being told, rather than asking

Panels do not poll. cmds.subscribe calls you back once per command with the list of what changed, and there is a second channel for what a drag is doing before it becomes a step:

token = cmds.subscribe(lambda changes: print([c["kind"] for c in changes]))
cmds.polyCube(1.0)          # ['added', 'added', ...]
cmds.unsubscribe(token)

Undo, and chunks

There is one stack, it belongs to the core, and everything is already on it. What you get to decide is what counts as one step.

Why you never have to write an undo

A command knows how to take itself back. That is what a command is here: a thing that can run, be undone, be redone, say what it touched, and write itself down to be sent to somebody else. Because every verb in cmds runs one, undo, redo, replication and the history panel come for free — and an operator that a plug-in registers gets all of it without writing a line of undo code, because one core command runs any operator (D67).

The consequence worth internalising: if it did not go through a command, it did not happen. There is no second way to change a scene that quietly skips the stack.

One step is one command — unless you say otherwise

Chunks: many commands, one Ctrl+Z

An action is often one thing to the person doing it and several commands underneath — build a wall, rig a limb, import and place. Say so, and the whole sequence becomes a single step (D52).

The block form cannot be left open, so prefer it:

with cmds.undoChunk("a wall"):
    for i in range(3):
        cmds.xform(cmds.polyCube(1.0).node, translation=(i * 2, 0, 0))

cmds.undoName()    # 'a wall'
cmds.undoDepth()   # 1 in a fresh scene - six commands, one step
cmds.undo()        # the whole wall goes at once

When a block cannot express it — a chunk that begins in one callback and ends in another, a tool that opens on mouse-down and closes on mouse-up, a script that builds something across several functions — open and close it by hand:

cmds.openChunk("a wall")
for i in range(3):
    cmds.xform(cmds.polyCube(1.0).node, translation=(i * 2, 0, 0))
cmds.closeChunk()

cmds.undo()        # still one step

# and when a gesture is abandoned half way:
cmds.openChunk("thrown away")
cmds.polyCube(1.0)
cmds.cancelChunk()  # everything it collected is undone, no step is left

What is deliberately not on the stack

Three kinds of thing run through the same machinery and leave no step, because a person pressing Ctrl+Z did not mean any of them:

In a session

The timeline is shared: Ctrl+Z takes back the newest step in the room, whoever made it, and the application says whose it was rather than silently undoing a stranger's work (D45). A step that cannot be taken back because somebody has been at those nodes since is refused with a sentence rather than applied to a scene that has moved under it (D30).

viewport

The control surface of a viewport widget: what it draws, how it draws it, and which camera it looks through. The application's own toolbar drives this directly rather than through a wrapper.

Writing a plug-in

A shared library that registers things when it is loaded. The shape is Maya's, because Maya's is right and people already know it.

The two entry points

#include "async/core/plugin.h"

using namespace async::core;

ASYNC_PLUGIN_EXPORT void asyncInitializePlugin(Registrar& into) {
    StageType twist;
    twist.name  = "twist";                       // in files, in cmds, on the wire
    twist.label = "Twist";                       // what a person reads
    twist.kind  = ModifierKind::Deform;          // it moves points, it adds none
    twist.params = {
        {"angle", "Angle", 45.0f, -360.0f, 360.0f},
        {"axis",  "Axis",  1,     0.0f,    2.0f, {"x", "y", "z"}},
    };
    twist.run = [](Mesh& mesh, const Params& p) {
        const float angle = p.number("angle");
        // ... move mesh.points ...
    };
    into.stage(twist);
}

ASYNC_PLUGIN_EXPORT void asyncUninitializePlugin() {}

ASYNC_PLUGIN_EXPORT is extern "C" plus one platform word. It has to be a macro because Windows exports nothing from a DLL unless it is asked: the two functions compiled and linked and the manager still said "it exports no asyncInitializePlugin", which is true and says nothing about where to look.

What a registrar gives you

Where they are found

The application scans a search path at start-up and lists what it finds in the Plug-in Manager — installed, loaded, and set to load on start. From a script: cmds.scanPlugins(path), cmds.loadPlugin("asyncTwist"), cmds.plugins(), cmds.pluginAutoLoad("asyncTwist", True).

What you can register

Four types, and the fields are the whole contract. Each one is a plain struct you fill in and hand over.

StageType — an entry in the modifier stack

OperatorType — an edit

An EMesh is the editable mesh — the one with the topology you can walk and change. A Mesh is the flat one a stage sees. That difference is the difference between the two register verbs.

NodeType — a kind of object

ActionType — a menu entry

From a script: cmds.pluginActions() lists them and cmds.runPluginAction("mpHost") runs one, which is how a headless test drives a plug-in that normally has a button.

Parameters

One declaration, and everything downstream knows what to do with it: the panel draws it, the file writes it, the wire carries it.

Param angle;
angle.name     = "angle";      // identifier - in cmds, in files, on the wire
angle.label    = "Angle";      // what a person reads
angle.fallback = 45.0f;        // the default, which also fixes the type
angle.low      = -360.0f;      // where a slider lives - soft, not a clamp
angle.high     =  360.0f;

Param axis;
axis.name    = "axis";
axis.label   = "Axis";
axis.fallback = 1;             // an enumeration is a number...
axis.choices = {"x", "y", "z"}; // ...plus the names of its alternatives

type.defaults() gives every declared parameter at its default, which is what a new stack entry or a freshly run operator starts as.

Building one

There is a CMake helper, and every line of it is a trap somebody would otherwise hit.

cmake_minimum_required(VERSION 3.20)
project(async_ripple LANGUAGES CXX)

include("/path/to/ASYNC/cmake/AsyncPlugin.cmake")

async_add_plugin(asyncRipple ripple.cpp)              # core only, headless
# async_add_plugin(asyncRipple ripple.cpp panel.cpp QT)  # with a panel

What it does for you:

Drop the built file where the manager looks (beside the plug-ins that ship with ASYNC), or point cmds.scanPlugins at your own folder.

Panels in a plug-in

A plug-in can bring a dock panel. It is a separate registrar, in the application half, and the cost is stated rather than discovered.

#include "panel.h"   // async::app

ASYNC_PLUGIN_EXPORT void asyncInitializePluginPanels(async::app::PanelRegistrar& into) {
    async::app::PanelType panel;
    panel.name  = "ripplePanel";
    panel.label = "Ripple";
    panel.make  = [] { return static_cast<QWidget*>(new MyPanel); };
    into.panel(panel);
}

A panel is a widget, a widget is Qt, and the core may not depend on Qt (D5) — which is why this lives in the application and not beside the other registrar. From a script: cmds.pluginPanels() and cmds.makePluginPanel(name).

The multiplayer plug-in that ships with ASYNC is built exactly this way, and split for exactly this reason: the transport and the session know nothing about Qt, so a headless peer is possible — a machine that holds the scene, a test that runs two sessions against each other — and only the panel needs a screen.

Decisions

Why the code is the way it is, in the order it was decided. Read out of the core's journal — this is not a summary of it, it is it.