# API

**Assembly:** `Spark.Playables` **Interface:** `IPlayablesPlugin` **Implementation:** `PlayablesPlugin`

## Interface

```csharp
public interface IPlayablesPlugin
{
    // Animation
    void ExecutePlayableAnimation(PlayableAnimationEntry entry,
        PlayableExecutionContext context);
    void ExecutePlayableAnimation(PlayableAnimationEntry entry,
        PlayableExecutionContext context, float delay);
    void ExecutePlayableAnimation(PlayableAnimationEntry entry,
        PlayableExecutionContext context, PlayableAnimationTargeting targeting);

    // Sound
    void ExecutePlayableSound(PlayableSoundEntry entry,
        PlayableExecutionContext context);
    void ExecutePlayableSound(PlayableSoundEntry entry,
        PlayableExecutionContext context, Vector3 position);
    void ExecutePlayableSound(PlayableSoundEntry entry,
        PlayableExecutionContext context, float delay);

    // GameObject
    void ExecutePlayableGameObject(PlayableGameObjectEntry entry,
        PlayableExecutionContext context);
    void ExecutePlayableGameObject(PlayableGameObjectEntry entry,
        PlayableExecutionContext context, Vector3 position, Quaternion rotation);
    void ExecutePlayableGameObject(PlayableGameObjectEntry entry,
        PlayableExecutionContext context, float delay);
    void ExecutePlayableGameObject(PlayableGameObjectEntry entry,
        PlayableExecutionContext context, float delay, float duration);

    // Generic
    void ExecutePlayable(SparkDatabaseEntry entry,
        PlayableExecutionContext context);
    bool IsPlayableSupported(SparkDatabaseEntry entry);
}
```

## PlayableExecutionContext

Carries source, target, position, and rotation data for playable execution.

| Property         | Type                  | Description                        |
| ---------------- | --------------------- | ---------------------------------- |
| `source`         | GameObject            | The entity initiating the playable |
| `manualPosition` | Optional\<Vector3>    | Override world position            |
| `manualRotation` | Optional\<Quaternion> | Override rotation                  |
| `manualParent`   | Transform             | Override parent transform          |
| `manualTarget`   | GameObject            | Override target object             |

**Methods:**

```csharp
SparkEntity GetSparkEntity()         // Gets SparkEntity from source
T GetComponent<T>()                  // SparkEntity-aware component lookup
bool TryGetComponent<T>(out T comp)  // Safe component lookup

// Fluent builders
PlayableExecutionContext WithPosition(Vector3 pos)
PlayableExecutionContext WithRotation(Quaternion rot)
PlayableExecutionContext WithParent(Transform parent)
PlayableExecutionContext WithTarget(GameObject target)
```

## Position, Rotation, and Target Modes

```csharp
public enum PlayablePositionMode { Source, Offset, Manual }
public enum PlayableRotationMode { Source, Fixed, Identity, Manual }
public enum PlayableTargetMode  { Source, ChildWithTag, Manual }
```

## Database Entries

### PlayableAnimationEntry

Plays character animations.

| Field                  | Type                  | Description                       |
| ---------------------- | --------------------- | --------------------------------- |
| `parameterName`        | string                | Animator parameter name           |
| `isRandom`             | bool                  | Enable random parameter selection |
| `randomParameterNames` | List\<string>         | Pool of random parameter names    |
| `parameterType`        | AnimatorParameterType | Trigger, Bool, Int, or Float      |
| `boolValue`            | bool                  | Value for Bool parameters         |
| `intValue`             | int                   | Value for Int parameters          |
| `floatValue`           | float                 | Value for Float parameters        |

**Methods:**

```csharp
string GetParameterName()          // Returns selected parameter (random if enabled)
void ApplyToAnimator(Animator anim) // Sets the parameter on the animator
bool IsValid()                      // True if properly configured
```

### PlayableSoundEntry

Plays audio clips.

| Field             | Type             | Description                  |
| ----------------- | ---------------- | ---------------------------- |
| `audioClip`       | AudioClip        | Single audio clip            |
| `randomClip`      | bool             | Enable random clip selection |
| `audioClips`      | List\<AudioClip> | Pool of random clips         |
| `audioMixerGroup` | AudioMixerGroup  | Audio routing group          |
| `volume`          | float            | Playback volume              |
| `pitch`           | float            | Playback pitch               |
| `spatialBlend`    | float            | 0 = 2D, 1 = 3D               |
| `maxDistance`     | float            | 3D audio max distance        |
| `rolloffMode`     | AudioRolloffMode | Distance attenuation curve   |
| `loop`            | bool             | Loop the audio               |

**Methods:**

```csharp
AudioClip GetAudioClip()                      // Returns selected clip
bool IsValid()                                 // True if clip is assigned
void ConfigureAudioSource(AudioSource source)  // Applies all settings to source
```

### PlayableGameObjectEntry

Instantiates prefabs with positioning, rotation, parenting, and optional auto-destruction.

### PlayableTransformEntry

Moves, rotates, or scales objects over a duration with easing. Supports per-entity overrides via `PlayableTransformEntryOverride`.

### PlayableCoordinatesEntry

Moves an entity to specific world coordinates. Used for scripted movement sequences.

### PlayableCameraOverrideEntry

Temporarily switches to a different camera view for a duration. Used for cutscenes.

## Events

| Event                   | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `PlayableRequestEvent`  | Requesting a playable to execute (priority 100) |
| `PlayableExecutedEvent` | A playable finished executing (priority 50)     |

**PlayableRequestEvent fields:**

| Field           | Type                     | Description             |
| --------------- | ------------------------ | ----------------------- |
| `playableEntry` | SparkDatabaseEntry       | The playable to execute |
| `context`       | PlayableExecutionContext | Execution context       |

**PlayableExecutedEvent fields:**

| Field           | Type                     | Description                 |
| --------------- | ------------------------ | --------------------------- |
| `playableEntry` | SparkDatabaseEntry       | The playable that executed  |
| `context`       | PlayableExecutionContext | Execution context           |
| `success`       | bool                     | Whether execution succeeded |
| `errorMessage`  | string                   | Error details if failed     |

## Components

| Component                        | Description                                   |
| -------------------------------- | --------------------------------------------- |
| `PlayableEntity`                 | Links a GameObject to the playable system     |
| `PlayableTransformEntity`        | Entity with per-entity transform overrides    |
| `PlayableTransformEntryOverride` | Override data for transform playables         |
| `PlayableAudioSource`            | Spatial audio source for sound playables      |
| `CameraOverrideEntity`           | Camera activated by camera override playables |
| `PlayableAnimationTracker`       | Tracks currently playing animations           |

## Execution Infrastructure

| Class                           | Description                                 |
| ------------------------------- | ------------------------------------------- |
| `PlayableExecutor`              | Core engine that runs all playable types    |
| `PlayableConfiguration`         | Bundles multiple playables into a sequence  |
| `PlayableCoroutineHelper`       | Runs coroutines from non-MonoBehaviour code |
| `AnimationSpeedCurveController` | Applies speed curves to animations          |

## Usage

```csharp
var playables = Spark.GetPlugin<IPlayablesPlugin>();
if (playables != null)
{
    var context = new PlayableExecutionContext
    {
        source = playerObject
    }.WithPosition(spawnPoint);

    // Play a sound
    playables.ExecutePlayableSound(hitSoundEntry, context);

    // Play an animation
    playables.ExecutePlayableAnimation(attackAnimEntry, context);

    // Spawn a VFX prefab
    playables.ExecutePlayableGameObject(vfxEntry, context, delay: 0.5f);

    // Generic execution (auto-detects type)
    playables.ExecutePlayable(someEntry, context);
}
```


---

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