Unity world building (level and environment artist)

Expert world building is structure first, then generated content that can be regenerated, then proof: the character fits every space, the camera fits every doorway, the player can reach every space and walk back, the edge of the world holds content, and the worst viewpoint holds the frame budget in a Player. An agent without a mouse does all of it through TerrainData, the ProBuilder API, PrefabUtility and scene APIs, then checks with raycasts, NavMesh paths, captures, a profiling tour and a Player probe. Target: Unity 6000.3.21f1, URP 17.3, ProBuilder 6.1.2, Splines 2.9.0, AI Navigation 2.0.14. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-unity-expert (channels, review loop, 6.3 traps). Import its toolkit; this skill adds scripts/ut_world.py, C# jobs in scripts/AgentKit/World/ and a runtime assembly in scripts/Runtime/World/.

Status (2026-09-24, after the blind-grade refactor): every procedure ran in Unity 6000.3.21f1 on this Mac except the plans marked [not run] in references/procedures.md: tests/code/unity-world-building/test_live_world.py (13 live tests), test_live_world_v2.py (12 live tests) and test_offline.py (7).

Stance (the expert delta)

1. Lock the structure before content. Terrain size and every texture resolution before sculpting (later changes rescale or resample, 6.3 Terrain manual); metrics from the character AND its camera before blockout, proven in a gym rebuilt whenever the controller changes (level design e-book, gym/zoo); the kit grid before placement (Christina Creates Games, 0o-QnNs-stc [00:07:35]). In code, persist the TerrainData asset before writing splat or the alphamaps are lost (observed).
2. Author non-destructively, regenerate deterministically. Alba renders movable features, levelers and roads to the heightmap and regenerates the world in ordered, skippable steps before play and in CI; the generated scene is checked in with git update-index --skip-worktree (Manesh Mistry, YOtDVv5-0A4 [00:06:10], [00:09:52], [00:10:05]). A PolyShape rebuilt from its footprint drops every later edit (ProBuilder manual; observed 12 faces back to 7): keep the recipe, not the edited mesh.
3. Raw procedural output needs a second layer. Noise needs erosion (Lague, eaXk97ujbPQ); WFC needs authored tiles (DV Gen, 20KHNA9jTsE [00:04:22]); roads need routing: a slope-aware A* route cut 2.6 m where straight knots cut a 9.1 m canyon (Alba [00:07:45]; observed).
4. Block out with one generic piece, then bulk replace; prefab every piece and every compound. One wall everywhere, then doors and windows by replacement (Christina [00:15:14]); a metric fix is one prefab edit (YsBniZ5ya7k [00:06:25]). In a script, record the instance override before replacing: ReplacePrefabAssetOfPrefabInstance kept 0 of 30 placements without RecordPrefabInstancePropertyModifications, 30 of 30 with it (observed; the grid audit stayed clean, a slot and perimeter audit caught it).
5. The graybox exit gate is mechanical. Doors from agent radius and camera boom, NavMesh over every whole floor with door leaves modified out of the bake and clutter that never splits a room, roofs marked Not Walkable, upper floors linked, one NavMesh Surface per area (Christina [00:17:12], [00:19:27]; YsBniZ5ya7k [00:15:24]); a quick bake for dark zones; landmarks and paths first, signs last (Adam Robinson-Yu, ZW8gWgpptI8 [00:18:37]).
6. Players test the edge first; guide with a ladder. On an island they swim out and around: put content and a way back on every stretch of coast, not walls ([00:16:54], [00:17:58]). Landmarks, breadcrumbs, paths that lead back, inclines toward the goal, signs last; false peaks need a reason. Here 32 of 36 coast bearings had nothing within 150 m (observed).
7. Stream only what does not fit, around a persistent core, and judge it in a Player. Alba kept its island resident with LOD and relevance systems ([00:12:43]). The core owns RenderSettings, lightmaps and fog; load by path; never hold allowSceneActivation = false in play (it froze a queued unload for a second, observed); sweep assets after unloads; show a merged proxy while a visible chunk is out. backgroundLoadingPriority and the Integrate marker only mean something in a built Player (6.3 Scripting API; Editor counters read 0 here).
8. Profile the worst viewpoint, compare statistics, fix on the device's terms. Teleport to anchors, turn 360 degrees, keep the worst heading (Alba [00:29:46]); compare about 200 frames per side (Profile Analyzer, [00:17:00]). On tile-based mobile GPUs opaque LOD foliage beats alpha-tested impostors (7.12 of 32.5 ms, [00:20:14]); Firewatch's distance alpha cutoff is a PC and console choice (Jane Ng, ZYnS3kKTcGg [00:20:29]). LOD Group trees ignore Terrain.treeDistance (60 m and 700 m gave identical frames, observed): the LOD Group is the lever.

Establish first

Platform and budget (default desktop 60 fps = 16.67 ms; mobile 30 fps: 65 % of the 33.3 ms frame = 21.7 ms, scenario-unity-expert); memory of the lowest device (decides whether to stream at all); world size and traversal speed; the character (radius, height, slope limit, step, jump distance) and its camera (pivot, shoulder offset, boom, pitch); art style and fog language; content source (authored, procedural, mixed) and who paints; whether the user's editor holds the project (ut_env.project_lock). Defaults: URP, 1 km terrain, heightmap 1025, 1 m graybox grid, 2.5 m kit grid, story 3 m, capsule 0.4 x 1.8 m, slope 45, step 0.3, jump 2.5 m [added].

Workflow

Each stage is one ut_world call; engine calls, arguments and recorded results are in references/procedures.md.

1. Spec. Metrics, resolutions, grids, budgets, anchors, memory budget. GATE: every later check has a number.
2. Terrain. build_island (resolutions first, fBm, erosion, levelers, A* road, rule splat, LOD trees, instanced details), raw_roundtrip for DCC heightmaps, set_terrain_settings for the per-tile settings the Toolbox cannot batch. GATE: 2^n+1, patch 16, distinct detail seeds, road grade <= 10 %, audit 0 errors in a fresh editor.
3. Gym, then graybox. build_gym(P, metrics) (gym_is_stale after any controller change), then build_village. GATE: the door size passes the NavMesh and its camera clip fraction is known; PathComplete into every building; UV2 everywhere; names carry sizes.
4. Kit. build_kit then kit_nav_gate. GATE: grid, story, yaw, slot and perimeter audit clean; door leaves ignored by the bake; no roof islands; upper floors linked.
5. Guidance. setup_views (bookmarks, anchors, sightlines, spawn), audit_guidance, fill_coast until the longest empty arc passes. GATE: every anchor sees a landmark or stands on the main path; every POI walks back; spawn dot >= 0.7.
6. Look. capture fog off (layout) and fog on (look), capture_pops at the detail, LOD and cull distances. Open every sheet; judge with references/critique.md. GATE: no blank, black, white or magenta frame; pop sizes recorded.
7. Stream (only if needed). scene_report first; then split_streaming, build_proxies, streaming_tests, stream_probe. GATE: PlayMode 5/5; Player Integrate marker within the priority budget; memory back to baseline after the sweep.
8. Tour. tour_profile, compare_runs before and after each change. GATE: budget_check pass per anchor; counts decide in the Editor, milliseconds on the device.

Numbers

Value	Relative to	Source
2^n+1 (513, 1025, 2049)	heightmap; 1025+ for erosion	6.3 Terrain manual
16	Detail Resolution Per Patch (more only for sparse far grass)	6.3 manual
4	terrain layers per splat map with height blend	smnLYvF40s4 [00:04:23]
2 / 4 / 10 / 50 ms	Integrate budget per frame, Low / BelowNormal / Normal / High, Player only	6.3 Scripting API
2.5 x 3 m, Y = 3 n	kit wall, story	0o-QnNs-stc [00:07:35]
1.0 m	narrowest door for a 0.4 m capsule (0.8 fails)	gym, observed
80 % / 27 %	camera boom (3.5 m, 20 degrees) blocked through a 1.4 x 2.4 m / 2 x 3 m door	gym, observed
40 pass, 45 fail	ramp degrees at slope limit 45, NavMesh and CharacterController agree	gym, observed
0.13 to 0.06 m	NavMesh height error on stairs without / with Build Height Mesh	gym, observed
0.5 to 1.13 of 2 ms	Player Integrate max per frame at Low (village chunk, 34 to 371 ms loads)	stream_probe, observed
7.12 of 32.5 ms	impostor foliage GPU cost, iPad Mini 4	YOtDVv5-0A4 frame [00:19:53]
~200 frames	per side of a before/after comparison	YOtDVv5-0A4 [00:17:00]
150 m, 300 m	POI radius, longest empty coast arc (defaults to tune)	[added]

Quality gates

• Measurable: envelope ok, zero compile errors; terrain audit 0 errors (desktop and mobile=True); blockout, kit slot and perimeter audits clean; kit NavMesh gate; gym table; guidance gate; NUnit EditMode 8/8 and PlayMode 5/5; Player probe verdict; budget_check per anchor; compare_runs p-values.
• Visual: fog-off, fog-on, pop and proxy sheets opened; ut_review flags none; before/after from the same bookmarks; detail reads as language: generic rocks and trees shape-only, narrative props detailed, no fourth rock if three suffice (Firewatch, ZYnS3kKTcGg [00:24:27], [00:25:50]).

Common mistakes

Mistake	What it looks like	Fix
CreateAsset(terrainData) after SetAlphamaps	terrain all first layer in a fresh editor	asset first, then layers
ReplacePrefabAssetOfPrefabInstance after an unrecorded move	replaced walls stacked at the house origin, holes; grid audit clean	RecordPrefabInstancePropertyModifications after placing; restore the transform; slot audit
two NavMesh Surfaces over one area	paths "complete" through walls on the stale surface	one surface per area; rebake overlaps
closed door leaves baked	rooms unreachable	NavMeshModifier.ignoreFromBuild on leaves
clutter placed without the agent radius	door open, room split: 25 % of a floor reachable (observed)	keep door zones clear; reject items that disconnect the floor; sample the whole floor
roofs and upper floors in the bake	unreachable islands	roof area Not Walkable; stairs or NavMeshLink
door sized from the capsule only	camera snaps in at every doorway	measure the boom in the gym; interior camera
editing a PolyShape again	extrusions gone	lock footprints; replay a recipe
tuning treeDistance for LOD trees	no change at all	tune the LOD Group, capture the cull
Healthy/Dry Color on instanced details	no color variation	vary color in the shader
Bake Light Probes For Trees (on by default) alone	no effect	tree renderers receive GI from Light Probes
holding activation to preload	unloads freeze	load immediately, gate only a loading screen
no Start scan in a streamer	a chunk opened in the Editor loads twice (1 vs 2 copies, observed)	scan loaded scenes in Start
streaming or memory judged in the Editor	counters 0, priority ignored	stream_probe in a development Player
new ProfilerRecorder(handle) for a marker	0 ms forever	add ProfilerRecorderOptions.StartImmediately (or StartNew); treat a never-sampled marker as no data
per-system GPU ms from FrameTimingManager	"terrain 2 ms" that is the whole frame	toggle the system and diff, or a GPU capture
judging layout through fog or top-down ortho	washed aerial; trees culled by LOD	fog-off aerial captures

Handoffs

• Receives assets from scenario-3d, scenario-textures, scenario-skyboxes and scenario-blender-expert; the character controller and camera rig from scenario-unity-gameplay and scenario-unity-animation (Cinemachine); input from scenario-unity-architecture.
• Delivers to scenario-unity-rendering-lighting: scenes with static flags, UV2, the core as lighting owner, one APV Baking Set with the core and every chunk, baked (and occlusion) with all scenes open [not run here], fog baseline, probe settings per tile; to scenario-unity-shaders: the Firewatch gradient-strip fog as a fullscreen pass spec, grass color variation in the detail shader; to scenario-unity-performance: tour CSV and JSON, compare_runs, the Player probe, the LOD finding, GPU Resident Drawer candidates among chunk props (Forward+, SRP Batcher, Mesh Renderers only, deltas section 5); to scenario-unity-mobile: audit(mobile=True), streaming priorities; to scenario-unity-gameplay: NavMesh surfaces, links, gym table, spawn points; to scenario-unity-pipeline-automation: Addressable scenes, build list, import rules as AssetPostprocessors.
• Packet: project, channel, scenes, the gates with numbers, all sheets, open issues.

Unity 6.3 notes

• Polybrush is deprecated and never worked on Terrain: scatter by raycast. ProBuilder 6.1.2: no window (Scene view tool context), PivotLocation.FirstVertex (the docs' "First Corner"), default material is a vertex-color Shader Graph.
• Terrain Tools 5.3.2 bundled; Splines 2.9.0; AI Navigation 2.0.14 (NavMesh Surface, Modifier, Link, Build Height Mesh); Build Profiles share EditorBuildSettings.scenes; Memory Profiler 1.1.12 and Profile Analyzer 1.4.0 are packages.
• FindObjectsByType needs a sort mode (obsolete in 6.4); 6.6 new projects enter Play mode without domain reload.

References

• references/procedures.md: 24 procedures with full calls, live test paths and recorded results.
• references/expert-notes.md: principles and judgment by expert, with source and timestamp.
• references/critique.md: rubric for terrain, gym, blockout, kit, guidance, atmosphere, streaming, performance.
• references/gui-paths.md: Terrain Toolbar, ProBuilder tool context, Splines, NavMesh, multi-scene, profiling windows.
• references/sources.md: every source with credentials, URLs, best timestamps, revision history.