Unitscape Documentation

Documentation

  • About Unitscape
    • Purpose
  • Installation
    • Installing
    • Uninstalling
  • Getting Started
    • First Steps
    • Creating Shapes
    • Creating Instance Sets
  • User Interface
    • Main Toolbar
    • Overlay Menu
  • Instancing
    • Instance Set
    • Unitscape Actor
  • Shape System
    • General information
    • Shape Component
    • Path Deform
  • Shape Tools
    • Polygon Tool
    • Path Tool
    • Strip Tool
    • Fill Tool
    • Ring Tool
    • Cut Tool
    • Outline Tool
    • Quad Tool


Polygon Tool

Missing Something? Let us know if this page needs more information about the topic.


Path Tool


Purpose

Unitscape was designed as a shape based world creation tool for Unreal Engine to bridge the gap between pure procedural content generation and artistically driven scene composition, giving you the best of two worlds in a powerful yet easy to use software package.

To accomplish this Unitscape makes use of custom artist-defined "Instance Sets", which are a set or a composition of objects, which can be applied/scattered to user-defined shapes in a Unitscape Level using a powerful boolean shape system, which seamlessly connects all shapes in the level to enable non-destructive editing workflows and that can also be used to provide better spatial awareness of the entire environment.


Populating Instances


Path Deform


Strip Tool


Unitscape Actor

The Unitscape Actor is the host actor for all Unitscape shapes and is reponsible for drawing the instanced geometry. Any new shape
that is created in the Unitscape Editor mode will be added as a component of its shape tree.

Theoretically there can be more than one Unitscape actor, although it is not advised to have more than one in your scene, since this
will degrade rendering performance.

Hiding the Unitscape Actor will also hide all Unitscape shapes and instances in the scene.


Uninstalling

Use the Programs and Features dialog to locate the Unitscape entry. Use the uninstall option to uninstall Unitscape for Unreal Engine.
If you don't plan on re-installing Unitscape and you installed the Content Library you may have to manually delete the "External Content"
shortcut at Program Files\Epic Games\UE_4.26\Engine\Plugins\Ephere\Unitscape\Content .

This will not delete the external Unitscape content library, which will have to be manually removed as well(if desired).


Randomization


Quad Tool


Shape Component

Populating Instances : Specifies instance set geometry

Tiling : Instance Set Tiling settings

Randomization : Per instance - randomization settings

Instance Grounding : Per instance grounding settings

Instance Set Transform : Transform applied to instance sets

Hide Instances : Hides all instances created by this shape

|


Ring Tool


Fill Tool


General information

Everything connected

Unitscape's boolean shape system was designed as a means to spatially connect all the areas of a map ( mountains, forests, fields, roads, cities, buildings,...) with one-another thus providing more detailed spatial information about the environment (that can also be used for agent navigation) while at the same time making level design much easier by offering a non destructive workflow with a set of easy to use (and easy to randomize) world shaping tools along with powerful procedural content generation methods.

Boolean operations and shape attachment

By default Unitscape shapes are cut according to their shape layering index, meaning that a shape at the top level will cut a hole into all the shapes that are placed below it.
When a shape component is attached to another shape component (in the component tree) the child shape will cut the parent shape (since it is automatically assumed that the child will be blaced "above" the parent". In addition to that the child shape is also being cut by the parent shape at its border(to assure the child shape will not overlap the parent shape).

To change the shape's layering index you can use the "Send to front" / "Send to back" buttons in the Overlay Menu.


First Steps

Opening the example scene

  1. Open a new or any existing Unreal Engine Project and make sure Unitscape plugin is activated as outlined here:Installing
  2. Click on the Unitscape symbol to toggle the toolbar and click on Content to open the Unitscape Content Browser
  3. You will find four scenes listed here, the first two can be used as starting points(with lighting & post process settings already set up) when you intend to start from scratch.
  4. For now just open the "Example scene with landscape and Unitscape shapes".

When doing this for the first time expect substantial load times! As Unreal Engine will compile a lot of shaders in the background!

Exploring the example scene

  1. When first opening any Unitscape scene you'll likely see transparent shapes that contain instanced geometry, you can press G on your keyboard to activate the game mode, which will hide these shapes.
  2. Explore the scene which mainly consists of a Unitscape path (for the canyon) and a couple of background shapes containing Canyon rocks.
  3. In the level you should see a single Unitscape Actor which contains all the shapes and is responsible for managing and rendering all instances. Individual shapes can be selected by double clicking the shape inside the editor
    which will select the shape component.

Unitscape currently uses a component based approach to manage all the shapes in the scene to allow for a more procedural and hierarchical workflow as well as not to clutter the level with too many objects.
However going forward Unitscape is also going to offer an option to use "Shape-Actors" as well as "Shape-Components" with the ability to attach or detach them to the main Unitscape actor at any time.

Applying randomization and changing shape geometry

As you might have noticed, as soon as a shape or the Unitscape actor is selected an Overlay Menu is being displayed in the Editor viewport, you can click on it to expand it. The contextual overlay menu contains the most important shape and instancing settings in a condensed, easily accessible form even when in full screen mode (F11).

  1. Select a shape and try the randomize+ /randomize- buttons which will change the randomization seeds for the instance transforms for each shapes. Randomization can be controlled more precisely in the detail settings of each shape component.
  2. Also try changing the assigned Instance Set asset which will apply a completely different look to your shape ( when loading an instance set for the first time Unreal Engine will compile shaders, so expect some loading delays here as well).

Use top view to make more precise adjustments and to create new shapes

While it is possible to edit existing and also create new shapes in Edit Mode we highly recommend using the top view to create the scene's shape layout.
To make that switch between perspective and top view easier we integrated a toggle button in the Unitscape toolbar:


Creating Instance Sets

Creating an Instance Set is very simple in Unitscape, you simply select all the actors in your scene you want to be part of the instance set
and then right click in the content browser to create the instance set from selection as shown in this video:

Creating custom bounding box to prevent tiling gaps

It is advised you also create a bounding box for your instance set to make sure there will be no gaps between tiles of the instance set
(when the shape is larger than the instance set tiling will automatically be applied to it).
To create a custom bounding box you can use any sort of volume and make sure its name begins with "bounds" like shown here:

Actor attachment

You can attach actors to other actors to make sure the objects are grounded properly, like a bench with some items placed on it :

Hierarchical instance sets

Alternatively you can also use instance sets in other instance Sets and build a hierarchy this way (which achieves the same thing),
you can simply drag any instance set in the scene and make it part of another instance set simply by having it selected when you create
the new instance set asset:


Cut Tool


Creating Shapes

Open the Unitscape Editor mode, either by toggling the Unitscape icon in the main Editor toolbar or by clicking any tool in the Overlay Menu.

It is strongly recommended to create all shapes in top view. You can toggle between perspective and top view by using the "Top" button in the toolbar.

By default spline point interpolation type is set to linear for all curves, it can be changed to "curved" in the Shape Component details panel.

Here are a few examples of tool usage in Unitscape:


Main Toolbar

Please note that all of the tools listed here are still under heavy development and subject to frequent changes.

The main toolbar can be toggled by clicking the Unitscape Icon in Unreal Editor's top toolbar, doing this will also activate the Unitscape editor mode.

For better precision we recommend using the shape tools in top view.

  1. Select : Deactivates any tool, so that you may select objects in the scene.
  2. Poly : Activates the Polygon Tool which enables basic poly shape drawing mode.
  3. Path : Using the Path Tool is the easiest way to quickly create a path in your scene.
  4. Strip: The Strip Tool offers a more precise way of creating paths allowing you to specify exact point placement, which can be useful when tracing existing blueprints.
  5. Fill: Fill Tool allows you to place "fill anchors" in the scene which will override the shape settings (i.e. instancing settings) at the location the "anchor" is placed .
  6. Ring: The Ring Tool will create a child-shape of the shape you are currently hovering over, creating an evenly shaped hole in the parent polygon.
  7. Cut: The Cut Tool will simply cut a shape in two pieces (more precisely it will create two new child shapes at the location of the cut overriding the parent shape).
  8. Outline: Outline Tool allows creating a shape along the borders of any polygon or path. Note that this tool is currently still under heavy development.
  9. Quad: Using theQuad Tool you can place quads in the layout that are automatically aligned to the closed polygon border and are automatically resized to fit the currently used Instance Set
  10. Top: Toggles between top and perspective view
  11. Content: Opens the Unitscape Content Browser

Here is a video showing basic tool usage:


Instance Set Transform


Overlay Menu

Please beware that the Overlay menu is subject to frequent changes.

When selecting a Unitscape - actor or shape component in the scene a small overlay menu is displayed at the bottom right corner
of the viewport. It can be expanded by clicking on the title bar. The Overlay itself is divided into three sections, the toolbar,
the shape settings and the instancing settings:

Mini Toolbar

A miniature version of the Main Toolbar.

Shape Settings

  1. Send to front/back : Adjusts shape layering for boolean operations.
  2. Randomize -/+ : Increases/Decreases randomization seed for the instance transform, can be more precisely adjusted in Shape Component settings.

Instancing Settings

  1. Toggle between Instance Set / Static Mesh usage as source for shape instance geometry (most of the time Instance Set will be used).
  2. Rotate left/right : Rotates instance set by 90Â° to the left or right.
  3. Library : Opens content browser window.
  4. Reload : Reloads the currently selected instance set (in case changes were made to the asset)
  5. Select : Selects all shapes that have the specified Instance Set assigned.


Outline Tool


Installing

Installing Unitscape

  1. Run Unitscape Installer
  2. Open a new or an existing Unreal Engine Project in the Unreal Engine Editor
  3. Go to Edit->Plugins and search for "Unitscape" and activate the plugin :

After having restarted the Editor you will be asked to license the software, click on "Assign License" to do so:

Once the Unreal Editor has restarted again click the Unitscape Symbol on the main Editor toolbar, which will activate the Unitscape Toolbar:

Installing Content Library

  1. Click on the "Content" Icon in the Unitscape toolbar to fire up the content browser:

  1. Follow the steps outlined there, i.e. Downloading the content archive and extract it anywhere
    in your file System(i.e. like "D:\Unitscape\Content"), please don't put the content inside your Game Project directly!

A directory junction (a shortcut) will be automatically created by the plugin to link from "Program Files\Epic Games\UE_4.26\Engine\Plugins\Ephere\Unitscape\Content\ExternalContent" to the specified location.
If you intend to move your content directory to another location later on this shortcut ("ExternalContent") has to be deleted before doing so. Please make sure the Editor is not running when doing this.

2. Then locate the directory using button button "2." and confirm and restart the Editor again.

An "ExternalContent" link should now exist at "Program Files\Epic Games\UE_4.26\Engine\Plugins\Ephere\Unitscape\Content\ExternalContent" :

3. After restart open the content browser again and you should be seeing a list of example scenes:

  1. The first two example can be used as starting points for building scenes from scratch.
    Click on the item labled "Example scene with landscape and Unitscape shapes" which will open that scene.

Warning! Opening this scene for the first time only might take a significant amount of time and Unreal Engine might become unresponsive
for a while! We are working on improving this with future releases. Should you experience any crashes during this time this might be caused by a lack
of available memory on your C: drive, which may be used by Unreal Engine to store temporary data.


Instance Set

An instance set is a collection or composition of static mesh actors which can be applied as a "scatter pattern" to populate Unitscape shapes with geometry, that can be transformed, grounded, randomized and even conformed to the underlying geometry(such as a landscape actor) on a per-shape basis. Instance sets provide a great way to infuse "artistic vision" into otherwise purely procedural object scattering.

Here are a few examples showing different types of "instance sets" applied to the same shape with different settings:

Generally speaking the wider the instance set(and the more objects in it) the better the visual result since this reduces pattern repetition when tiling and also provides more flexibility when transforming the instance set gizmo on each shape. Ideally an instance set should be wider than the shape it is being assigned to.


Instance Grounding