Designing Operators

Operators are the central building blocks of Tooll. Creating them is fast, flexible, and a lot of fun. If you're only working on your own projects, that's all you need to know. But when you want to share your work with other users, it's helpful to consider some conventions for naming and documenting. These conventions will make it easier and more intuitive to use and understand them.

Naming Operators

Naming Parameters

Parameter names should follow these guidelines:

• Must be valid C# field names: No spaces or other special characters.
• Ideally, start with an uppercase character.
• Use PascalCase.
• Avoid underlines, unless for grouping related parameter names.
• Keep them as short as possible (ideally less than 12 characters, max. 20).

Although words like "Scale," "Stretch," and "Size" may sound interchangeable, they have very explicit meanings in the context of Tooll. For consistency, use verbs if possible (e.g., "Translate" instead of Translation).

Please consider the following table:

Name	Comment	Avoid
Subgraph		Command
Position	For generators
Translate	For modifiers	Translation
Center	For effects and volumes
Rotate		Rotation
Stretch	For vec3	Scale, Scaling
Scale	(additional) scale factor	UniformScale, ScaleFactor
Pivot
-
Color
Width	For lines
Size	For points
-
EnableDepthText		EnableZTest
EnableDepthWrite
BlendMode
WrapMode		Wrapping, TextureMode
FilePath		Path
Seed	For integer values	RandomSeed
Phase	For continuous seed values

Ordering Parameters

Obviously, each operator will have different needs for parameters. Some will be essential, and some will be additional details. Nevertheless, it's useful to consider the ordering shown above if in doubt: e.g., Position > Rotate > Stretch > Scale.

Grouping Parameters

Use parameter groups or padding to structure the list of parameters. You can watch this YouTube tutorial to learn more:

• Right-click on a parameter name and choose -> Parameter Settings
• Then check Insert Padding or Insert Group.
• Appending "..." (three dots) will close this group by default. Only choose this for parameters that are not essential and might confuse users.

Documenting Operators

The wiki pages for operators are auto-generated based on the operators' descriptions within Tooll3. That means any contributions made directly to that section of the wiki will be overwritten regularly. If you want to contribute operator descriptions, you'll need to install the development environment and write them in-application.

Currently, T3 only supports plaintext within operator descriptions. This means it should be kept as readable as possible without Markdown formatting, i.e., use minimal emphasis or bold text and avoid images.

Style Guide: A Reference Example

Consider the following description of the Time operator:

Time

Returns the current time from the "context".

In most situations, this will be the playback time in bars (not seconds!) as a number. But this could also be overridden by [SetCommandTime], [TimeClip], during beat tapping, or during rendering an image sequence. Like many music applications, Tooll uses bars to represent time. This allows easily syncing animations to varying soundtracks or BPM rates. At 120 Beats per Minute, 1 bar is equivalent to 2 seconds.

Tips:

• Add a [Modulo] or other math operators to repeat a time range.
• Consider using [AnimValue] for other deterministic time values.
• If you want to restart the timer during playback, try the [Modulo] operator.
• Consider [RunTime] to get the time since application start.

AKA: clock, seconds, bars

... and for its parameters:

Mode: Selects the time representation used:

• LocalFxTimeInBars: Use context time in bars (not seconds!) with applied Idle Motion.
• LocalTimeInBars: Use context time, without Idle Motion.
• LocalTimeInSec: Use the current BPM to convert to seconds.
• PlaybackTimeInBars: Ignore time overrides.

SpeedFactor This parameter is equivalent to appending a [Multiply] operator. Note that animating this will probably result in very rapid changes. You might consider [Accumulator] to achieve smooth but non-deterministic changes in animation speed.

As you can see, writing good documentation is a lot of work and requires intricate knowledge of the operator you're describing. If in doubt, always ask on Discord before drawing assumptions. Incorrect documentation is much worse than missing documentation.

Summary Statement

Start with a one-line summary. It should quickly convey the function of the operator and nothing more. Every library operator should have a one-line summary, even the simplest ones.

• Keep it concise and to the point.
• Avoid padding text with phrases like "This operator does..." or "A handy tool to..."
• If an operator is an internal helper, begin the summary with "Internal helper."

Further Details

Operators that need a more in-depth explanation can have as many paragraphs as necessary in this section. These paragraphs should describe, in detail, how to use the operator.

• Avoid first- or second-person pronouns ("I like to do A," "This op works best if you do B").
• Avoid subjective descriptions ("This op creates an interesting effect").
• Not everything can be explained through text! Use the link section to point out tutorial videos or other sources, like this video for working with time. Also be sure to add a link to the operator's example project, if one is available.

Synonyms

The next line underneath the description should be the word AKA: followed by synonyms for the operator name - any other terms that users might search for when looking for this operator. This mitigates the need for bloated SEO-style descriptions.

• Separate words with commas.
• Use one-word synonyms only.

Tips & Advice

The Tips section at the bottom of the description is for more subjective content. Advice on optimization, interesting combinations to try, or other recommendations can be made here. Tips should be written in bullet-list format.

• Tips can (but don't have to) be phrased like instructions. This means second-person pronouns are fine.
• First-person pronouns should still be avoided. Tips can generally be rephrased to remove them ("I like to set A to 3 and tweak B; it creates an interesting effect!" -> "Try setting A to 3 and tweaking B; it creates an interesting effect!")

Parameter Descriptions

Individual parameters can have their own descriptions. These are only necessary if the name of the parameter is insufficient to describe its function. These are useful to clarify things that are not obvious and that will yield surprising results for certain settings.

• Avoid descriptions that are "content-free content," like "Radius: sets the radius of the sphere." Instead, focus on the non-obvious: "Negative values will flip the normals."