Entities

Entities are the presence in the 3D world of Apparance procedural objects. Each provides an instance of a single procedure with a specific set of input parameters. It acts as a container for all geometry generated and all objects placed procedurally by the execution of the associated procedure.

Transform

Entities are positioned in the 3D world of the engine like any other game object. They are position independent; all construction made in object space. It is usual to have the first parameter be a frame that can be used to describe an objects desired size (and also potentially an offset and orientation).

[0] Frame – Entity OABB, optional offset and orientation adjustment.

• Local space (Unreal default, Unity future) – In Unreal the input frame is always treated as in local/object space with the literal value set in the details panel being the values the procedure sees. This can include position, orientation, and size. Moving the entity in the world has no effect on the generated content and no rebuild is triggered.
• World space (Unreal N/A, Unity current) – In Unity the input frame is always injected with the current world location and orientation. The size coming from an attached Box Collider. As the entity is moved in the world, the procedure is re-run with the new world space information. For now, if you don’t need this world context you can just ignore the transform position and treat the passed frame as local. (although it will still take on orientation and size from the game object).
• Handedness – Apparance coordinate system is right-handed with Z up, and any information passed into Apparance procedures is treated as such. Conversion from engine coordinates is done where necessary (e.g. world space injection).
• Orientation – Apparance Frame data carries orientation around as three basis axis vectors (i.e. not rotations). This is still exposed as Euler angles in some places for easy of hand authoring, but generally doesn’t have to be worried about.
• Scale – Entity scale isn’t used and should always remain at identity (1,1,1). Changing this causes issues for placed sub-objects and any internal arrangement of objects (would require engine skew matrix support). For procedural objects the concept of size is much more useful, and passed/injected in instead. If using local space and you require context information from (or linked to) the world transform then you can generate and inject this using a script. This will then cause the procedure to update as the entity is moved or transformed around the world.

Parameters

Obtained in this order of increasing priority, each having the potential to be overridden by the next independently.

1. Procedure – Each procedure definition can have a specific default value set for each parameter in the Apparance Editor.
2. Preset – If an entity instance in the world is based on a Preset, these can override default procedure parameter settings. Association with a Preset can be changed or removed if needed.
3. Entity – Any entity instance placed in the world can have parameters explicitly set over default. If a parameter is set in script it is disabled in the details panel for those instances and can’t be edited.
4. Script/Blueprint set – individual parameters can be set programmatically in script/blueprints. Typically this is done in the construction script, but you may need to also set it in response to the BeginPlay event (i.e. for level loaded actors), often a blueprint function helps here as the same code can be used easily in each case.

Any changes within this hierarchy of parameter sources will result in all affected entities in the world updating to reflect the new parameter composition.

State

• Population – Control when generation occurs. Can be used to delay initial generation until needed by setting to false and programmatically setting to true at a later date (e.g. based on player proximity). Note: There is always at least a frame delay (for generation and instancing to occur) once this is set to true so there won’t immediately be something to display. When available it will appear, assuming Visibility is true. De-population is always within one frame.
• Visibility – Similar to Population but immediately show/hide the content (assuming it is populated and at least one generation run has completed).
• Frozen (Unity, Unreal in future) – Certain internal systems can be disabled to increase performance in situations where you have a huge quantity of entities (thousands). Marking an Entity as Frozen locks the generated content and rebuilds won’t happen.
• Readable (Unity only) – In situations where you require access to the generated geometry (triangle and vertex data) you need to mark the entity as Readable. A use case for this is if you are writing utilities to bake out procedurally generated meshes.

Worlds

Many engines support multiple scenes or worlds existing at the same time. This can be for preview windows, blueprint/prefab editing, or a separate world spun up for in-editor play testing. Apparance recognises this and partitions any Entity instances according to the host engines world setup. This is important for any inter-object awareness and interaction to work properly. Mostly this isn’t something you need to worry about, as it is handled for you. In the Apparance Editor advanced view mode (Alt+F12) you can see if multiple worlds are in use and which entity instances are present in each. NOTE: Internally Apparance uses the term ‘Universe’ for each world or scene the host is running.

Misc

• Autoseed – This is a test feature for exploring procedural variation space and providing a nice ‘slide-show’ of some procedural systems. Set the Autoseed period (seconds) and enable to repeatedly rebuild the entity with ever incrementing seed value.

Resources

“Resource” is the Apparance term for any game engine asset that can be used by the procedural generation system. Because Apparance procedures are engine agnostic, a mapping layer is needed to associate engine assets, such as meshes or materials, with some form of descriptor that Apparance can use to tell the engine what is needed.

The plugin integration provides custom asset types to help build up and maintain these mappings. Each has a UI to build up lists of resources, keyed by descriptor, for you to link to the engines assets.

Resource Descriptors

A resource descriptor is a text string that can take any form, but there are several recommended naming conventions that are supported to help organise them.

resource_category.organisational_hierarchy.resource_name

• The descriptor is partitioned into elements by full-stops ‘.’
• The first element is used as a top-level categorisation for the resource, providing global grouping of resources.
• The remaining elements are effectively a ‘path’ to describe the resource, providing grouping and organisation of a hierarchical nature to the resource.

This organisational ‘pathing’ is visualised as a hierarchy in the plugins Resource management UI.

Descriptors can be fixed constant strings in the procedures that use them to look up resources, but they can also be procedurally composed from elements using text operators. This allows dynamic switching of resource use, or just dynamic selection based on any procedural logic you desire. Dynamic selection of the top-level category can be used as a means of ‘skinning’ procedural creations, switching between large banks of different resources to completely re-style the generated object or scenery.

Resource List

The Resource List is the main way to map descriptors to engine assets. It is an asset type in its own right within the engine and has a UI to edit and manage the resource references.

Resource Table (Unity only)

To avoid the issue of Resource List references keeping assets loaded unnecessarily, indirection via text-based Resource List lookup allows lazy loading and timely release of unused assets. A Resource Table provides hints to the resource lookup process by allowing pre-filtering of the Resource Lists searched based on the descriptor category element. This takes two forms: * The asset name prefix to add to the category element. E.g. “City” -> “PCG_City” * A list of substitutions for certain descriptor Categories. E.g. “City.Default” -> “PCG_City.Tone.Default” These Resource List names are used to resolve and load the Resource List assets dynamically, by name. This breaks the reference dependency in the engine. This means you will need to ensure the referenced assets are included in any packaged build as they may be ignored otherwise and not found at runtime.

Resource Types

• Meshes – Single static meshes can be placed, with scaling as needed to fit the prescribed frame.
• Prefabs (Unity only) – One or more meshes, and optional Box Collider to override bounds information. Procedural prefabs shouldn’t be scaled, instead pass in size information or bounding frame.
• Blueprints (Unreal only) – Actor placement, with scaling to fix prescribed frame. Procedural blueprints shouldn’t be scaled, instead pass in size information or bounding frame.
• Components (Unreal yes, Unity future) – Add actor components of any type, for example light sources, collision primitives, or effects emitters. See below for parameterisation options.
• Materials – Materials can be assigned to procedurally generated geometry.
• Textures (Unreal yes, Unity future) – Textures can be passed to material instances to vary their appearance.
• Resource List References – Resource Lists can reference other resource lists to build an organisational hierarchy.

Asset Information

• Bounds – The bounding box of an asset is based on the mesh bounds by default, but can be overridden by adding a Box Collider to a prefab (Unity only), or explicitly via values or a reference mesh (Unreal only).
• Copy (Unity Only) – Set to true to use a material instance/copy instead of the source material asset on generated geometry. This is needed for materials that have parameters changed at runtime so that the original material assets don’t always show up as modified. (There is a script API to access the copy).
• Collision (Unreal Only, Unity Future) – Causes geometry marked as such to be added to the engine as a collision mesh as well as visible. Set the actual material asset reference to empty to just add as collision geometry.
• Variants – If a Resource is set to be a variant it can reference a list of assets instead of just one. The quantity of them can be queried within the procedures, and then selected by number.

Parameterisation

• Component setup (Unreal yes, Unity future)
• Common
  • Setting Properties
  • Calling Functions
  • Parameter Map

Documentation Work In Progress

Custom Resource Resolution

Documentation Work In Progress

Custom Resource Instantiation

Documentation Work In Progress

Unreal Plugin Differences

Currently the implementation and feature set of the Unreal and Unity plugins differ. Here are the main things to consider when working in Unreal instead of Unity.

• Resource lookup always starts with a ‘root’ resource list.
• The root resource list is defined globally in the project settings.
• Resource lists can contain references to other resource lists (facilitating organisation).
• Resources can only be resolved if they are in a list that is linked back to the root resource list.
• Resource Tables are not needed by the Unreal Plugin.
• There is no Apparance Engine object to add to your levels, this is implicit and configured in the project settings.

Unity Plugin Differences

Currently the implementation and feature set of the Unreal and Unity plugins differ. Here are the main things to consider when working in Unity instead of Unreal.

• Resource lookup always starts with the scene Apparance Engine object.
• The Apparance Engine object maintains references to Resource Lists and Resource Tables to use for resource resolution.
• Resource Table assets must be referenced by the Apparance Engine object to be searched.
• Resource List assets must be referenced by the Apparance Engine object to be searched (unless resolved via a Resource Table).
• The Apparance Engine object has its own Resource List component that can be used to reference assets.
• Variants are handled by naming convention, if you want a resource entry to behave as a variant you need to rename it to end with “#1”. The entry and UI will switch to allow multiple assets to be assigned to that one descriptor.
• Resource Tables are provided as an optimisation for the problem of resource list references causing preloading of assets in Unity.
• Resource descriptor hierarchy is supported by a Category field at the top of the Resource List UI and by naming the resource with the dot separators explicitly (not including the category). Once named the UI will show this hierarchy as expandable entries.