> For the complete documentation index, see [llms.txt](https://mindcodeinteractive.gitbook.io/easy-build-system/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mindcodeinteractive.gitbook.io/easy-build-system/meta/troubleshooting.md). # Troubleshooting ### General #### NullReferenceException on BuildingManager.Instance Either there's no [Building Manager](/easy-build-system/reference/building-manager.md) in the scene, or you're accessing it before `Awake` completes.\ The manager sets its singleton in `Awake` scripts using it in `Awake` may run too early. *** #### Components can't find Easy Build System types If your scripts are in an assembly definition (.asmdef), add a reference to:\ `MindCodeInteractive.EasyBuildSystem.Runtime`.\ Without this reference, your assembly can't see the building system's types. *** #### Input conflicts with other systems Both the building system and other systems may read the same keys at the same time.\ With Legacy Input, check `BuildingController.Instance.ActiveMode` and skip input when active.\ With the New Input System, use separate Action Maps and toggle them on mode enter/exit. *** #### Two BuildingManagers exist at the same time This can happen with additive scene loading or `DontDestroyOnLoad`.\ The manager sets its singleton on `Awake`, so the last one wins.\ Ensure only one scene contains a [Building Manager](/easy-build-system/reference/building-manager.md), or add a check that destroys the duplicate. *** ### Placement #### The preview is always red (invalid) This is usually caused by [Building Conditions](/easy-build-system/reference/building-part/building-condition.md) on the active [Building Part](/easy-build-system/reference/building-part.md). [Collision Condition](/easy-build-system/reference/building-part/building-condition.md) overlapping ground, objects, or its own colliders.\ Enable **Show Logs** on each condition in the inspector and check the Console for the failure reason. If collision is the issue, shrink the bounds slightly and exclude the `Socket` layer from the check.\ If the [Common Condition](/easy-build-system/reference/building-part/building-condition.md) is failing, check its toggles (placement enabled, socket requirement). *** #### The preview is invisible The Renderer System didn't detect any renderers.\ Open the prefab, select the [Building Part](/easy-build-system/reference/building-part.md), and click **Build Variants From Renderers**.\ Make sure your 3D model is a child of the root GameObject and is correctly scaled. *** #### The preview doesn't follow the mouse The [Building View's](/easy-build-system/reference/building-controller/building-view.md) **Raycast Camera** field is empty.\ Select your player, find the active [Building View](/easy-build-system/reference/building-controller/building-view.md), and assign your main camera. *** #### The preview jitters between two positions Multiple sockets are competing for the snap.\ Reduce the **Socket Radius** on the competing sockets, or increase the distance between them.\ You can also reduce the **Snap Radius** on the [Building View](/easy-build-system/reference/building-controller/building-view.md). *** #### Parts place inside the ground Add a [Collision Condition](/easy-build-system/reference/building-collections.md) with bounds that detect your ground layer.\ You can also enable **Force Grounding** on the part's Placement System. *** #### Parts place floating in the air The raycast is hitting something above the ground (invisible collider, trigger volume).\ Check the **Raycast Layer** on the [Building View](/easy-build-system/reference/building-controller/building-view.md).\ Enable **Force Grounding** on the part's Placement System. *** #### Rotation doesn't work Check the Placement Building State: **Lock Rotation** might be enabled.\ Also check the part's Placement System: the **Rotation Step** might be (0, 0, 0).\ Set it to (0, 45, 0) for 8-way or (0, 90, 0) for 4-way rotation. *** ### Socket & Snapping #### Parts don't snap to anything Sockets must be on the **Socket** layer, matching the [Building Manager’s](/easy-build-system/reference/building-manager.md) Socket Layer.\ Also check that the socket has at least one Snapping Point with a Match Type that matches the part. *** #### The part snaps but to the wrong position The **Position Offset** and **Rotation Offset** on the snapping point are incorrect.\ These are in the socket's local space.\ Place both parts manually where they should connect, then calculate the offset. *** #### The part snaps but shows as invalid (red) The snap works but a condition fails at the snapped position.\ Usually the Collision Condition bounds overlap with the source part's colliders.\ Shrink the collision bounds or configure the collision to ignore parts on the same socket. *** #### Socket is detected but the wrong part tries to snap The snapping point's match criteria are too broad.\ If using Category matching, use a more specific category string.\ If using Reference matching, verify the correct prefab is assigned. *** ### Save & Load #### Parts don't reappear after restarting If Save Mode is **Manual**, the system never saves automatically.\ Call `SaveBuildings()` explicitly, or switch to **Automatic** mode. *** #### "Part not found for PrefabId" error on load The prefab no longer exists in the Building Part Registry, or its PrefabId changed.\ Never change PrefabIds after shipping. Disable parts instead of deleting them. *** #### Save file isn't found Check your **Save Provider**. PlayerPrefs stores in registry/list.\ **LocalFileData:** stores in `Application.dataPath` (wiped on rebuild).\ **LocalFilePersistent:** stores in `Application.persistentDataPath` (recommended for builds). *** #### Duplicate parts appear on load `LoadBuildings()` is being called more than once.\ Check your startup sequence and ensure load happens exactly once. *** #### Custom data isn't loading Make sure `SaveCallback` and `LoadCallback` are subscribed before the load happens.\ Subscribe in `OnEnable()` to be safe, since the save system loads in `BuildingManager.Start()`. *** ### Building Menu UI #### The menu doesn't open Check the **Toggle Key** (or Toggle Action) on the menu component.\ Verify that **InputEnabled** is true and the Canvas is active.\ In Mobile input mode, the menu doesn't respond to keyboard input: call `OpenMenu()` from a button. *** #### Clicking a slot does nothing The slot's **Action** field is empty. Each slot requires an action. *** #### Slot icons are blank The slot has no Icon set, and the linked part has no Thumbnail.\ Either assign an icon on the slot, or set a Thumbnail texture on the [Building Part](/easy-build-system/reference/building-part.md) prefab. *** #### Menu clicks also trigger building placement **Block When Pointer Over UI** is disabled on the [Building Input](/easy-build-system/reference/building-controller/building-input.md) component.\ Enable it so UI clicks don't pass through to the building system. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://mindcodeinteractive.gitbook.io/easy-build-system/meta/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.