This page is your instruction manual for using Apparance within the Unreal Engine development environment and editor. Once you have installed and set up the plugin you are ready to author procedures and work in Unreal.

Apparance Menu

The main toolbar has an Apparance drop-down for quickly accessing the main tools and information links.

  • Tools - Setting up of Apparance, and directly open the editor
  • Help - Online documentation links
  • Information - Direct links to some of the About Box pages

Tip
You can also open a specific procedure directly in the Apparanc Editor by clicking the Open button on a procedural entity in the scene.

Level Viewport

Procedures are instanced into a level via a custom Entity Actor actor type:

  • These refer to the procedure definition created in the Apparance Editor
  • They store instance specific input parameters to drive the procedure
  • All generated geometry and placed meshes/component/blueprints are added as hidden children

By default these are empty and don't contribute to the scene until you assign which procedure they will present as.

Placing Entity Actors

New Entities can be placed in a number of ways:

  • Drag the Entity Actor entry from Actor Panel into the scene (set Procedure in drop-down)
  • Right click in the scene and select Apparance Entity from the Context menu (set Procedure in drop-down)
  • Copy an existing Entity Actor and change the procedure it references
  • Drag an Apparance Entity Preset asset into the scene (has implied procedure and default parameters)

Entity Appearance

In the editor, a selected entity has a faint bounding box drawn to help visualise the location, orientation and size of the space it will be built into. (This only applies if the Entity has an input parameter of Frame type as it is that that defines an objects bounds.)

Manipulating Entities

The normal actor transforms are used to position and orient the procedural instance in the world. Scaling however is less useful as it affects all the placed components and can't be used to drive the population of the entity as easily if you don't know the actual size of the space available. Usually it is common to have a Frame input parameter to provide the bounds to the procedural logic, it is by no means required though and a procedure can build out from the Entity origin as it sees fit.

Undo and Redo are fully supported and should work with all Entity transform and parameter changes.

Coordinate Systems

Apparance lives in the 'CAD corner' of the coordinate systems chart) operating with a Right Handed / Z Up coordinate system and 1 metre per unit scaling. This means there is a bit of a disparity between working in Apparance and working in Unreal (Left Handed, Z Up, 1 cm units). There are some mechanisms to help with this (World Space metadata flag on parameters) but generally you will have to work in one when building procedures and the other when working in Unreal.

Application System Right Forward Up Distance
Apparance Right-handed X Y Z 1 (m)
Unreal Left-handed Y X Z 100 (cm)

Details Panel

Each Entity Actor has an Apparance Category available in the Details Panel to customise it's procedural parameters.

Procedure Type

The first property (to the right of the logo) controls the procedure the Entity will use to build its content. A drop-down list presents all the procedures, arranged by category.

To the right there is a button that can be used as a shortcut to take you directly to the procedure in the Apparance Editor and open it for editing.

Procedure Parameters

The rest of the details are dedicated to the input parameters for the selected procedure. Any input pins added to the procedure are exposed as editable parameters. Most types use standard Unreal property controls for editing.

Hovering over a parameter name will show additional information about the parameter where available. For example; the type of the parameter, if it's been edited, the origin (for Frame parameters), and if they are a world-space value.

Some parameter have additional metadata associated with them that affects how they appear in the Details Panel. See the Editor manual page for more information on procedure inputs.

Parameter Overrides

Like many Unreal objects, Entity parameters can be edited to override any default values, and the 'Reset to default' button can be used to clear out the override. With Entities, there is are several places this default can come from and alternate ways it can be overridden.

Procedure Input Definition → [Preset Asset] → Level Instance → Script Overrides

Each subsequence place takes precidence over the previous one and can override any procedure parameters, becoming more and more customised/specialised through the chain.

  • Procedure Input Definition - Default value set in the Apparance Editor on each procedure input
  • Preset Actor - If a preset is used to place the actor in the level then values can be overridden here
  • Level Instance - Each Entity Actor instance in a level can override and set it's own parameters
  • Script Overrides - A Blueprint based Entity Actor can completely specify the generation parameters in the construction script

Advanced Properties

An entity will, by default run the procedure and add any generated content to the scene automatically. This behaviour can be customised and controlled with some advanced settings (under the Apparance → Advanced section of Details panel).

  • Debug - For diagnostics purposes, the internal structure of the Entity Actor can be written to the clipboard. Try it and see!
  • Populated - Initially true, generation and instancing of content happens as soon as the Entity is loaded/added/active. This can be turned off to delay this process if not needed immediately, or some other criteria is used to control generation (such as proximity to the player perhaps).
  • Visible - The generated content can be shown and hidden as needed. This doesn't affect generation and means that pre-populated content can be shown instantly (no wait for the generation process).

Other properties are available for further customising the appearance of the Entity:

  • Instancing - By default, static meshes are added to the Entity as individual Static Mesh Component instances, but this can optionally be switched to use mesh instancing via the Instanced Static Mesh Component which in many situations is more performant.
    Note
    For instancing to be used the global Allow Instancing setting in the Projects Plugin settings must be enabled.
  • Auto Seed - For testing and demonstration purposes Entities can have a seed value (first integer parameter found) auto-incremented at regular intervals.

Content Browser

Content browser is used to manage Resource Lists and Entity Presets.

Procedures

Although procedures are stored in a folder within the project Content directory, they are not Unreal asset, and so don't appear here. Procedures are managed by the Apparance Editor. The setup process requires that a directory be set aside for storing procedures.

Resource Lists

Resource Lists are needed to bridge the gap between Apparance procedures, which don't know anything specific about the engine they are running in, and the actual assets in the project. They provide a mapping between resource descriptor strings used (or generated) in the procedures and actual assets in the project.

A resource list asset added to the project needs to be referenced directly or indirectly by the main project resource list (see setup, and the Resource List Editor section below, for details). A tree of resource lists can be built up to help organise the asset library the procedures need access to.

A Resource List is a hierarchy of 'folders' that can be used to organise your resource references. The folder hierarchy forms the resource descriptor, from the root down to the actual referenced asset, as string separated by dots. The root of the hierarchy applies to all resources referenced in a resource list and a good candidate for categorising at the project level. One Resource List per top-level category.

As an example, the string descriptor Example.Books.Book1 maps to the Resource List with the Example root name (shown below), then a Books folder within it, then the Book1 asset slot, and finally the Book_01 Static Mesh assigned to it.

There are several types of resource a slot can reference:

  • Static Meshes - visual bespoke geometry
  • Blueprint Actors - fully fledged child actor
  • Actor Components - any component types, e.g. for collision, lights, effects, etc
  • Materials - to be applied to generated geometry

Resource slots can be expanded to allow multiple variant slots within. These are exposed by the Resolve operator in procedures as the Variants count, and the Variant input can be used to select one of them by index.

Entity Preset

To aid with rapid placement of often used procedural Entity configurations the procedure and a specific set of parameters associated with it can be stored in the project as a Preset.

These can be dragged into a scene with their parameters already set up for a particular procedural variant.

Preset are created using the Content Browser context menu, under the Procedural category.

The editor for Presets, opened by double-clicking on the asset, is just the same as the details panel for an Entity in the scene; choose your procedure from the drop-down and set any default parameters. You can preview these settings by placing an instance in the scene. Changes to these parameters will update all instances of the preset in the scene (as long as the parameter hasn't been overridden on the instance).

Resource List Editor

A new, empty, resource list looks like this and has the following key UI areas:

  • Toolbar - A few common actions as well as context sensitive actions
  • Resource List - List of resource entries and the assets they refer to, supports folders to form a hierarchy
  • Details Panel - Explicit details of the selected resource entry

Resource Entries

A resource entry has a name, type, and referenced asset. If the entry is a folder then it acts as it's own list of resource entries.

The name of an entry contributes to the asset descriptor path leading to an asset reference (see example further up the page).

Press F2Rename, or edit the Name field in the Details Panel, to change the name of a selected entry.

New entries are added by pressing the +ResourceAdd Resource button on the toolbar. The first entry added to a folder is 'wild' and doesn't know what type it is until you assign an asset to it. You can also open the RMBRight click context menu to explicitly assign a type. Assets added to a folder that already has assets in will automatically adopt the same type. Entries initially have no Asset assigned.

A selected resource entry (or folder) can be deleted using the Remove toolbar button or the Delete key. All editing operations in the Resource List panel support Ctrl+ZUndo and Ctrl+YRedo.

Asset Types

Each Resource List entry can be used to reference one of the following Unreal asset or object types:

  • Static Mesh - Meshes can be placed in the scene using procedures
  • Material - The surfaces of generated geometry can have materials assigned
  • Blueprint - Complex blueprinted objects can be placed procedurally
  • Component - Any type of Actor Component can be placed procedurally (with it's properties driven by the procedure)

An asset can be assigned to an entry using the asset picker button in the Asset Slot UI (as well as finding the current asset in the Content Browser and clearing the asset out). This is also available in the Details panel.

Resource Variants

Variants are a collection of assets referenced by the same resource descriptor string that can then be procedurally selected by index from within the collection. This provides an easy way for artists to add richness to their creations, adding more variety and having the procedures 'just use them' automatically as the collection grows.

An existing resource entry can be toggled between Single and Variants mode with the Variants? toolbar button. When in Variants mode it will have sub-entries, each of the same type and numbered in sequence. Adding a new entry with the +ResourceAdd Resource button will add a new numbered variant to the end of the list. Generally they behave like all other resource list entries, but can't be renamed.

Actor Components

A really useful feature of the resource lists and the placement system is to allow adding of arbitrary Actor Components to the Entity Actor by the your procedural logic. These are added as new components to the actor and behave just like components of a blueprint would.

To create a new Actor Component entry you must do the following:

  1. Create an un typed entry (shows ? for it's icon) by adding a resource to an empty folder.
  2. Force it to be a Component entry type using the RMBContext Menu
  3. Navigate to the Component → Defaults → Component Template field in the details.
  4. Choose your component type
  5. Set the component default values
  6. Use the Parameter Map and Function lists to set up how each instance gets configured during placement

The Place procedural operator has an input for a list of placement parameters and these can be routed to drive how the component is set up when added to the actor:

  • Properties - Each parameter can be set to drive a named property of the component (e.g. setting the Text property of a TextRenderComponent)
  • Functions - Parameters can be used in function calls to the component (e.g. calling SetBoxExtent on a BoxCollider component)

Tip
To learn what properties and functions are available to configure a component you will need to examine the source code for the component or the documentation available for it. e.g. the UTextRenderComponent docs.
Tip
Have a look through the procedures used to build the information stands and the spotlights in the Examples Project for tips on how to set up and place Actor Components.
Warning
Actor Component resources are considered experimental and subject to change as the way that placement parameters are applied to the properties and functions of the component is still being developed.

An example of how you would pass the parameters from your procedure to your component can be seen in the Spotlight procedure used to add a light source to the scene.

Root Category

The root of a Resource List is considered the 'category' of the assets within and forms the first part of the resource descriptor string. This should be named something that reflects this high-level organisation of your resources/assets.

Folders

Folders are simple organisational entries that can be added to your lists to introduce a hierarchy into the descriptor naming scheme.

Add a folder with the +FolderAdd Folder toolbar button. Rename with F2Rename button or the Name field in the details panel. Delete with the Remove toolbar button.

Drag & Drop Editing

Resources and the Resource List structure can be edited by dragging entries around. Valid places to drop are highlighted in green.

Note
Entries within a folder are always sorted alphabetically/numerically so you can't drop into specific places in a list

Assets can be dragged from the Content Browser into a Resource List and can perform two actions:

  • Drop on a folder - to create a new entry of the approriate type with that asset assigned.
  • Drop on an asset slot - to assign or replace the asset already present in that entry.

References Section

The references section of a Resource List is used to add links to other Resource Lists. This forms them into a larger tree of assets that all get searched when Apparance attempts to resolve a resource descriptor.

The project settings Root Resource is the starting point for this search and any assets you want to place need to be reachable somewhere in this tree of resource lists.

Entries are added to the References section using the +ResourceAdd Resource button like any other entry.

Missing Section

A special section is present at the bottom of every Resource List showing any resource resolution requests that have failed to find an entry. If there is a Resource List that corresponds to the category for the request then it will only be listed as missing in that Resource List. This can help you diagnose entries you need to add, or procedures that aren't requesting the correct descriptors. Resolution falls back to the default mesh or material as specified in the project settings.

Blueprints

Apparance Entities are blueprint scriptable in a number of ways.

  • Override generation parameters before Entity initially builds
  • Trigger rebuilding of a procedural Entity
  • Respond to the generation process completing
  • Show/Hide the generated content of an Entity
  • Populate/Depopulate the generated elements of an Entity
  • Handle procedurally placed procedural objects
  • Access placement parameters of non-procedural actors

Blueprint Functions

Various Blueprint functions are exposed by the Apparance plugin to allow sophisticated scripting of a procedural Entity.

Apparance Parameters

Procedural parameters are handled as a single type (Apparance Parameters structure) so passing them around is easy. There are helper functions to break apart, construct, and manipulate these parameters.

Working with parameters require parameter type selection in order to know which exact parameters types to expect. This is based on the signature of the available procedure inputs and appears in a drop-down in the Details panel for the node.

This then exposes each parameter value as individual pins which can optionally be toggled on and off in the details panel.

  • Break-out Parameters - Expose a parameter set as individual values
  • Make Parameters - Build a parameter set from individual values

You can also enumerate and explicitly access parameters:

  • Get Parameter Count - How many values in a parameter list
  • Get Parameter Type - What type is a parameter, accessed by index?
    • An FName from the following: "frame", "integer", "float", "bool", "string", "colour", "vector"
  • Get X Parameter - Get parameter of a specific type, by index.
  • Set X Parameter - Set parameter of a specific type, by index.

The auto-generated Unreal Blueprint parameter structure manipulation functions (Make ApparanceParameters and Set members in ApparanceParameters) are less useful as they don't take into account the type of parameter structure being used.

Generation Parameters

The parameters fed into an entity (via defaults, presets, instance, etc), and the final parameters used to run the procedure are both accessible in Blueprint scripts:

  • Get Placement Parameters - Access the instance parameters of an Entity Actor
  • Get Current Parameters - The actual, final, most recent, parameters fed to the procedure for generation

Generation Control

The procedure generation process is usually triggered by default when an Entity Actor is loaded (as part of a level, say), or created/instanced dynamically. Optionally you can re-trigger this process at a later date.

  • Rebuild - Just rebuild as-is immediately
  • Rebuild Deferred - Rebuild at the next frame Tick of the Apparance plugin

A more powerful function is available that takes parameter inputs for the procedure so you can change the way the procedure generates.

  • Rebuild Apparance Entity - take parameter inputs to cause an Entity rebuild.

This is configurable like the parameter break/make nodes by the procedure signature and optional input enable tickboxes.

Events

It is sometimes important to know when all the content of a procedure has been generated (or updated). For example, if you want to access and manipulate components you need to wait for (and respond to) this event. This could be anything from replacing materials with dynamic instances to driving a light intensity interactively.

  • Event GenerationComplete - Fires when the entity has completed generation and instancing of all content

Properties

A few built-in properties of an Apparance Entity Actor are exposed to scripting:

  • Set/Get Populated - Should the procedure attempt to generate any content yet, or remove existing content? (used to defer population).
  • Set/Get Shown - Show or hide the generated content (use to defer reveal of generated content)
  • Set/Get Procedure ID - Procedures are uniquely identified by a 32 bit integer ID, this provides access to that and even allows runtime switching of the procedure to generate an Entity's content from.
  • Set/Get Use Mesh Instancing - Enable/disable mesh instancing for the entity (requires Mesh Instancing project setting to be enabled)

Procedural Placement

If you have procedural objects that place other procedural objects then you can pass and receive placement parameters between the procedure using the Place operator and the Entity that actually gets placed. Actually, any Blueprint can access parameters it was placed with.

  • Get Placement Parameters - Access the parameters a Blueprinted object was placed with (i.e. via the Place operator).

Frames

Because Frame are not an Unreal native type a set of Blueprint functions are provided to work with them

  • Make Frame from Box - Turn an Unreal FBox structure into an equivalent Frame
  • Make Frame from Euler - Turn an offset, size, and a set of orientation angles into an equivalent Frame
  • Make Frame from Rotator - Turn an offset, size, and an FRotator into an equivalent Frame
  • Make Frame from Transform - Turn an FMatrix transform into an equivalent Frame
  • Get Frame Euler - Access the orientation of a Frame as a set of Euler angles (roll, pitch, yaw)
  • Get Frame Orientation - Access the orientation of a Frame as a rotation FMatrix
  • Get Frame Origin - Access the origin of a Frame as an FVector
  • Get Frame Rotator - Access the orientation of a Frame as an FRotator
  • Get Frame Size - Access the size of a Frame as an FVector
  • Get Frame Transform - Access the full transform of a Frame as an FMatrix

The automatically generated Unreal Frame functions Make ApparanceFrame and Set members in ApparanceParameters are not particularly useful as there is no way to manipulate an existing Frame structure and there are not publicly exposed members of the Frame structure.

Misc Blueprint Functions

  • Is Game Running - Is Unreal currently Playing in Editor, Simulating in Editor, or running as a Standalone Application.
  • Cast To X - Safely cast an object to the specified type

Parameters are stored in a binary form, for whatever reason you might want to, you can access this:

  • Get Input Parameter Data - Access the raw data BLOB used to store the input parameters of an Entity Actor
  • Get Preset Parameter Data - Access the raw data BLOB used to store the input parameters of an Entity Preset

Some auto-generated helpers for accessing Preset properties

  • Get Procedure ID - The procedure ID of the Preset
  • Get Use Mesh Instancing - Whether mesh instancing support is enabled for the preset

Apparance Information Panel

The Apparance About panel has several sections and is not just a general version/about box. The following sections can be accessed (some have direct shortcuts from the Apparance Menu):

  • Setup Wizard
  • About Apparance
  • Release Notes
  • Status
  • License & Usage
  • Credits
  • Attribution

Some pages have items with action buttons to help you quickly access information or perform some useful function (e.g. getting set up).