Rooms, Portals, and Navigation
Polygon Engine provides two independent, fixed-capacity world systems:
- Rooms and Portals conservatively reject renderers outside the camera's potentially visible portal chain.
- Navigation bakes height-aware grid samples and moves NavMesh Agent GameObjects along three-dimensional runtime paths.
Author both from View > Advanced Scene Authoring > Rooms & Navigation.
Rooms
A Room is an axis-aligned volume centered on the GameObject Transform plus its authored offset.
| Property | Meaning |
|---|---|
| Enabled | Include the room in runtime queries |
| Name | Unique scene-local label |
| Size | Width, height, and depth of the volume |
| Offset | Local offset from the room GameObject position |
| Priority | Tie-breaker when volumes overlap; highest wins |
Assign environment Mesh Renderers with Renderer Room. An unassigned renderer remains globally eligible for the normal visibility path.
At runtime, the camera room is the highest-priority enabled Room whose AABB contains the camera. The renderer remains eligible when it is global or its assigned room is retained by the runtime portal traversal.
Portals and Recursive Connectivity
A Portal references Room A and Room B and stores an enabled/open state, opening width and height, and Two Sided flag. The PS1 runtime traverses the graph recursively:
- A can reach B through every enabled open Portal;
- B can reach A only when that Portal is Two Sided;
- every valid opening directly adjacent to the camera room is retained;
- later rooms are retained only when the incoming and outgoing conservative aperture cones overlap.
Each cone contains the complete authored rectangular opening. The test is deliberately broader than exact portal-plane clipping, so it can retain rooms that are not ultimately visible. Invalid graph references, missing or malformed portal transforms, an unknown camera room, a camera inside an opening, queue pressure, or other ambiguous data fail open instead of risking a missing room. Global and unknown room assignments also remain visible.
Editor Play Mode and the PS1 runtime share the same conservative aperture math, recursion limits and fail-open policy, so room eligibility matches for the same camera and scene state. Validate performance and final presentation in the packaged build. This system does not provide hardware occlusion queries, automatic room splitting, or automatic per-triangle room assignment.
Lua can change a Portal at runtime:
local doorPortal = -1
function Start(gameObjectId)
doorPortal = GameObject.Find("Door Portal")
end
function openDoor(gameObjectId)
Portal.SetOpen(doorPortal, true)
end
See the Portal Lua API.
Height-Aware Navigation Bake
Add NavMesh Surface to a root GameObject. Its volume establishes an X/Z grid and a vertical sampling range. The surface may rotate around Y. The surface center Y remains a backward-compatible base floor, while explicit traversable box faces add or replace quantized layers. The bake creates deterministic four-neighbour links between compatible samples.
| Surface property | Default | Bake effect |
|---|---|---|
| Size / Offset | 16,4,16 / 0,0,0 | Bounds the sampled volume |
| Cell Size | 0.50 | X/Z grid resolution |
| Cell Height | 0.25 | Quantizes sampled heights |
| Agent Radius | 0.30 | Expands obstacle clearance |
| Agent Height | 1.80 | Rejects nodes without enough headroom |
| Max Step | 0.35 | Maximum normal neighbour height difference |
| Max Slope | 45 degrees | Rejects steeper walkable faces |
| Max Drop | 1.50 | Maximum authored one-way WalkOff descent |
The bake can retain multiple Y samples at the same X/Z cell, allowing overlapping floors inside one surface volume. Increase the volume height and place explicit walkable geometry at each level.
Navigation Modifier Areas
Navigation Modifier classifies a Collider for the bake. Modifier geometry must be on a root GameObject.
| Area | Collider rule | Result |
|---|---|---|
| Obstacle | Non-trigger box or sphere | Blocks covered navigation cells |
| Walkable | Solid box | Samples the box's upper face as traversable geometry |
| Platform | Solid box | Same static bake behavior as Walkable; useful authoring label for platforms |
| WalkOff | Trigger volume | Allows downward-only links from covered source cells |
Walkable and Platform boxes may be rotated or sloped. The baker evaluates the
actual transformed upper plane, its height, and its slope. Platform is a
static bake classification; it does not add moving-platform velocity, rider
parenting, or dynamic rebaking.
A WalkOff link is created only when the destination is lower by more than Max Step and no more than Max Drop. It has no reverse upward link. The trigger marks permission to drop; it does not simulate falling or replace gameplay collision.
Ordinary enabled non-trigger Colliders are obstacles unless an enabled Walkable/Platform modifier classifies them otherwise. Ordinary obstacle boxes support Y rotation for the navigation bake. The NavMesh Surface and ordinary obstacles remain root, yaw-only authoring paths; explicit Walkable/Platform box sampling is the supported rotated-slope path.
Use Preview Navigation Bake to inspect node and directed-link counts, warnings, and errors before building. Its top-down graph uses node color to represent height. The preset menu offers:
| Preset | Cell Size / Height | Agent Radius / Height | Max Step / Slope / Drop |
|---|---|---|---|
| Balanced | 0.50 / 0.25 | 0.30 / 1.80 | 0.35 / 45 / 1.50 |
| Tight Indoor | 0.25 / 0.125 | 0.30 / 1.80 | 0.30 / 45 / 1.00 |
| Large Outdoor | 1.00 / 0.50 | 0.45 / 2.00 | 0.50 / 42 / 2.00 |
| Precision Platforming | 0.25 / 0.125 | 0.25 / 1.60 | 0.20 / 40 / 4.00 |
Apply Preset changes the bake parameters but not the surface Size or Offset. Preview the result again after any geometry or parameter change, then validate the packaged runtime path on its intended scene.
Navigation Agents
A NavMesh Agent must be on a root GameObject and reference one surface.
| Property | Meaning |
|---|---|
| Speed | Maximum movement speed |
| Acceleration | Rate used to approach maximum speed |
| Stopping Distance | Final waypoint tolerance |
| Rotate to Velocity | Turn Y rotation toward X/Z movement |
NavMeshAgent.SetDestination() finds a complete A* path on the assigned surface
and advances the GameObject through its three-dimensional waypoints. Requests above
32 path points fail rather than returning a misleading partial route.
Navigation writes the GameObject Transform. It does not add Character Controller collision response, dynamic obstacle avoidance, automatic replanning, or links between separate NavMesh Surface GameObjects.
The bake is not an arbitrary triangle navmesh or Recast-style runtime system. See the NavMesh and NavMeshAgent Lua API.
Limits
| Resource | Limit |
|---|---|
| Rooms | 24 |
| Portals | 48 |
| NavMesh Surfaces | 4 |
| NavMesh Agents | 16 |
| Baked nodes | 256 |
| Baked directed links | 1,024 |
| Path points per request | 32 |
Increase cell size, reduce sampled floors, or split the scene when the graph approaches node or link capacity.