Everything you need to know about the user interface, the controls, and the procedure editing process.

Apparance Editor

The Apparance Editor is the place where all creative magic happens. Build up a library of procedures to describe your world and its content. Explore the parameter space they occupy, tweaking and playing to home in on the look you are after.

Editor

Windows

The editor currently operates in a single window with multiple panels. These panels are:

  • Operator Browser - Find/manage procedures and operators
  • Procedure Graph - Wire up procedures
  • Property Editor - Tweak properties and constants

Functionality

The main functionality provided by the editor application is:

  • Managing - Manage hierarchies of procedures
  • Creating - Build and adjust procedure graphs to build your content
  • Playing - Adjusting parameters interactively to see where it takes you

Browser

The browser panels (to the left) are where all the loaded procedures and built-in operators can be found. Explore, search, and then drag from here to assemble your procedures.

Procedures

Procedures are at the heart of Apparance, these are your content, your design, your objects, and your world. By carefully organising and managing your procedures you can build up a hugely complex and detailed worlds with ease. Procedures are grouped by category and then listed alphabetically by name. A naming convention the browser uses to help organise procedures is to separate sub-levels with dots, for example House.Window would be at the same level as House.Door in the hierarchy. Any part of a name before a dot will appear faded in the browser to help see the unique parts beneath. Whilst categories correspond to separate directories on disk, the naming hierarchy is simply a naming convention and forms the procedure file name.

Operators

Operators are navigated and used exactly the same way as procedures, but they are implemented in code instead of data. The operators you see available are built in to the engine and provide the fundamental functionality of it. Operators have a display name and an internal name, the display name you see on the placed operator and describes its purpose, the internal name disambiguates it from variants (usually by the type it operates on or number of inputs). Operators are grouped by category and then listed alphabetically by their internal name (followed by the display name). A full list of Operators is provided on the operators page of the manual.

Procedure Graph

The main editor window is occupied by the procedure graph, a visualisation of the operators and interconnections between them that make up a procedure. The left side of the procedure outline hosts the input connection points for the procedure, the right, the outputs.

Each Operator within the procedure similarly shows its inputs on the left and outputs on the right. Most are named and have tool-tips to help you remember what each is for. Here is an example, hover over the connections to learn more about them.

The data type for all connection points and the wiring between them are indicated by their colour to help visualise the kinds of information flowing through the procedures. Here is a summary of the types available and their colours.

Property Panel

Many objects in the editor have properties that are exposed for editing via the property panel to the right of the UI. The most common ones are the operators placed in a procedure. By selecting an operator, it's inputs are listed, with editing controls appropriate for each type. A procedures input and output names and descriptions can also be edited here.

Most controls are pretty standard for property editing, but a few are extended to provide extra useful functionality. The colour edit control shows separate RGB sliders and a colour preview swatch. The integer and floating point edit controls have sliders with configurable min and max values. Enumeration and flag properties sometimes have button panels for all their options.

Managing Procedures

Each procedure is stored in it's own file on disk as a .proc file, along with data that is only used by the editor in a .procedit file. Each procedure is represented by an entry in the procedure browser.

Organisation

Each procedure has a category and a name, with procedures of the same category appearing under the same section heading in the browser. The names can contain any characters that are acceptable in a filename and appear as an alphabetically sorted list. If you use full-stops to delineate nested levels of procedure naming then the editor will use this to help visualise this ad-hoc hierarchy by making the name part before the last dot fainter. This has the effect of indenting names that share the same prefix together.

Creating New

  • Alt+NNew Procedure : Creates a new, empty procedure, in the same category as the selected procedure.
  • Right☰  Add new procedure : The context menu has an option for adding new procedures too.

You can either have a procedure selected (Left) and it will be created with a similar name and under the same category, or if you use the context menu on the empty space in the procedure browser it will create a new category and name for you.

Renaming/Moving

Procedures can be easily renamed, without affecting any of your procedures functionality (they are referenced by immutable unique identifiers internally).

  1. LeftSelect the procedure you want to rename
  2. The category, name, and description of the procedure are presented in the Property Panel.
  3. Edit the name and description.
  4. The changes are applied when the text entry field loses focus (either Left click the mouse somewhere else or press Tab).
  5. The procedure will update, and be marked as edited.

To move a procedure change the procedures category property and the procedure browser will show it in the new location.

Other Properties

A procedures description property is a really useful place to document the use of the procedure. This will appear as a tooltip on any instance of the procedure you hover the mouse pointer over.

Saving & Loading

  • Ctrl+SSave the project and all edited procedures
  • You can also press the Save button at the top-left of the editor window.

All procedures are saved and loaded together, you can't partially save the project or individually save procedures.

Tip
A backup history of every procedure saved is maintained per project within your temp user files in C:\Users\yourusername\AppData\Local\Temp\Apparance\ProcedureBackups\. This is purely maintained for emergency, hand maintenance, and not available within the editor. Procedure files are very small so there should be no need to clean out backups.
Warning
If there is a long synthesis job going on in the background then the save operation may be delayed momentarily until it is completed.
Note
Unsaved changes are warned about on exit, with the option to Save them or not

Opening

To open a procedure in the main procedure graph panel for inspection or editing you can either:

  1. DoubleclickOn a procedure in the procedure browser.
  2. DoubleclickOn a procedure instance in the procedure graph.
  3. ClickA document tab at the top of the procedure panel to re-activate an already open one.

The currently edited procedure is shown by the active tab at the top of the procedure graph panel and it's full name as the procedure graph title.

Closing

A couple of ways to close a procedure (no data is lost by closing an edited procedure):

  1. LeftX button of the document tab to close that document.
  2. Middleon label of the document tab to close that document.

Editing Procedures

The normal workflow when editing procedures will include:

  1. Navigating around the procedure graph
  2. Selecting operator instances
  3. Wiring operators together
  4. Setting constant values
  5. Editing procedure inputs and outputs

The procedure graph view area can be panned and zoomed to see the procedure, its operator instances, and its wiring close-up, or as an overview.

  • RightPan to drag the view around the viewport.
  • WheelZoom in and out on the procedure.

Tip
Hold Ctrl while zooming to bypass the normal 1:1 zoom and make everything even bigger

Anatomy

The procedure graph editor consists of several distinct areas and contains various important elements:

Bounds

The boundary of the procedure is host to the input points on the left, the output points on the right, and the full procedure name at the top.

You can't explicitly adjust the size of the bounds, but it will expand to accomodate the operators within it. You can extend the boundary in any direction by moving an operator instance near it.

Warning
There is currently no way to shrink the boundary back down it can only be expanded

Inputs

The left hand side of a procedure shows its inputs.

Outputs

The right hand side of a procedure shows its outputs.

Operators

The main area within a procedure is where all the functionality lives. Fundamental operators (black) and other procedures (grey) can be dropped in here for wiring up.

Each operator (or procedure) instance shows its inputs and outputs in a similar way to the procedure itself. For a full list of the available procedures see the operator directory.

Wiring

All the operators and procedures are connected up with wires, these carry the data from outputs to inputs (generally from left to right).

Wires are colour-coded the same way the inputs and outputs are.

Notes

Notes (not shown) are for two things: adding descriptive and explanatory text, and grouping operators together.

Selection and manipulation of notes is slightly different from standard because of the various states they can be in.

  1. Inactive - No normal mouse operations interact with the note, effectively procedure background.
  • DoubleclickActivate Note and enable movement
  1. Active - Note can be resized, and moved (along with its contents).

Hovering over the corners, edges, and inside of the note show the manipulation available.

  • Drag cornerResize the note in that direction
  • Drag edgeResize the note in that direction
  • Drag insideMove the note and it's contents around the procedure
  • ClickDeactivate by clicking on the procedure background to return the note to its inactive state
  • DoubleclickEdit Note to switch to editing mode
  1. Editable - Note heading and body text can be edited (they are text entry fields)
  • ClickChoose to edit the heading or note body text
  • Tab and Shift+Tab to switch between heading and body
  • ClickDeactivate by clicking on the procedure background to return the note to its inactive state

Selection

Various elements in the procedure editing window are selectable, for either moving around or for viewing and editing properties. Most of them also high-light when the mouse pointer is over them to provide additional feedback.

  • Operator instances
  • Procedure input collection
  • Procedure output collection
  • Notes

For most of these the selection mechanic is fairly standard:

  • LeftSelect an operator, deselecting all others
  • DragMarquee Select around operators, selecting them all
  • Ctrl+LeftToggle Selection on individual operators
  • LeftDeselect all by clicking on the procedure background

The procedure input/output areas to the left/right of the procedure boundary are selectable as a whole, just click outside the boundary anywhere that isn't an input/output label. Individual input/output labels can be selected too.

Operators & Procedures

Operators and procedures, once placed down, are treated exactly the same way. Where the term 'Operator' is used here it applies to Procedures too.

Browsing

Both browsing windows support filtering which limits the listings to only those that match the search text (in category, display name, or internal name). This can be operated using the following methods:

  • Type the text you want in the filter box at the top of each panel
  • Clear the text out to remove the filter
  • Press the Filter button to turn off the filter or restore the previous filter.
  • Right☰  By Name: '???' context menu option to re-instate the previous filter.
  • Right☰  Clear context menu option to clear the current filter.

The operator browser includes some built-in filtering for operators flagged with certain properties.

  • Right☰  🗹 Experimental - A number of operators and operator categories are still under development and disabled by default, select this option in the menu to enable their placement in procedures.

Adding

Operators can be added to the procedure graph by dragging from the browser onto a blank space.

  • DragPlace new operator/procedure instance

Alternatively, the RightContext Menu can be used to browse and select new instances.

  • Right☰  Procedures ► - to explore the procedures available
  • Right☰  Operators ► - to explore the operators available

Tip
The context menu also provides a list of recently placed operators at the top for quick repeat placement.

Positioning

Operators can be arranged within the procedure as best befits their place in the process they are wired up into. Selecting multiple operators allows them to be moved together.

  • DragMove selected operators around the procedure

Operators that have been placed within the border of a note turns the note into a group, i.e. becomes 'attached' to the note. When the note is moved, all the operators placed on it move too.

  • Double ClickActivate group of operators
  • DragGroup to move with all operators in the group

Note
Operators are only added to a group if they are dropped within a group border. Moving a group to be underneath an operator does not add it to the group.

As operators are moved, all wiring is updated to stay connected and the boundary of the procedure may be expanded to accomodate their positions.

Removing

Operators can be removed by selecting them and then pressing Delete.

  • DeleteDelete selected operator(s)

Wiring

The interconnections between operators and input/output points are generally termed 'wires'. Wires always connect from one point to another point within a procedure, i.e. they have direction. Because there are two types of things that a wire can come from both: one of the procedures inputs and one of the operators outputs it's confusing to use the terms 'input' and 'output' when talking about direction of information flow. Because of this we use the term 'Source' and 'Sink' to mean 'a provider of information' and 'a consumer of information'. Summarised here:

Wires signify which Sinks will take their values from which Sources. Source and Sink points are illustrated by the small right-pointing triangles of various colours on the Operators and at the Procedure inputs and outputs.

There are several wiring operations that can be performed:

  • Make - Connect a Source and a Sink together
  • Break - Disconnect an existing Source-Sink connection
  • Move - Change one Source or Sink connection to another Source or Sink

To make a connection:

  1. Lefton Source/Sink to connect starting from the name label or triangular marker.
  2. Dragto required Sink/Source over the name label or triangular marker. Compatible connection points will highlight in bright green. Wire end will 'lock on' to the connection point.
  3. Releaseto make the connection with the chosen connection point. Letting go when not over a connection point will cancel the connection.

To break a connection:

  1. Hoverover end of wire to disconnect and it will highlight in white (whole wire will appear bold).
  2. Dragthe wire end off of the connection point it is connected to.
  3. Releaseaway from connection point to remove the connection.

To move a connection:

  1. Hoverover end of wire to move and it will highlight in white (whole wire will appear bold).
  2. Dragthe wire end away from the connection point it is connected to.
  3. Dragto the new connection point over the name label or trianguoar marker. Compativle connection points will highlight in bright green. Wire end will 'lock on' to the connection point.
  4. Releaseto break the old connection and make the new one

Constants

Unconnected Sinks assume constant values. These can be chosen and adjusted interactively in the editor. Operators behave exactly the same way as if they are wired to something that happened to always produce a certain value.

Editing Operator input constants:

  1. LeftSelect the Operator
  2. Propertyedit the value using the property panel

Many of the data types have special editing UI which will appear in the property panel for them.

Inputs

The left edge of a procedure holds its inputs. These are added to provide ways to parameterise the logic wired up within.

Adding

To add an input simply drag a connection from a Sink somewhere in the procedure, such as an operator input, past the LEFT edge of the procedure. This creates a new input of the type matching the chosen Sink, i.e. to create a string input, drag a string connection out of the left side.

  1. LeftStart new connection from an existing sink of the right type
  2. DragTo input area on the LEFT side of the procedure
  3. DropCreate new input by dropping on the input area

See below for instructions on changing the name of the input.

Note
Doing this will update any places where the procedure is already used to have the additional input and assign it the default value for the given type
Tip
It doesn't matter which connection point you use, as long as it's the right type. You can easily disconnect it for connection to the correct point later.
Warning
You can't change the type of a new input once placed, you will have to remove it and add a new one instead

Removing

Inputs can be removed as you would an operator:

  1. LeftSelect the input to select (hold Control to multiselect)
  2. Delete to remove them

Warning
This will affect all procedures containing this operator and any connections to this input will be removed. Fortunately this is undo-able if you delete something by mistake.

Rearranging

Input can be rearranged using drag and drop.

  1. LeftSelect the input to select (hold Control to multiselect)
  2. LeftDrag the input(s) to a new position (indicated by the orange insertion marker).
  3. LeftRelease and they will be moved.

Properties

Inputs can be renamed and have helpful descriptions added. Select the input area (highlights in yellow), and edit using the Property Panel on the right.

  1. LeftSelect the input area on the LEFT to see the inputs listed in the Property Panel.
  2. PropertyEdit Name & Description for each input in Property Panel.

Outputs

The right edge of a procedure holds its outputs. These are added to provide ways to pass information out from, the logic wired up within.

Adding

To add an output simply drag a connection from a Source somewhere in the procedure, such as an operator output, past the RIGHT edge of the procedure. This creates a new output of the type matching the chosen Source, i.e. to create a string output, drag a string connection out of the right side.

  1. LeftStart new connection from an existing source of the right type
  2. DragTo output area on the RIGHT side of the procedure
  3. DropCreate new output by dropping on the output area

See below for instructions on changing the name of the output.

Note
Doing this will update any places where the procedure is already used to have the additional output (unconnected)
Tip
It doesn't matter which connection point you use, as long as it's the right type. You can easily disconnect it for connection to the correct point later.
Warning
You can't change the type of a new input once placed, you will have to remove it and add a new one instead

Removing

Outputs can be removed as you would an operator:

  1. LeftSelect the input to select (hold Control to multiselect)
  2. Delete to remove them

Warning
This will affect all procedures containing this operator and any connections to this input will be removed. Fortunately this is undo-able if you delete something by mistake.

Rearranging

Outputs can be rearranged using drag and drop.

  1. LeftSelect the output to select (hold Control to multiselect)
  2. LeftDrag the output(s) to a new position (indicated by the orange insertion marker).
  3. LeftRelease and they will be moved.

Properties

Outputs can be renamed and have helpful descriptions added. Select the output area (highlights in yellow), and edit using the Property Panel on the right.

  1. LeftSelect the output area on the RIGHT to see the outputs listed in the Property Panel.
  2. PropertyEdit Name & Description for each output in Property Panel.

Undo & Redo

The Apparance Editor is built with a full command based system internally and supports Undo and Redo of most editing operations.

  • Ctrl+ZUndo to undo the last edit operation
  • Ctrl+Shift+ZRe-do to re-perform the most recently un-done operation
  • Ctrl+YRe-do to re-perform the most recently un-done operation

Operations supported include, but not limited to:

  • Adding/removing operators
  • Operator re-arrangement (moving)
  • Wiring operations (make/break/move)
  • All procedure property editing (including naming and comments)
  • Adding/removing/rearranging procedure inputs/outputs