> 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/reference/building-controller/building-state.md).

# Building State

Each building mode has a dedicated state handling its logic.
\
Placement, Destruction, Adjustment, and Upgrade states handle preview and confirmation.

***

### How States Work

States encapsulate all the logic for a specific building mode.\
Each state has `EnterState`, `UpdateState`, and `ExitState` hooks.\
When the controller enters a mode, its state updates each frame until changed.

All states respond to `OnValidateAction`, `OnCancelAction`, and `OnRotateAction`.\
Validation checks conditions on the target part and distance constraints from the active view.\
If validation fails, the reason is published as an event and optionally logged.

***

### Built-in States

#### Placement State

Creates a preview of the selected part and moves it with the player's aim.\
Searches for compatible sockets and snaps the preview when a match is found.\
On validate, executes the `PlaceCommand`.

#### Destruction State

Highlights the part under the player's aim.\
On validate, executes the `DestroyCommand`.\
Optionally exits the mode after a successful destroy.

#### Adjustment State

Picks up a placed part and creates a preview for repositioning.\
The original part is hidden during adjustment.\
On validate, executes the `AdjustCommand` to finalize the new position.\
On cancel, the part returns to its original position.

#### Upgrade State

Previews a variant swap on the part under the player's aim.\
On validate, executes the `UpgradeCommand` to switch the renderer variant.\
Optionally exits the mode after a successful upgrade.

***

### State Options

**Cancel State After Validation**: When enabled, the mode automatically exits after a successful action. Useful for destruction and upgrade modes where the player typically performs one action at a time.

**Show Logs**: Logs condition failures and validation warnings to the Console.\
Useful for debugging why a placement is being rejected.

***

### Creating Custom States

Inherit from `BuildingState` and implement the required hooks:

```csharp
using MindCodeInteractive.EasyBuildSystem.Framework.Code.Runtime.Systems.Controllers.States;
using MindCodeInteractive.EasyBuildSystem.Framework.Code.Runtime.Systems.Controllers.States.Abstracts;

public class MyCustomState : BuildingState
{
    public override BuildingMode Mode => BuildingMode.Placement;

    public override void EnterState()
    {
        // Setup when entering this mode
    }

    public override void UpdateState()
    {
        // Runs every frame while this mode is active
    }

    public override void ExitState()
    {
        // Cleanup when leaving this mode
    }

    public override void OnValidateAction()
    {
        // Handle confirm input
        base.OnValidateAction();
    }

    public override void OnCancelAction(bool cancelMode = true)
    {
        // Handle cancel input
        base.OnCancelAction(cancelMode);
    }

    public override void OnRotateAction(int direction)
    {
        // Handle rotation input
    }
}
```

***

### Scripting Examples

Get the active state:

```csharp
BuildingState state = BuildingController.Instance.ActiveState;
BuildingMode mode = BuildingController.Instance.ActiveMode;
```

Get a specific state:

```csharp
BuildingState placementState = BuildingController.Instance.GetState(BuildingMode.Placement);
```

Listen for state events:

```csharp
EventPublisher.Subscribe<BuildingStateEvent.PlacedEventArgs>(e =>
{
    Debug.Log("Part placed: " + e.Part.Name);
});

EventPublisher.Subscribe<BuildingStateEvent.DestroyedEventArgs>(e =>
{
    Debug.Log("Part destroyed: " + e.Part.Name);
});

EventPublisher.Subscribe<BuildingStateEvent.AdjustedEventArgs>(e =>
{
    Debug.Log("Part adjusted: " + e.Part.Name);
});

EventPublisher.Subscribe<BuildingStateEvent.UpgradedEventArgs>(e =>
{
    Debug.Log("Part upgraded: " + e.Part.Name);
});

EventPublisher.Subscribe<BuildingStateEvent.ValidateAttemptEventArgs>(e =>
{
    Debug.Log("Validate attempt: " + e.Mode + " - " + e.Result.IsValid);
});

EventPublisher.Subscribe<BuildingStateEvent.CancelAttemptEventArgs>(e =>
{
    Debug.Log("Cancel attempt: " + e.Mode);
});
```


---

# 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/reference/building-controller/building-state.md?ask=<question>&goal=<endgoal>
```

`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.