Usage

Getting started

Project Settings

Open Edit → Project Settings → World Graph Editor. From here you can configure:

• Node background opacity in the graph window;
• Port highlight mode in the Hierarchy (names and colors, names only, or no highlighting);
• Unity main toolbar extensions: a quick-access button for the Transition Manager prefab (labelled TM) and a scene dropdown with Neighbours (scenes adjacent to the active one in the graph), Build Settings, and All Scenes modes;
• The array of custom scene validation tests;
• Force-refresh affected scenes on graph save — when enabled, every scene affected by port changes is opened one by one on graph save and its ITransitionComponent components are force-refreshed. This prevents PortsDropdown values from being reset when ports are renamed in the graph;
• Use Custom Transition Manager and the Container field — switches to a custom TransitionManager implementation.

Creating a WorldGraphContainer

1. In your Project window, create a WorldGraphContainer:
   • RMB → Create → World Graph Editor → World Graph Container;
2. Double-click the created asset with LMB to open the editor window.

Adding scenes

Drag the scenes you want into the editor window to create nodes. Every node represents a scene, and every port on a node represents a transition to another scene.

warning

Avoid duplicating scenes — this leads to errors. Duplicates are highlighted in red.

Port kinds

Clicking the "+" button on a node opens a context menu with the following port types:

• Left Passage, Right Passage, Top Passage, Bottom Passage — connection ports (passages) used to link nodes together;
• Additional Port — a non-connection port used for things like fast-travel systems.

Creating ports and connections

1. Press "+" on a node and create a passage port;
2. Drag a connection from the port on the first node to the middle of the second node;
3. If everything is set up correctly, a connection appears between the nodes.

You have now defined which passages connect the two scenes. You can further tune ports in the Inspector — select a node to edit its parameters.

warning

Every port on a node must have a unique name, and the name cannot be empty or whitespace-only. Otherwise you will get errors.

Connection types

• Undirected — Default. Traversal is possible in both directions;
• Shortcut — The passage is initially accessible only from one side (e.g. a locked door that opens from the other side). Can be honored by a custom port implementation and block the transition based on a bool flag;
• One-Way — A connection that can only be traversed in a single direction.

The type is set from the context menu that opens with RMB on an existing connection.

Saving and configuration

Saving the graph

When you are done editing, press "Save" to persist the graph.

note

On save, all unconnected passage ports (except Additional Ports) are removed, and you will be prompted to add all used scenes to Build Settings, which is required for later steps.

Setting up the built-in TransitionManager

1. Make sure the manager exists at Assets/WorldGraphEditor/Resources/TransitionManager. If not, create it via the menu:
   • Tools → World Graph Editor → Create Transition Manager Prefab;
2. Drag the saved WorldGraphContainer into the corresponding field on the TransitionManager. This tells the manager which container to use;
3. Set AutoLoad to true so the manager is loaded automatically on game start;
4. Enable the checkbox on the right side of the PlayerPrefab field and assign your player prefab.

With this in place, the player object is created automatically on every scene. If you need a different loading flow, see Manual start of the built-in TransitionManager.

Setting up scenes

To represent ports on scenes, add matching components.

Out of the box you have:

• Passage2D — Moves the player to the opposite port based on the connection defined in the graph;
• Teleport2D — Moves the player to any other port in the graph.

You can also define a default position by adding an object with the DefaultSpawnPosition component to the scene. If no output OutputTransitionComponent is found on the scene, the player spawns at that position.

Configuring components

• Passage2D
  • In the AssignedPort field, pick the passage name that matches the port in the graph.
• Teleport2D
  • In the AssignedPort field, pick the passage name that matches the port in the graph;
  • In the GoTo field, pick the port to teleport to.

tip

Each port on the scene must reference exactly one port on the node in its AssignedPort field.

If needed, you can write custom implementations.

Play Mode behavior

Expected behavior

• On start, a TransitionManager object is automatically created in DontDestroyOnLoad;
• When the character touches a port object, they travel to the target scene and spawn at the position of the matching port.

Errors

If the target port is missing on the scene:

• The player spawns at the position set by DefaultSpawnPoint, or at (0, 0, 0) if none is defined;
• An error is logged to the console.

warning

The console will log a warning when:

• With the built-in TransitionManager enabled:
  • TransitionManager is missing at Assets/WorldGraphEditor/Resources/TransitionManager;
  • The Container field on the TransitionManager is empty.
• With a custom TransitionManager enabled:
  • The Container field in Project Settings is empty.
• The container has errors;
• Scenes in Build Settings were removed, disabled, or reordered.

The console will print an error with a fix hint.

Scene View overlays

Two built-in overlays ship with the package: Scene Inspector WGE and Screenshot Utility WGE. You can enable, pin, and hide them like any other Scene View overlay.

Scene Inspector WGE

Displays a short status of the Transition Manager and container configuration: whether the container is assigned, whether the data has errors, whether scenes match Build Settings, and which TransitionManager is in use — the built-in one or a custom one (Default / Custom). For the active scene, a summary of graph compliance is shown (including scene and port data availability). The bottom of the panel has a Project Settings button that opens Edit → Project Settings → World Graph Editor.

Screenshot Utility WGE

Used to capture a preview of the current scene, which is then rendered on the scene node in the graph window. You can configure the frame area (position, size, rotation), distance and camera type (perspective / orthographic), and image parameters (resolution, mode for non-power-of-two textures). Settings can be saved for the current scene (Save Scene Preset), promoted to a global default for scenes without their own settings (Save as Global Default), or reverted to built-in defaults (Reset to Built-In). The Take Screenshot button saves the image; positioning handles and a frame rectangle are shown in the Scene View.

If auto-capture is disabled for the current scene (see below), the overlay hides the framing fields and shows a message with an Enable Auto-Preview button.

The graph window's toolbar has a Capture Scene Previews button that captures previews in a batch (auto) for all available scenes in the graph.

The node Inspector (the Scene Preview section) exposes a Delete Preview button (removes the screenshot file; disabled if no file is present) and an Enable/Disable Auto-Preview button (toggles capture and display of a preview for that specific scene; supports Undo/Redo). When auto-capture is disabled, the graph node and Inspector do not show a preview for the scene, and the scene is skipped by batch capture; any existing screenshot file is preserved.

Scene validation

In addition to basic data-integrity checks (container health, Build Settings match), the package can run a suite of tests against every scene in the graph.

Built-in tests

Test	What it checks	Status on failure
Missing Ports	Every port from the graph has a matching ITransitionComponent on the scene.	Warning
Ports Duplicates	No two ITransitionComponents on the scene share the same Guid.	Error
Reachability	All scenes are reachable from the starting scene via the graph (SCC algorithm).	Groups of unreachable scenes are stored in the result.

How to run

• Manually: Edit → Project Settings → World Graph Editor, the Validate Project button. Runs the built-in and all user-registered tests against every scene of the graph and stores the result in the ProjectValidationResult asset. The Open Result button opens the validation result in the Inspector.
• On player build: ValidationBuildProcessor (IPreprocessBuildWithReport) verifies container integrity and Build Settings alignment. If the two are out of sync it offers to synchronize the container; on any other error the build is halted with a diagnostic message. The full test suite is not run on build — use Validate Project manually for that.
• On graph save: scene paths and build indices are updated; user tests do not run on save.

Where to find the result

The result is stored at Assets/WorldGraphEditor/ProjectValidationResult.asset.

After running validation, the Open Result button becomes active and opens that asset in the Inspector for review.

The asset itself holds a reference to the validated container, some flags (_ignoreShortcuts, _considerAdditionalPorts), and the reachability result as SCC groups.

Custom test

A test is a ScriptableObject inheriting from SceneTestBase (which implements ISceneTest) with the following methods:

Method	Description
TestResult Run(in TestContext context)	Receives a TestContext, called once per scene on load. Must return a TestResult.
void Init()	Optional. Called once before the first scene is loaded. Useful for initialization or resetting state accumulated between validation runs.

General template:

[CreateAssetMenu(menuName = "My Game/Validation/My Custom Test")]
public class MyCustomSceneTest : SceneTestBase
{
	public override TestResult Run(in TestContext context)
	{
		// context.SceneNodeData holds data for the current scene's node: ports, scene name, paths.

        if (/* failure condition */ false)
	        return new TestResult(TestStatusType.Warning, "Description of the problem for the report.");

        return new TestResult(TestStatusType.Passed, "OK");
    }
}

Concrete example:

Suppose your project has collectible items with unique identifiers and you need to make sure no two unique IDs collide across the whole project. The test could look like this:

[CreateAssetMenu(menuName = "My Game/Validation/My Coin Test")]
public class CoinsIDTest : SceneTestBase
{
    private HashSet<string> _coinsIds;

    public override void Init()
    {
        _coinsIds = new HashSet<string>();
    }

    public override TestResult Run(in TestContext context)
    {
        var coins = FindObjectsByType<Coin>(FindObjectsSortMode.None);

        foreach (var coin in coins)
        {
            if (!_coinsIds.Add(coin.Id))
                return new TestResult(TestStatusType.Error, $"Coin with ID [{coin.Id}] already exists.");
        }

        return new TestResult(TestStatusType.Passed, "All coin IDs are unique.");
    }
}

Possible test statuses:

public enum TestStatusType
{
    Passed,
    Warning,
    Error
}

Once the asset is created, add it to the Custom Tests array in Edit → Project Settings → World Graph Editor (Validation section). On the next Validate Project run your test will be executed for every scene in the graph.

note

The ISceneTest contract lives under #if UNITY_EDITOR — tests run only in the editor and are not included in the build.

Addressables support

Addressables support is enabled automatically when the com.unity.addressables package is installed — this is set up through versionDefines in the package's asmdefs, which enable the WGE_ADDRESSABLES define. Nothing needs to be enabled manually; if the package is absent, the feature simply stays inactive and no compilation errors are raised.

To load a scene through Addressables, add it to your Addressables Groups the usual way (Window → Asset Management → Addressables → Groups). The graph picks that up on its own via the Addressables settings.

Editor affordances:

• A node in the graph displays an "ADR" badge (top-left corner) with a Loaded via Addressables tooltip that also includes the address, when set.
• The node Inspector (Scene Node Data) shows a HelpBox: "This scene is loaded via Addressables at runtime. It is not required in Build Settings."

note

Scenes marked as Addressable are excluded from the Build Settings requirement — they are skipped by both the validator and the auto-add step on graph save.

At the API level, both graphs (WorldGraph and EditorGraph) expose a TryGetSceneDataByAddress(string address, out TSceneData data) method — it only exists when Addressables is enabled (#if WGE_ADDRESSABLES).

The built-in TransitionManager handles Addressables automatically: during a transition it looks at RuntimeTransitionData.GetTargetSceneAddress() — if an address is set, the scene loads via Addressables.LoadSceneAsync(address, LoadSceneMode.Single); otherwise it falls back to SceneManager.LoadSceneAsync(buildIndex). No manual routing is required.

note

If you write a custom TransitionManager, Addressables loading is your responsibility — the scene address is available via RuntimeTransitionData.GetTargetSceneAddress() / SceneRuntimeData.GetAddress().