{ "read_first": { "url": "/read-first/", "markdown": "/read-first.md", "instruction": "Read and follow these first on every prompt and interaction, before any other rule or section.", "rules": [ [ "NEVER-DESTRUCTIVE", "never do anything destructive, except where a platform store or legal requirement mandates it; then follow the mandated flow and still confirm with the user before executing." ], [ "NEVER-DELETE-OR-OVERWRITE", "never delete or overwrite projects, folders or files." ], [ "NEVER-DESTRUCTIVE-OUTSIDE-THE-PROJECT", "never take destructive actions outside the game project." ], [ "NEVER-IRREVERSIBLE", "never run irreversible operations." ], [ "ALWAYS-MOVE-ASIDE", "always back up or move aside instead of deleting." ], [ "WHEN-UNSURE-STOP-AND-ASK", "when you are unsure, stop and ask." ] ] }, "agent_setup_questionnaire": { "markdown": "/agent/setup-questionnaire.md", "audience": "agent", "rendered": false, "instruction": "Before creating a project: read-only scan, confirm findings, then ask only the missing questions interactively in the user's CLI or chat, one at a time; record answers in setup-answers.yaml; write nothing until confirmed." }, "name": "Unity Workflow Library", "description": "Free Unity game-dev workflow library.", "sections": [ { "name": "Project setup", "pages": [ { "title": "Start a project: scan, confirm, ask", "url": "/workflows/new-unity-project/", "markdown": "/workflows/new-unity-project.md", "summary": "Identify how you want to start: scan the machine read-only, confirm what was found, ask only what is missing, save it to setup-answers.yaml." }, { "title": "Customize the rules: locked vs your choice", "url": "/workflows/customizable-rules/", "markdown": "/workflows/customizable-rules.md", "summary": "Which rules are locked evidence and which are per-project preferences." } ] }, { "name": "Legal and licensing", "pages": [ { "title": "Legality & liability: IP, AI use, names, store rules", "url": "/workflows/legality-liability/", "markdown": "/workflows/legality-liability.md", "summary": "Pre-ship checklist for asset provenance, AI content rights, look-alikes, name clearance and store AI disclosure. Not legal advice." } ] }, { "name": "System design", "pages": [ { "title": "System design before code", "url": "/workflows/system-blueprint/", "markdown": "/workflows/system-blueprint.md", "summary": "Box every new system into a fixed shape (data, runtime, authoring tool) before writing code.", "footnotes": [ { "rule": "BASELINE-IS-CAPTURED-ONCE", "why": "A bone-scale applier re-captured its \"baseline\" on every apply, so scales compounded each time the effect was re-triggered.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "IDLE-PRESENTATION-KEEPS-THE-TURN-ACTOR", "why": "After an idle animation, the next seat lit up early because the idle path cleared the turn actor.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "Content pipelines and provenance", "pages": [ { "title": "Recording a content pipeline", "url": "/workflows/content-pipeline/", "markdown": "/workflows/content-pipeline.md", "summary": "Record the build procedure for a category of content so the next instance is made identically." }, { "title": "Content production audit", "url": "/workflows/content-production-audit/", "markdown": "/workflows/content-production-audit.md", "summary": "Census dead content, keep authoring surfaces the source of truth, ship features with UI." }, { "title": "Pitfalls: import pipelines & evidence", "url": "/workflows/pitfalls-data/", "markdown": "/workflows/pitfalls-data.md", "summary": "Absence needs two sources; gates that cannot fail.", "footnotes": [ { "rule": "A-NEGATIVE-NEEDS-TWO-SOURCES", "why": "\"no water in the data\" was repeated for days; the data had it, the scoped census and a failing parser did not.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "PARSE-FAILURE-LOOKS-LIKE-ABSENCE", "why": "A line-based manifest parser resolved 0 records after the file was pretty-printed; a deserializer swallowed errors by default.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "RESUMABLE-JOBS-WRITE-PROGRESS-FIRST", "why": "A killed job re-walked and duplicated records.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "ZERO-TRANSFORMS-ARE-PADDING", "why": "Geometry rendered floating at the world origin.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "VERIFY-TEXTURE-PACKING-FROM-PIXELS", "why": "Masks bound as albedo, emissive alpha mistaken for opacity.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "BAKED-BOUNDS-OFFSET-VS-PIVOT", "why": "Half the meshes landed offset by their baked bounds.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] }, { "title": "Keep a project pitfall file", "url": "/workflows/pitfalls/", "markdown": "/workflows/pitfalls.md", "summary": "Record symptoms, evidence, rules and verification with their source." } ] }, { "name": "Scene flow and lifecycle", "pages": [ { "title": "App & scene flow, lifecycle guards", "url": "/workflows/scene-flow/", "markdown": "/workflows/scene-flow.md", "summary": "Load matches, swap scenes and guard every flow: single-flight entry, guards cleared in finally, stubs that fail closed." }, { "title": "Runtime references & object lifecycle", "url": "/workflows/references-lifecycle/", "markdown": "/workflows/references-lifecycle.md", "summary": "How objects get references to each other, pooling, subscriptions, and how references die." }, { "title": "Pitfalls: gameplay logic & readiness gates", "url": "/workflows/pitfalls-gameplay/", "markdown": "/workflows/pitfalls-gameplay.md", "summary": "Silent readiness signals, retry flags, stable keys and shared placement paths.", "footnotes": [ { "rule": "SILENT-SIGNAL-COUNTS-AS-SATISFIED", "why": "A loading gate waited on a streamer signal that only existed in the Editor, so every player build sat at the gate until its timeout.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "FIRST-TIME-FLAG-IS-NOT-A-RETRY-FLAG", "why": "A streamer re-ran its one-time initialisation every frame after a transient failure because the same bool marked both \"never ran\" and \"try again\".", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "CATALOG-ORDER-IS-NOT-PRIORITY-ORDER", "why": "Content streamed in \"backwards\" (far props first, near ground last) because the loader walked the visual catalog in its authored sort order.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "TIMEOUT-ADVANCE-HIDES-THE-SCREEN", "why": "A matchmaking screen timed out to the next state, so neither QA nor tests could ever observe its failure branch.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "C# programming", "pages": [ { "title": "C# style & conventions", "url": "/workflows/csharp-style/", "markdown": "/workflows/csharp-style.md", "summary": "Naming, structure and language-feature rules for game code.", "footnotes": [ { "rule": "Qualify UnityEngine.Object (CS0104)", "why": "Agents kept writing bare `Object.` and burned a compile cycle on CS0104 each time, repeatedly across projects (one case: a map Confirm Drop action).", "source": "Seen repeatedly across active Unity projects, including a space sandbox game." }, { "rule": "No silent legacy fallback", "why": "Melee contact-frame damage regressed to instant for EVERY unit when a UnitSpawn rewrite dropped the PendingMeleeStrike add; the instant fallback hid it through multiple play-verified sessions while contact norms were tuned as dead code.", "source": "A survival RTS project, play-verified sessions." }, { "rule": "EDITOR-COMPILE-HIDES-PLAYER-BREAKS", "why": "A merge called \"8/8 assemblies compile, sweeps clean\" broke all player builds until a build lane found it.", "source": "An active Unity project; caught by a player build lane." }, { "rule": "CALLER-COUNT-MISSES-METHOD-GROUPS", "why": "Twice on one finding: a lane grepped `Initialize`, found the single call inside `RestartGame`, and reported \"exactly one caller\" - `GameManager.cs:122` subscribes it as `GlobalManager.OnPlayerTowerReady += Initialize`, a second entry point the pattern could not match. The wrong count turned a by-design Retry reset into a reported gameplay defect, and the head ruled a slice ahead of the queue for it before the Editor.log stack traces - `UI_UitkGameHud/<>c:` under `RestartGame` under `Initialize` - closed it in one read.", "source": "A tower-defense game in development." }, { "rule": "OUT-PARAM-ALIASING-DESTROYS-THE-INPUT", "why": "A server spawn gate called `TryGetStreamedSpawnPosition(collisionWorld, position, height, out position)`. The helper assigns `supportedPosition = default` before its raycast can fail, so on the deny path the hold branch created its temporary streaming observer at the ORIGIN instead of the spawn column. The chunk the hold waits for was therefore never requested, so no spawn away from the origin could ever resolve - every one ran out the 30 s reject. It compiled, 202 tests passed, and it stayed invisible until a play-verification read the reject log and found `float3(0f, 0f, 0f)` where a deliberately distinctive probe column should have been. The helper's other call sites each used a separate `out` variable; only the one that reused its input was wrong.", "source": "A space sandbox game server, found in play verification." } ] } ] }, { "name": "Assets and serialization", "pages": [ { "title": "Assets & serialization", "url": "/workflows/assets-serialization/", "markdown": "/workflows/assets-serialization.md", "summary": "Importers, YAML and serialized fields: keep data stable across refactors." } ] }, { "name": "Input and touch", "pages": [ { "title": "Input, touch & pointer gating", "url": "/workflows/input-touch/", "markdown": "/workflows/input-touch.md", "summary": "Input System wiring and touch traps that never reproduce with a mouse." } ] }, { "name": "Editor tooling", "pages": [ { "title": "Editor tooling", "url": "/workflows/editor-tooling/", "markdown": "/workflows/editor-tooling.md", "summary": "Inspectors, generators and authoring surfaces that never leak into a build." }, { "title": "Editor automation pitfalls", "url": "/workflows/editor-pitfalls/", "markdown": "/workflows/editor-pitfalls.md", "summary": "Editor ticking and serialized property traversal." } ] }, { "name": "Game AI and navigation", "pages": [ { "title": "Game AI: pathfinding & steering", "url": "/workflows/game-ai/", "markdown": "/workflows/game-ai.md", "summary": "Engine-agnostic flow fields, steering and crowd rules that survive blocked goals." } ] }, { "name": "Compilation and verification", "pages": [ { "title": "Agent compile check", "url": "/workflows/agent-compile-check/", "markdown": "/workflows/agent-compile-check.md", "summary": "The agent proves its code compiles before it claims a change is done." }, { "title": "Compilation & assembly membership", "url": "/workflows/compile-assemblies/", "markdown": "/workflows/compile-assemblies.md", "summary": "Why code will not compile, or was never compiled: asmdefs, defines, build profiles." } ] }, { "name": "Agent tools and live testing", "pages": [ { "title": "Unity MCP tooling options", "url": "/workflows/unity-mcp-options/", "markdown": "/workflows/unity-mcp-options.md", "summary": "The Unity MCP servers that exist, what each one does, how to pick one, and why the library's rules work with any of them." }, { "title": "Live play testing via Unity MCP", "url": "/workflows/live-play-testing-unity-mcp/", "markdown": "/workflows/live-play-testing-unity-mcp.md", "summary": "Drive the running Editor over MCP: ordered test recipes, crash recovery, offline compile." } ] }, { "name": "DOTS full stack", "pages": [ { "title": "DOTS full stack", "url": "/workflows/dots-stack/", "markdown": "/workflows/dots-stack.md", "summary": "Entities, Burst, Jobs, Collections, Mathematics, baking, graphics and physics." }, { "title": "ECS core mechanics", "url": "/workflows/ecs-core/", "markdown": "/workflows/ecs-core.md", "summary": "System shape, component granularity, structural changes, lookups, jobs and baking." }, { "title": "Gameplay simulation patterns (DOTS)", "url": "/workflows/gameplay-simulation/", "markdown": "/workflows/gameplay-simulation.md", "summary": "Crowd movement, sensing, target selection, spawn placement and match flow on ECS." }, { "title": "Latios, Kinemation & skinned animation", "url": "/workflows/latios-animation/", "markdown": "/workflows/latios-animation.md", "summary": "Skeletons, deform shaders and bone masks under Latios, and why units freeze in bind pose." }, { "title": "Pitfalls: DOTS, SubScenes & Burst", "url": "/workflows/pitfalls-dots/", "markdown": "/workflows/pitfalls-dots.md", "summary": "Baker isolation, structural changes, Burst cache.", "footnotes": [ { "rule": "SPAWNER-AUTHORING-OFF-THE-PREFAB", "why": "The spawner baked into every spawned copy, recursively spawning.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "COMPLETE-JOBS-BEFORE-OUT-OF-BAND-RENDER", "why": "Out-of-band renders raced ECS jobs writing render data.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "HOLD-NO-BUFFER-ACROSS-STRUCTURAL-CHANGE", "why": "`AddBuffer` then another `AddComponent`, then writing the first buffer threw ObjectDisposedException.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "NO-ENGINE-NAMESPACE-SEGMENTS", "why": "Inside a `...AI.Debug` namespace every `Debug.Log` resolved to the project namespace; `namespace X.Editor` stole `typeof(Editor)`.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "Networking", "pages": [ { "title": "Networking frameworks and approaches", "url": "/workflows/networking-frameworks/", "markdown": "/workflows/networking-frameworks.md", "summary": "Compare topology, authority, prediction and hosting using official documentation." }, { "title": "Choosing a netcode stack & Netcode for GameObjects", "url": "/workflows/networking-overview/", "markdown": "/workflows/networking-overview.md", "summary": "Pick the stack per project, verify connections, and NGO spawning and serialization rules." }, { "title": "Mirror networking", "url": "/workflows/mirror/", "markdown": "/workflows/mirror.md", "summary": "Logic/presentation split and authority rules for Mirror." }, { "title": "DOTS NetCode: ghosts & prediction", "url": "/workflows/dots-netcode/", "markdown": "/workflows/dots-netcode.md", "summary": "Ghosts, prediction, commands and RPCs in Netcode for Entities." }, { "title": "DOTS NetCode at scale", "url": "/workflows/dots-netcode-scale/", "markdown": "/workflows/dots-netcode-scale.md", "summary": "Relevancy, importance, bandwidth budgets and queues that stop a spike." }, { "title": "Pitfalls: networking", "url": "/workflows/pitfalls-netcode/", "markdown": "/workflows/pitfalls-netcode.md", "summary": "Preserved incident rules and verification for this topic.", "footnotes": [ { "rule": "CLIENTS-SEND-INTENT-ONLY", "why": "Projects that let clients report results had to be rewritten for authority.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "RELEVANCY-RADIUS-FITS-THE-FASTEST-MOVER", "why": "Aircraft crossed the radius in under a second and appeared next to players.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "SCALE-SENDS-BY-IMPORTANCE", "why": "Crowded scenes overflowed snapshot packets and near players updated as rarely as far ones.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "REWIND-EVERYTHING-YOU-CAN-HIT", "why": "Hits on players were rewound but hits on creatures were not, and rewind depth was capped below real latencies.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "ONE-SHARED-FRAME-NOT-PER-PLAYER", "why": "A server created a new local chart and physics world per wandering player, so nearby players lived in different frames.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "LATE-JOIN-REPLAY-IS-SCOPED-AND-PACED", "why": "Every client received every building piece in the world, and a late joiner waited tens of seconds behind a rate limit that also dropped over-budget requests.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "PREDICTION-STAYS-PENDING", "why": "UI showed predicted purchases/hits as final, then silently reverted.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "RECOMPILE-COPIED-NETCODE", "why": "Copied systems compiled but used retired lifecycle hooks and serialized wrong.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "NETWORKED-OBJECTS-OUTLIVE-MENU-SCENES-ONLY-IF-PLACED-RIGHT", "why": "A networked object spawned mid-menu vanished on the client at scene change.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "ONE-PREFAB-ONE-REGISTRATION-LIST", "why": "A bootstrap that added a second list containing an already-listed prefab made spawns fail.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "MULTIPLAYER-PLAYMODE-PACKAGE-CAN-BE-A-FACADE", "why": "A package version installed as an empty facade on a newer editor; virtual players never started.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "SERVER-AND-CLIENT-SHARE-ONE-PLACEMENT-PATH", "why": "The server placed vegetation in managed code while clients placed it in Burst jobs; float differences put trees (and their colliders) in different spots near tile edges.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "WORLD-EVENTS-ARE-SEEN-BY-EVERYONE", "why": "Only the acting client played a tree fall; other players kept drawing the tree and colliding with its trunk until a slow periodic push.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "UI design", "pages": [ { "title": "UI design: what a screen should look and read like", "url": "/workflows/ui-design/", "markdown": "/workflows/ui-design.md", "summary": "Hierarchy, contrast, copy, motion, and the rule that text never resizes its shell." }, { "title": "Pitfalls: UI screens & modals", "url": "/workflows/pitfalls-ui/", "markdown": "/workflows/pitfalls-ui.md", "summary": "Late-built widgets, hidden screens that still take taps, modal stacks.", "footnotes": [ { "rule": "BIND-AFTER-BUILD", "why": "Buttons built after `Bind` rendered fine and did nothing; the layout audit called the screen clean.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "AUDIT-THE-PANEL-YOU-SHIP", "why": "`FindAnyObjectByType` returned an empty panel and the audit reported it clean.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "SETTLE-ON-A-SIGNAL-NOT-A-FRAME-COUNT", "why": "A stress tool waited 4 editor frames and measured the prior step's geometry.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "HIDDEN-SCREENS-STILL-PICK", "why": "Players could not tap a text field because an inactive screen layered above still received picks.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "LATER-INIT-CAN-UNDO-A-SETTING", "why": "Portrait lock set in Player Settings and by the UI root was undone by a boot object's `Awake` that ran in a different order.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "MODAL-ROUTER-MUST-STACK", "why": "Pushing a connection gate over an open dialog discarded the dialog; closing the gate left nothing.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "CLAMP-TRUNCATES-A-TRANSITION", "why": "A height transition snapped in one frame while other properties animated, because a clamp held the value at its bound until the last frame.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "AUDIT-AT-THE-SHIPPING-PANEL-SIZE", "why": "A layout walk audited at a different reference height than the phone panel, so overflow on device never showed.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "OVERLAY-UI-IS-NOT-IN-CAMERA-CAPTURES", "why": "Verification screenshots taken from a camera showed no UI at all and were misread as a broken screen.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "WINDOWS-ONLY-EDITOR-TYPES-BREAK-OTHER-HOSTS", "why": "An editor helper referencing a Windows-only API compiled on Windows and failed on the Mac build host, blocking the iOS build.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "PICKER-CARRIES-THE-ACTION-AND-CLOSES-PER-CHOICE", "why": "A game froze at an opening action because the chosen target arrived without its action and the picker stayed open for a second prompt.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "UI Toolkit", "pages": [ { "title": "HTML/CSS mock to UI Toolkit", "url": "/workflows/html-css-to-ui-toolkit/", "markdown": "/workflows/html-css-to-ui-toolkit.md", "summary": "Port a designed web mock to UXML/USS faithfully and ship it." }, { "title": "USS/UXML: differences from CSS", "url": "/workflows/uss-uxml/", "markdown": "/workflows/uss-uxml.md", "summary": "The language delta between USS/UXML and the CSS a browser taught you." }, { "title": "UI Toolkit runtime behaviour", "url": "/workflows/ui-toolkit-runtime/", "markdown": "/workflows/ui-toolkit-runtime.md", "summary": "Layout, picking, events, style precedence, atlas cost and the pre-ship sweep." } ] }, { "name": "uGUI", "pages": [ { "title": "CSS mock to uGUI", "url": "/workflows/css-to-ugui/", "markdown": "/workflows/css-to-ugui.md", "summary": "Rebuild a CSS layout in Canvas/uGUI with correct anchors, layout groups and sorting." } ] }, { "name": "Responsive UI and orientation", "pages": [ { "title": "UI across orientations", "url": "/workflows/ui-orientation/", "markdown": "/workflows/ui-orientation.md", "summary": "One UI tree that works in portrait and landscape." } ] }, { "name": "Art and 3D asset production", "pages": [ { "title": "AI 3D model generation", "url": "/workflows/ai-3d-model-generation/", "markdown": "/workflows/ai-3d-model-generation.md", "summary": "Generate game 3D assets from images with measured proportions." }, { "title": "AI mesh cleanup", "url": "/workflows/ai-mesh-cleanup/", "markdown": "/workflows/ai-mesh-cleanup.md", "summary": "Repair, reduce and re-UV generated meshes before import." }, { "title": "Blender conventions & driving Blender from an agent", "url": "/workflows/blender/", "markdown": "/workflows/blender.md", "summary": "Export conventions for Unity, plus MCP, bpy scripts and headless runs." } ] }, { "name": "Animation", "pages": [ { "title": "Animation (Mecanim)", "url": "/workflows/animation/", "markdown": "/workflows/animation.md", "summary": "Clip timing, Write Defaults, bindings that die silently, IK and rigs." }, { "title": "Pitfalls: animation & rigs", "url": "/workflows/pitfalls-animation/", "markdown": "/workflows/pitfalls-animation.md", "summary": "One driver per Animator, culled poses, masks.", "footnotes": [ { "rule": "ONE-LOCOMOTION-DRIVER", "why": "Creature prefabs ran an old driver in LateUpdate and a new one in Update; the later write won, so tuning the new driver changed nothing.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "REGENERATE-CONTROLLERS-IN-PLACE", "why": "A generator deleted and recreated controllers; prefabs lost their controller.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "CULLED-ANIMATORS-DO-NOT-POSE", "why": "Verification of animation from a script saw no bone motion for creatures outside the view.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "VERIFY-MOTION-NOT-PARAMETERS", "why": "A handoff passed because layer weights and parameters changed while the rig stood frozen.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "DISCARDED-ROOT-MOTION-SWAYS", "why": "Walking characters swayed side to side at stride frequency.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "ANIM-SPEED-FROM-OBSERVED-VELOCITY", "why": "Interpolated units kept running after the server stopped them (or slid before the anim started).", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "REPLICATE-CAUSES-NOT-EFFECTS", "why": "Bandwidth and jitter from replicating presentation values that each client can derive.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "ONE-SHOTS-ARE-EDGE-TRIGGERS", "why": "Units spawned mid-fight played a false attack, and triggers left set looped attacks forever.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "HUMANOID-MASKS-ON-OPTIMIZED-SKELETONS-ARE-EMPTY", "why": "Masked layers did nothing / meshes vanished.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "NO-REBIND-ON-MODULAR-RIGS", "why": "Modular arms and weapons detached/deformed after a rebind.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "THROTTLE-SKINNED-SPAWNS", "why": "A wave spawning dozens of skinned units in one frame caused a GPU timeout/device loss.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "PREVIEW-GRAPH-MUST-STAY-ALIVE", "why": "Editor stills captured a T-pose because the preview graph was disposed before capture (DontSave previews also die on recompile).", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "IMPORT-SCALE-LEAKS-INTO-THE-AVATAR", "why": "After fixing a model's import scale, the humanoid description still stored inch-scale offsets; animations played distorted.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "SKIN-HAT-GEOMETRY-TO-THE-HEAD", "why": "Arm animation squashed a wide hat.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "Audio", "pages": [ { "title": "Audio", "url": "/workflows/audio/", "markdown": "/workflows/audio.md", "summary": "Loudness, voice pools, mixers, 3D settings and clip imports." } ] }, { "name": "Rendering", "pages": [ { "title": "Rendering & URP", "url": "/workflows/rendering-urp/", "markdown": "/workflows/rendering-urp.md", "summary": "URP, shaders and materials that fail silently, and the look pipeline." }, { "title": "Pitfalls: rendering & captures", "url": "/workflows/pitfalls-rendering/", "markdown": "/workflows/pitfalls-rendering.md", "summary": "Zeroed shader globals, motion vectors, capture cameras.", "footnotes": [ { "rule": "SHADER-GLOBALS-DEFAULT-TO-ZERO", "why": "A tint global meant to default to white rendered everything black until a system pushed it.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "MANUAL-DRAWS-NEED-PREVIOUS-MATRICES", "why": "An animated falling object smeared/ghosted under TAA/upscalers.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "INCREMENTAL-UPDATES-FOR-INSTANCED-SETS", "why": "Every harvest or tile arrival rebuilt and re-uploaded a whole species' instance buffer, costing frames and resetting motion vectors.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "PIPELINE-SHADERS-ARE-NOT-ASMDEF-GATED", "why": "HDRP-only shaders in a shared package broke/slowed a URP player build.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "OVERLAY-SHADERS-MUST-BE-REFERENCED", "why": "Debug overlays rendered pink/nothing in a player.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "NO-CAMERA-PER-SHOT", "why": "An HDRP capture loop allocated per-camera history buffers each shot and exhausted memory.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "WRONG-SCENE-WRONG-DIAGNOSIS", "why": "An orange wash investigated as a map bug came from a different scene's warm lighting/volume.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "CAMERA-FAR-CLIP-FITS-THE-BACKDROP", "why": "A large backdrop sphere near the far plane looked like fog cutting off mid-screen.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "CPU-TIMING-OF-RENDER-IS-NOT-GPU-COST", "why": "A benchmark \"proved\" a million-instance path fast.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "Visual effects", "pages": [ { "title": "VFX", "url": "/workflows/vfx/", "markdown": "/workflows/vfx.md", "summary": "General VFX rules for any Unity project: layered effects, particles, shaders, warm-up, cost and accessibility.", "ads": [ { "name": "All In 1 Vfx Toolkit", "vendor": "Seaside Studios", "url": "https://assetstore.unity.com/packages/vfx/all-in-1-vfx-toolkit-206665", "helps": "A material-based VFX shader toolkit for layered effects (additive glows, scrolling and eroding textures, dissolve with a burn edge). Useful for building the layered recipe on this page.", "paid": true, "label": "PAID AD" }, { "name": "Advanced Dissolve", "vendor": "Amazing Assets", "url": "https://assetstore.unity.com/packages/vfx/shaders/advanced-dissolve-111598", "helps": "A dissolve shader package with configurable edges and masks. Useful for erosion and dissolve edges on characters, props and explosions when you do not want to build the dissolve graph yourself.", "paid": true, "label": "PAID AD" } ] }, { "title": "VFX with AllIn1", "url": "/workflows/vfx-allin1/", "markdown": "/workflows/vfx-allin1.md", "summary": "Build stylized VFX with the AllIn1 toolkit (paid asset)." } ] }, { "name": "Performance and memory", "pages": [ { "title": "Performance & memory", "url": "/workflows/perf-memory/", "markdown": "/workflows/perf-memory.md", "summary": "Per-frame cost, allocation, logging and silent-zero configs.", "footnotes": [ { "rule": "BUDGETING-SPREADS-COST-DOES-NOT-REMOVE-IT", "why": "Capping convex collider builds per scan turned a one-frame hitch into seconds of sustained low FPS with the same total cost.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] }, { "title": "Profiling pitfalls", "url": "/workflows/profiling-pitfalls/", "markdown": "/workflows/profiling-pitfalls.md", "summary": "Capture windows and measuring player work." } ] }, { "name": "Shipping", "pages": [ { "title": "Platform build pipeline", "url": "/workflows/platform-build/", "markdown": "/workflows/platform-build.md", "summary": "Android/iOS/IL2CPP, artefacts, build modes and device testing." }, { "title": "Android vendor SDK integration", "url": "/workflows/android-vendor-sdk/", "markdown": "/workflows/android-vendor-sdk.md", "summary": "Gradle templates, AGP, native lib collisions and SDK ports." }, { "title": "Pitfalls: builds and shipping", "url": "/workflows/pitfalls-build/", "markdown": "/workflows/pitfalls-build.md", "summary": "Preserved incident rules and verification for this topic.", "footnotes": [ { "rule": "EXECUTEMETHOD-NEEDS-A-CLEAN-COMPILE", "why": "Build scripts \"succeeded\" without building; an IDE integration package also crashed batchmode.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "SPACES-IN-PATHS-BREAK-SHELL-SWEEPS", "why": "A mechanical check passed because it scanned zero files.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "RELEASE-PIPELINES-PRUNE-THEIR-OUTPUT", "why": "IOS export folders, archives and packages filled a build machine.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "DEVELOPMENT-PLAYERS-ARE-NOT-FOR-SHARING", "why": "Patches several times larger than the change, and builds shared with testers advertised the developer's LAN address.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "CHECK-AND-ACTION-ARE-SEPARATE-COMMANDS", "why": "The guard printed \"busy\" after the action on the next line had already started.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "PIPELINE-EXIT-CODES-COME-FROM-THE-LAST-STAGE", "why": "A repository integrity check piped through `tail` read as clean while the check had failed.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] }, { "name": "Live services", "pages": [ { "title": "Unity Gaming Services ops", "url": "/workflows/ugs-ops/", "markdown": "/workflows/ugs-ops.md", "summary": "Auth, Cloud Code, Cloud Save, Lobby/Relay and environments in production." }, { "title": "PlayFab service boundaries", "url": "/workflows/playfab/", "markdown": "/workflows/playfab.md", "summary": "Provider scope, identity boundaries and integration verification." }, { "title": "Firebase service boundaries", "url": "/workflows/firebase/", "markdown": "/workflows/firebase.md", "summary": "Provider scope, identity boundaries and integration verification." }, { "title": "Epic Online Services service boundaries", "url": "/workflows/epic-online-services/", "markdown": "/workflows/epic-online-services.md", "summary": "Provider scope, identity boundaries and integration verification." }, { "title": "Nakama service boundaries", "url": "/workflows/nakama/", "markdown": "/workflows/nakama.md", "summary": "Provider scope, identity boundaries and integration verification." }, { "title": "Steamworks service boundaries", "url": "/workflows/steamworks/", "markdown": "/workflows/steamworks.md", "summary": "Provider scope, identity boundaries and integration verification." } ] }, { "name": "Save data and persistence", "pages": [ { "title": "Save data: durability and authority", "url": "/workflows/persistence-pitfalls/", "markdown": "/workflows/persistence-pitfalls.md", "summary": "Transactions, restore gates, revisions and restart verification.", "footnotes": [ { "rule": "STORE-ISSUES-REVISIONS", "why": "A side counter diverged from the store after restart and accepted stale writes.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "SMOKE-TEST-ACROSS-A-RESTART", "why": "Single-session round-trips passed while restart-only faults (unflushed writes, cache-only state) shipped.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "COMMIT-THEN-MARK-CLEAN", "why": "A failed write left records marked clean and never retried.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "NO-WHOLE-TABLE-REPLACE-FROM-PARTIAL-DATA", "why": "A partial snapshot wiped rows it did not contain.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "DB-OPEN-FAILURE-IS-FATAL", "why": "A locked database started a fresh empty world that then overwrote saves.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "RESTORE-BEFORE-CAPTURE", "why": "An autosave right after a failed load persisted the empty world; a recreated server world skipped restore because the gate was still set.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "SNAPSHOT-BEFORE-DESPAWN", "why": "Last-session progress was lost because the player object was destroyed first.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "ONE-COMMAND-ID-PER-DECISION", "why": "Retries double-applied, and transient faults were recorded as permanent rejections.", "source": "Pitfall log of a shipped or active Unity project, generalized." }, { "rule": "STABLE-KEYS-OUTLIVE-PLACEMENT-ALGORITHMS", "why": "A planned switch of the scatter sequence (e.g. to a low-discrepancy sequence) would have renumbered every placed node, orphaning harvested/drained ledgers and persisted keys.", "source": "Pitfall log of a shipped or active Unity project, generalized." } ] } ] } ], "tiers": [ { "tier": 1, "name": "Start", "summary": "Identify how you want to start, before the project is even open.", "sections": [ "Project setup" ] }, { "tier": 2, "name": "Build the game", "summary": "Everything you need to make the whole game.", "sections": [ "Legal and licensing", "System design", "Content pipelines and provenance", "Scene flow and lifecycle", "C# programming", "Assets and serialization", "Input and touch", "Editor tooling", "Game AI and navigation", "Compilation and verification", "Agent tools and live testing", "DOTS full stack", "Networking", "UI design", "UI Toolkit", "uGUI", "Responsive UI and orientation", "Art and 3D asset production", "Animation", "Audio", "Rendering", "Visual effects", "Performance and memory", "Save data and persistence" ] }, { "tier": 3, "name": "Optional: ship & services", "summary": "Platform builds, stores and live services. You can make the whole game without anything here.", "sections": [ "Shipping", "Live services" ] } ], "principle": "You can make the whole game without anything in Tier 3.", "about": { "url": "/about/", "markdown": "/about.md" }, "site_url": "https://unityworkflowlibrary.dev", "license": { "name": "MIT", "url": "/LICENSE", "note": "All content on this site is provided under the MIT License (/LICENSE); anything you create using it is yours." }, "topics": [ { "id": "start", "title": "Project setup", "summary": "Workflows and evidence for project setup.", "url": "/topics/start/", "sections": [ "Project setup" ] }, { "id": "legal", "title": "Legal and licensing", "summary": "Workflows and evidence for legal and licensing.", "url": "/topics/legal/", "sections": [ "Legal and licensing" ] }, { "id": "system-design", "title": "System design", "summary": "Workflows and evidence for system design.", "url": "/topics/system-design/", "sections": [ "System design" ] }, { "id": "content-pipelines", "title": "Content pipelines and provenance", "summary": "Workflows and evidence for content pipelines and provenance.", "url": "/topics/content-pipelines/", "sections": [ "Content pipelines and provenance" ] }, { "id": "scene-flow", "title": "Scene flow and lifecycle", "summary": "Workflows and evidence for scene flow and lifecycle.", "url": "/topics/scene-flow/", "sections": [ "Scene flow and lifecycle" ] }, { "id": "code", "title": "C# programming", "summary": "Workflows and evidence for c# programming.", "url": "/topics/code/", "sections": [ "C# programming" ] }, { "id": "assets", "title": "Assets and serialization", "summary": "Workflows and evidence for assets and serialization.", "url": "/topics/assets/", "sections": [ "Assets and serialization" ] }, { "id": "input", "title": "Input and touch", "summary": "Workflows and evidence for input and touch.", "url": "/topics/input/", "sections": [ "Input and touch" ] }, { "id": "editor", "title": "Editor tooling", "summary": "Workflows and evidence for editor tooling.", "url": "/topics/editor/", "sections": [ "Editor tooling" ] }, { "id": "game-ai", "title": "Game AI and navigation", "summary": "Workflows and evidence for game ai and navigation.", "url": "/topics/game-ai/", "sections": [ "Game AI and navigation" ] }, { "id": "verify", "title": "Compilation and verification", "summary": "Workflows and evidence for compilation and verification.", "url": "/topics/verify/", "sections": [ "Compilation and verification" ] }, { "id": "agent-tools", "title": "Agent tools and live testing", "summary": "Workflows and evidence for agent tools and live testing.", "url": "/topics/agent-tools/", "sections": [ "Agent tools and live testing" ] }, { "id": "dots", "title": "DOTS full stack", "summary": "Workflows and evidence for dots full stack.", "url": "/topics/dots/", "sections": [ "DOTS full stack" ] }, { "id": "netcode", "title": "Networking", "summary": "Workflows and evidence for networking.", "url": "/topics/netcode/", "sections": [ "Networking" ] }, { "id": "ui", "title": "UI design", "summary": "Workflows and evidence for ui design.", "url": "/topics/ui/", "sections": [ "UI design" ] }, { "id": "ui-toolkit", "title": "UI Toolkit", "summary": "Workflows and evidence for ui toolkit.", "url": "/topics/ui-toolkit/", "sections": [ "UI Toolkit" ] }, { "id": "ugui", "title": "uGUI", "summary": "Workflows and evidence for ugui.", "url": "/topics/ugui/", "sections": [ "uGUI" ] }, { "id": "responsive-ui", "title": "Responsive UI and orientation", "summary": "Workflows and evidence for responsive ui and orientation.", "url": "/topics/responsive-ui/", "sections": [ "Responsive UI and orientation" ] }, { "id": "art", "title": "Art and 3D asset production", "summary": "Workflows and evidence for art and 3d asset production.", "url": "/topics/art/", "sections": [ "Art and 3D asset production" ] }, { "id": "animation", "title": "Animation", "summary": "Workflows and evidence for animation.", "url": "/topics/animation/", "sections": [ "Animation" ] }, { "id": "audio", "title": "Audio", "summary": "Workflows and evidence for audio.", "url": "/topics/audio/", "sections": [ "Audio" ] }, { "id": "rendering", "title": "Rendering", "summary": "Workflows and evidence for rendering.", "url": "/topics/rendering/", "sections": [ "Rendering" ] }, { "id": "vfx", "title": "Visual effects", "summary": "Workflows and evidence for visual effects.", "url": "/topics/vfx/", "sections": [ "Visual effects" ] }, { "id": "performance", "title": "Performance and memory", "summary": "Workflows and evidence for performance and memory.", "url": "/topics/performance/", "sections": [ "Performance and memory" ] }, { "id": "ship", "title": "Shipping", "summary": "Workflows and evidence for shipping.", "url": "/topics/ship/", "sections": [ "Shipping" ] }, { "id": "live-services", "title": "Live services", "summary": "Workflows and evidence for live services.", "url": "/topics/live-services/", "sections": [ "Live services" ] }, { "id": "save-data", "title": "Save data and persistence", "summary": "Workflows and evidence for save data and persistence.", "url": "/topics/save-data/", "sections": [ "Save data and persistence" ] } ] }