# API

**Assembly:** `Spark.ScreenTexts` **Interface:** `IScreenTextsPlugin` **Implementation:** `ScreenTextsPlugin`

## Interface

```csharp
public interface IScreenTextsPlugin
{
    void DisplayScreenText(string eventName, string text, Vector3 worldPosition);
    void DisplayScreenText(string eventName, string text);
    List<ScreenTextEntry> GetAllScreenTextEntries();
    ScreenTextEntry GetScreenTextEntryByEventName(string eventName);
}
```

## Methods

### DisplayScreenText (world position)

```csharp
void DisplayScreenText(string eventName, string text, Vector3 worldPosition)
```

Displays floating text at a world position, converted to screen space. Used for damage numbers, XP gains, and similar feedback.

### DisplayScreenText (screen position)

```csharp
void DisplayScreenText(string eventName, string text)
```

Displays text using the entry's configured screen position and alignment.

### GetAllScreenTextEntries

```csharp
List<ScreenTextEntry> GetAllScreenTextEntries()
```

Returns all screen text entries.

### GetScreenTextEntryByEventName

```csharp
ScreenTextEntry GetScreenTextEntryByEventName(string eventName)
```

Returns the entry configured for a specific event name.

## ScreenTextEntry

Extends `SparkDatabaseEntry`. Configures how floating text appears.

### Event Configuration

| Field              | Type   | Description                              |
| ------------------ | ------ | ---------------------------------------- |
| `eventName`        | string | Event identifier that triggers this text |
| `playerOnlyEvents` | bool   | Only show for player-involved events     |

### Text Formatting

| Field           | Type                        | Description             |
| --------------- | --------------------------- | ----------------------- |
| `formatterType` | ScreenTextFormatterTypeBase | Custom text formatter   |
| `formatterData` | ScreenTextFormatterData     | Formatter configuration |

### Visual Configuration

| Field             | Type           | Description                   |
| ----------------- | -------------- | ----------------------------- |
| `fontAsset`       | TMP\_FontAsset | Custom font (optional)        |
| `textColor`       | Color          | Text color                    |
| `fontSize`        | float          | Font size (12-72)             |
| `displayDuration` | float          | Time visible (0.5-5 seconds)  |
| `fadeDuration`    | float          | Fade-out time (0.1-2 seconds) |

### Animation

| Field              | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| `animationEnabled` | bool           | Enable movement/scale animation |
| `yMovementCurve`   | AnimationCurve | Vertical movement over time     |
| `xMovementCurve`   | AnimationCurve | Horizontal movement over time   |
| `scaleCurve`       | AnimationCurve | Scale over time                 |

### Positioning

| Field                  | Type            | Description                          |
| ---------------------- | --------------- | ------------------------------------ |
| `positionMode`         | PositionMode    | Screen, Target, or Custom            |
| `screenAlignment`      | ScreenAlignment | 9-point screen alignment             |
| `screenPositionOffset` | Vector2         | Pixel offset from alignment          |
| `followTarget`         | bool            | Track moving targets                 |
| `worldSpaceOffset`     | Vector3         | Offset from world position           |
| `randomizePosition`    | bool            | Add random offset to prevent overlap |
| `randomXPosition`      | Vector2         | Random X range                       |
| `randomYPosition`      | Vector2         | Random Y range                       |
| `parentName`           | string          | Name of a custom parent transform    |

### Enums

```csharp
public enum PositionMode { Screen, Target, Custom }

public enum ScreenAlignment
{
    Center, Top, Bottom, Left, Right,
    TopLeft, TopRight, BottomLeft, BottomRight
}
```

**Methods:**

```csharp
bool IsValid()
string GetFormattedText(SparkEventBase sparkEvent)
```

## Components

### ScreenTextsManager

MonoBehaviour that handles spawning and pooling screen text entities.

| Field               | Type             | Description                    |
| ------------------- | ---------------- | ------------------------------ |
| `container`         | Transform        | Parent for spawned text        |
| `screenTextPrefab`  | ScreenTextEntity | Prefab template                |
| `customParents`     | Transform\[]     | Named custom parent transforms |
| `initialPoolSize`   | int              | Starting pool size (5-50)      |
| `maxPoolSize`       | int              | Maximum pool size (10-200)     |
| `defaultTextFormat` | string           | Fallback format string         |

Subscribes to `SparkEventBase` at priority 25. Automatically matches events to entries by event name and spawns formatted text.

**Methods:**

```csharp
void SpawnScreenText(ScreenTextEntry entry, string text, Vector3 worldPos)
void ReturnEntityToPool(ScreenTextEntity entity)
void RefreshEntryCache()
void TestScreenText(ScreenTextEntry entry)
string[] GetCachedEventNames()
```

### ScreenTextEntity

MonoBehaviour that renders and animates a single floating text instance.

Handles world-to-screen positioning, animated movement, scale, fade, target following, and visibility culling. Returns to pool on completion.

## Custom Formatters

Create custom text formatters by extending `ScreenTextFormatterTypeBase`:

```csharp
[CreateAssetMenu(menuName = "Spark/ScreenTexts/My Formatter")]
public class MyFormatterType : ScreenTextFormatterTypeBase
{
    public override Type GetExpectedDataType() => typeof(MyFormatterData);
    public override ScreenTextFormatterData CreateDefaultData() => new MyFormatterData();
    public override string GetDescription() => "My custom formatter";
}
```

## Usage

```csharp
var screenTexts = Spark.GetPlugin<IScreenTextsPlugin>();
if (screenTexts != null)
{
    // Show damage number at a world position
    screenTexts.DisplayScreenText("Combat.DamageDealt", "-50", targetPosition);

    // Show a notification at configured screen position
    screenTexts.DisplayScreenText("Quest.Completed", "Quest Complete!");
}
```


---

# 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/screentexts/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.