Scene Structure

A consistent scene structure makes work faster and more enjoyable, improves collaboration, and makes onboarding painless. It also decides how many people can work on a level at the same time, which is why this page exists.

Multi-Scene Setup

A Unity scene is a single file, and .unity is on our lock list (see Version Control). One scene per level would mean one person per level. Unlike a kit, which usually has a single owner, a level is where the environment artist, the designer, lighting, and audio all converge, often in the same week.

So we split every level into additively loaded scenes, one per discipline. Each can be locked, edited, and committed independently.

Scene Layers

Scene Contains Owner
SC_[Level]_Base Scene set definition, load orchestration, level-wide settings Level owner
SC_[Level]_Environment Kit geometry, props, terrain, decals Environment artist
SC_[Level]_Gameplay Spawns, triggers, interactables, AI, navigation Designer
SC_[Level]_Lighting Lights, reflection probes, fog and post-process volumes Lighting artist
SC_[Level]_Audio Ambience emitters, reverb zones Audio
SC_[Level]_UI Level-specific UI UI

Plus SC_Systems, loaded persistently in every level, holding managers that survive level changes.

Small projects

For a jam or a small game, Base + Environment + Gameplay is enough. Add layers when a second person needs to work in one.

Ownership

Like kits, every scene layer has an owner: the person who knows it, maintains it, and confirms changes. The level owner (owner of _Base) is responsible for the level as a whole and for resolving disagreements between layers.

Rules

  • _Base is the active scene. New objects are created in the active scene, and lighting settings come from it. Always check which scene is active before building. Set it explicitly on load.
  • Cross-scene references do not serialize. Unity will not save a reference from an object in one scene to an object in another. Resolve at runtime through a registry, an event channel, or SceneManager lookups. If you find yourself wanting a direct reference, that's a sign the two objects belong in the same layer.
  • Don't move objects between layers casually. It breaks references and produces a conflicting commit in two files at once. If something is in the wrong layer, tell both owners first.
  • One layer, one lock. Working across layers means holding multiple locks. Keep it short, and commit as soon as you can.

Hierarchy Structure

Section Headers

Every scene is organised under section headers: empty transforms named ---UPPERCASE---, sitting at the origin.

SC_AbandonedTavern_Environment
├── ---ARCHITECTURE---
│   ├── Floors
│   ├── Walls
│   ├── Ceilings
│   └── Stairs
├── ---PROPS---
│   ├── Static
│   └── Interactive
├── ---NATURE---
└── ---DECALS---

SC_AbandonedTavern_Gameplay
├── ---SPAWNS---
├── ---TRIGGERS---
├── ---INTERACTABLES---
├── ---NAVIGATION---
└── ---CAMERAS---

Rules

  • Nothing loose at the scene root. Everything lives under a section header.
  • Section headers never move. They stay at position (0,0,0) with identity rotation and unit scale. Moving one moves everything beneath it, and that bug is nearly invisible in the inspector.
  • Keep static geometry shallow. Two or three levels under a section header is plenty. Deep hierarchies cost transform updates and hurt batching.
  • Mark static geometry as Static. Required for batching, occlusion culling, and navmesh baking.
  • Runtime-spawned objects get their own root container. Never parent pooled or spawned objects into a hand-authored section. It makes the hierarchy unreadable at play time and creates diffs that aren't real.

Scene Object Naming

Objects inside scenes follow their own convention. See Naming Conventions for asset file names.

objectPrefixes

Key Value
trigger TRG_
spawnPoint SPN_
waypoint WP_
camera CAM_
light LGT_
audio SND_
volume VOL_
marker MRK_
system SYS_
interactable INT_
navLink NAV_
decal DCL_
collisionBlocker COL_
effect VFX_
uiRoot UI_
probe PRB_

Prefix Type Example
(none) Prefab instance, keeps the prefab name P_Kit_Tavern_01_Wall_Interior_01
TRG_ Trigger volume TRG_Kitchen_Enter
SPN_ Spawn point SPN_Player_Start
WP_ Waypoint / patrol node WP_Guard_A_03
CAM_ Camera / virtual camera CAM_Cutscene_Intro
LGT_ Light LGT_Kitchen_Ceiling_01
SND_ Audio emitter SND_Ambience_Rain
VOL_ Post-process, reverb or fog volume VOL_PostFX_Interior
MRK_ Designer marker / reference point MRK_DoorPivot_Ref
SYS_ Manager / singleton SYS_GameState
INT_ Interactable INT_Kitchen_Drawer_01
NAV_ Nav mesh link NAV_Kitchen_Window_Jump
DCL_ Decal DCL_Blood_Splatter_01
COL_ Collision blocker COL_Stairs_Ramp
VFX_ Effect VFX_Effect_Fireplace_Smoke_01
UI_ UI root UI_Level_Hud
PRB_ Reflection or light probe PRB_Kitchen_Reflection

Rules

  • Never ship (1), (2), or GameObject. Unity's auto-suffix on duplication is the single biggest source of unreadable hierarchies. Duplicates get _01, _02.
  • Prefab instances keep their prefab name. If you need to distinguish two instances, add a location or role: P_..._Wall_Interior_01 (Kitchen North) is fine, but prefer grouping them under a descriptive parent instead.
  • Name things when you create them, not later. Later never comes, and by then someone else is reading your scene.

Scene File Naming

SC_[Level]_[Layer]
  • SC_AbandonedTavern_Environment
  • SC_AbandonedTavern_Gameplay
  • SC_Systems

Level names use PascalCase and match the kit name where a level is built from a single kit.

Tooling

  • Template scenes live in Assets/Bubbly Games/Templates, with section headers pre-created. Always start a new level from a template. Hand-building the structure is how it drifts.
  • Hierarchy icons. We use vHierarchy to colour and icon section headers. Install it before working on levels.
  • Scene structure rules are validated by the asset rules system (see Asset Rules (Generated)), so a scene missing its section headers or containing loose root objects is reported on import.