> For the complete documentation index, see [llms.txt](https://docs.sparkframework.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkframework.dev/documentation/developer-guide/core-systems/screentexts/api.md).

# 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
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://docs.sparkframework.dev/documentation/developer-guide/core-systems/screentexts/api.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.