# API

**Assembly:** `Spark.UI`

The UI plugin does not expose a central interface. Instead, it provides base classes and utility components for building game UI.

## GamePanel

Abstract MonoBehaviour base class for all UI panels. Handles open/close state, visibility, and cross-panel coordination.

### Fields

| Field                | Type        | Description                                  |
| -------------------- | ----------- | -------------------------------------------- |
| `panelCanvasGroup`   | CanvasGroup | Controls alpha, interactable, blocksRaycasts |
| `onPanelOpenedEvent` | UnityEvent  | Invoked when panel opens                     |
| `onPanelClosedEvent` | UnityEvent  | Invoked when panel closes                    |

### Methods

```csharp
virtual void OpenPanel()
// Shows the panel. Sets CanvasGroup alpha to 1, interactable and
// blocksRaycasts to true. Checks the "DEAD" rule and blocks opening
// if the player is dead. Sets the "UI_OPENED" rule to true.

virtual void ClosePanel()
// Hides the panel. Sets CanvasGroup alpha to 0, interactable and
// blocksRaycasts to false. Updates "UI_OPENED" rule.

bool IsOpen { get; }
// Returns current open state.

virtual void OnPanelOpened()
// Override hook called after the panel opens.

virtual void OnPanelClosed()
// Override hook called after the panel closes.

static int GetOpenPanelCount()
// Returns how many panels are currently open.

static bool AnyPanelOpen()
// True if at least one panel is open.

static bool AnyOtherPanelOpen(GamePanel excludePanel)
// True if any panel besides the given one is open.

static void CloseAllOtherPanels(GamePanel excludePanel)
// Closes all panels except the specified one.
```

GamePanel implements `ISparkEventHandler<CloseAllUIPanelsEvent>` and closes itself when the event is published.

## SparkUISpawner

MonoBehaviour that dynamically instantiates UI prefabs at runtime.

### Fields

| Field                | Type          | Description                                           |
| -------------------- | ------------- | ----------------------------------------------------- |
| `uiPrefab`           | RectTransform | Prefab to spawn                                       |
| `instantiateAsChild` | bool          | If true, spawns as child; if false, spawns as sibling |

### Methods

```csharp
RectTransform Spawn()
// Creates an instance of the prefab.
// As child: stretches to fill parent (full screen).
// As sibling: copies RectTransform values, then destroys the spawner.

void DestroySpawned()
// Destroys the spawned instance.

void SetPrefab(RectTransform prefab)
RectTransform GetPrefab()

RectTransform SpawnedInstance { get; }
bool IsSpawned { get; }
```

## CursorManager

MonoBehaviour that dynamically switches the cursor based on what the player is hovering over.

### Fields

| Field                | Type                    | Description            |
| -------------------- | ----------------------- | ---------------------- |
| `defaultCursor`      | CursorOptionData        | Fallback cursor        |
| `availableCursors`   | List\<CursorOptionData> | All registered cursors |
| `maxRaycastDistance` | float                   | How far to raycast     |
| `raycastLayerMask`   | LayerMask               | Which layers to check  |

### Methods

```csharp
CursorOptionData GetCursorById(string cursorId)
void RegisterCursorOption(CursorOptionData cursorOption)
void UnregisterCursorOption(string cursorId)
CursorOptionData CheckForCursorProvider()
// Raycasts and checks for ICursorProvider on hit objects.
```

Uses priority-based cursor selection. Objects implementing `ICursorProvider` can provide their own cursor when hovered.

## ICursorProvider

Interface for objects that provide a custom cursor on hover.

```csharp
public interface ICursorProvider
{
    bool ShouldProvideCursor(out CursorOptionData cursorOption);
}
```

## CursorOptionData

ScriptableObject defining a cursor appearance.

| Field           | Type      | Description                      |
| --------------- | --------- | -------------------------------- |
| `cursorId`      | string    | Unique identifier                |
| `cursorTexture` | Texture2D | Cursor image                     |
| `hotspot`       | Vector2   | Click point offset               |
| `priority`      | int       | Selection priority (higher wins) |

## GenericTooltipData

Simple data container for tooltip content.

| Field         | Type   | Description          |
| ------------- | ------ | -------------------- |
| `icon`        | Sprite | Optional icon        |
| `title`       | string | Optional title       |
| `description` | string | Optional description |

**Properties:** `HasIcon`, `HasTitle`, `HasDescription`

## Events

### CloseAllUIPanelsEvent

Published to close all open panels at once.

| Property        | Type       | Description             |
| --------------- | ---------- | ----------------------- |
| `RequestSource` | GameObject | Who requested the close |

EventType: `"CloseAllUIPanels"`

## Usage

### Creating a Custom Panel

```csharp
public class InventoryPanel : GamePanel
{
    [SerializeField] private Transform itemContainer;

    protected override void OnPanelOpened()
    {
        RefreshItems();
    }

    protected override void OnPanelClosed()
    {
        ClearItems();
    }

    private void RefreshItems() { /* populate UI */ }
    private void ClearItems() { /* clear UI */ }
}
```

### Implementing ICursorProvider

```csharp
public class ChestObject : MonoBehaviour, ICursorProvider
{
    [SerializeField] private CursorOptionData lootCursor;

    public bool ShouldProvideCursor(out CursorOptionData cursorOption)
    {
        cursorOption = lootCursor;
        return true; // Always show loot cursor when hovering
    }
}
```

### Closing All Panels

```csharp
SparkEventBus.Publish(new CloseAllUIPanelsEvent
{
    RequestSource = gameObject
});
```


---

# Agent Instructions: 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:

```
GET https://docs.sparkframework.dev/documentation/developer-guide/core-systems/ui-system/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.