Skip to content

api-reference.md

Latest commit

 

History

History
410 lines (337 loc) · 10.7 KB

api-reference.md

File metadata and controls

410 lines (337 loc) · 10.7 KB
Raw

ObjectAnimator API Reference

Comprehensive reference for all Pawn natives exposed by object_animator.inc.

All natives use the prefix OA_* (or OA_Animation* for reusable animation definitions).

Table of Contents

  1. Handle Types & Constants
  2. Creation & Lifecycle
  3. Timeline Building
  4. Playback Controls
  5. Reusable Animation Definitions
  6. Diagnostics & Errors

Handle Types & Constants

  • Animator: - Tag for an animator instance attached to a world object.
  • Animation: - Tag for a reusable, immutable animation template.
  • INVALID_ANIMATOR - Value Animator:0.
  • INVALID_ANIMATION - Value Animation:0.

Creation & Lifecycle

OA_Create

Signature:

Animator:OA_Create(objectid);

Description: Creates an animator instance attached to a global server object. Parameters:

  • objectid - SA-MP global object ID. Returns: Valid Animator: handle on success, or INVALID_ANIMATOR on failure. Failure Conditions: Server object ID does not exist or internal capacity exceeded. Example:
new Animator:anim = OA_Create(gate_object);

OA_CreatePlayerObject

Signature:

Animator:OA_CreatePlayerObject(playerid, objectid);

Description: Creates an animator instance attached to a player-specific object. Parameters:

  • playerid - Connected player ID.
  • objectid - Player object ID. Returns: Valid Animator: handle on success, or INVALID_ANIMATOR on failure. Failure Conditions: Invalid player ID, player not connected, or invalid player object ID.

OA_Destroy

Signature:

bool:OA_Destroy(Animator:animator);

Description: Destroys an animator instance and releases its resources. Old handles immediately become invalid. Parameters:

  • animator - Animator handle. Returns: true on success, false on invalid handle.

OA_IsValid

Signature:

bool:OA_IsValid(Animator:animator);

Description: Checks whether an animator handle refers to an active, non-destroyed animator. Parameters:

  • animator - Animator handle. Returns: true if handle is valid, false if stale or invalid.

OA_Play

Signature:

bool:OA_Play(Animator:animator);

Description: Begins timeline playback from the current time. If stopped, captures object transform and prepares the timeline sequence. Parameters:

  • animator - Animator handle. Returns: true if playback started or was already running, false on failure (e.g. empty timeline).

OA_Pause

Signature:

bool:OA_Pause(Animator:animator);

Description: Temporarily halts playback at the current timestamp. Object remains at its current position. Parameters:

  • animator - Animator handle. Returns: true if paused, false if animator is not playing.

OA_Resume

Signature:

bool:OA_Resume(Animator:animator);

Description: Resumes playback from a paused state. Parameters:

  • animator - Animator handle. Returns: true if resumed, false if not paused.

OA_Stop

Signature:

bool:OA_Stop(Animator:animator);

Description: Halts playback and keeps the object at its current transform. Parameters:

  • animator - Animator handle. Returns: true on success.

OA_Reset

Signature:

bool:OA_Reset(Animator:animator);

Description: Stops playback, rewinds time to 0, and restores the object to its starting transform. Parameters:

  • animator - Animator handle. Returns: true on success.

OA_IsPlaying

Signature:

bool:OA_IsPlaying(Animator:animator);

Description: Checks if the animator is actively playing.

OA_IsPaused

Signature:

bool:OA_IsPaused(Animator:animator);

Description: Checks if the animator is currently paused.

Timeline Building

OA_MoveTo

Signature:

bool:OA_MoveTo(Animator:animator, Float:x, Float:y, Float:z, duration, Easing:easing = EASE_LINEAR);

Description: Appends an absolute movement node to world coordinates $(x, y, z)$. Parameters:

  • animator - Animator handle.
  • x, y, z - Target world coordinates.
  • duration - Duration in milliseconds.
  • easing - Easing curve from Easing: enum.

OA_MoveBy

Signature:

bool:OA_MoveBy(Animator:animator, Float:x, Float:y, Float:z, duration, Easing:easing = EASE_LINEAR);

Description: Appends a relative movement node offset $(\Delta x, \Delta y, \Delta z)$ from the previous node end position.

OA_RotateTo

Signature:

bool:OA_RotateTo(Animator:animator, Float:rx, Float:ry, Float:rz, duration, Easing:easing = EASE_LINEAR);

Description: Appends an absolute rotation node to target angles $(rx, ry, rz)$ using shortest angular distance interpolation.

OA_RotateBy

Signature:

bool:OA_RotateBy(Animator:animator, Float:rx, Float:ry, Float:rz, duration, Easing:easing = EASE_LINEAR);

Description: Appends a relative rotation node by angular offset $(\Delta rx, \Delta ry, \Delta rz)$. Supports continuous multi-turn spins (e.g. 720.0).

OA_TransformTo

Signature:

bool:OA_TransformTo(Animator:animator, Float:x, Float:y, Float:z, Float:rx, Float:ry, Float:rz, duration, Easing:easing = EASE_LINEAR);

Description: Appends a simultaneous absolute movement and rotation node.

OA_TransformBy

Signature:

bool:OA_TransformBy(Animator:animator, Float:x, Float:y, Float:z, Float:rx, Float:ry, Float:rz, duration, Easing:easing = EASE_LINEAR);

Description: Appends a simultaneous relative movement and rotation offset node.

OA_Wait

Signature:

bool:OA_Wait(Animator:animator, duration);

Description: Appends an idle delay node for the specified duration in milliseconds.

OA_SetPosition

Signature:

bool:OA_SetPosition(Animator:animator, Float:x, Float:y, Float:z);

Description: Appends an instant transform node (duration = 0) that sets coordinates immediately.

OA_SetRotation

Signature:

bool:OA_SetRotation(Animator:animator, Float:rx, Float:ry, Float:rz);

Description: Appends an instant rotation node (duration = 0) that sets rotation immediately.

OA_Event

Signature:

bool:OA_Event(Animator:animator, const event[]);

Description: Appends an instant event node that dispatches OnOAEvent(animator, event) when playback crosses this timestamp.

Playback Controls

OA_SetLoop

bool:OA_SetLoop(Animator:animator, bool:enabled);

Enables or disables looping when the timeline reaches its conclusion.

OA_SetLoopCount

bool:OA_SetLoopCount(Animator:animator, count);

Configures the maximum number of loop cycles (0 = infinite).

OA_SetPingPong

bool:OA_SetPingPong(Animator:animator, bool:enabled);

Enables back-and-forth reversing playback when reaching either end of the timeline.

OA_SetSpeed

bool:OA_SetSpeed(Animator:animator, Float:speed);

Sets the playback rate multiplier (1.0 = normal, 2.0 = double speed, 0.5 = half speed).

OA_GetSpeed

Float:OA_GetSpeed(Animator:animator);

Returns current playback speed multiplier.

OA_Seek

bool:OA_Seek(Animator:animator, time);

Instantly positions the timeline and updates the object's transform to the state at time (in ms).

OA_GetTime

OA_GetTime(Animator:animator);

Returns elapsed timeline time in milliseconds.

OA_GetDuration

OA_GetDuration(Animator:animator);

Returns total timeline duration in milliseconds.

Reusable Animation Definitions

OA_AnimationCreate

Animation:OA_AnimationCreate();

Creates an immutable animation template.

OA_AnimationDestroy

bool:OA_AnimationDestroy(Animation:animation);

Destroys an animation template.

OA_AnimationClear

bool:OA_AnimationClear(Animation:animation);

Clears all nodes from a template.

OA_ApplyAnimation

bool:OA_ApplyAnimation(Animator:animator, Animation:animation);

Copies all nodes from the template into the specified animator's timeline.

OA_AnimationMoveTo / MoveBy / RotateTo / RotateBy / TransformTo / TransformBy / Wait / Event

Functions identical to their OA_* equivalents, but appending nodes to an Animation: template instead of an active animator.

Diagnostics & Errors

OA_SetDebug

OA_SetDebug(bool:enabled);

Enables or disables verbose server console logging of warnings and errors.

OA_GetLastError

OA_GetLastError();

Returns the last error code encountered:

  • OA_ERROR_NONE (0)
  • OA_ERROR_INVALID_HANDLE (1)
  • OA_ERROR_OBJECT_NOT_FOUND (2)
  • OA_ERROR_EMPTY_TIMELINE (3)
  • OA_ERROR_ALREADY_PLAYING (4)
  • OA_ERROR_NOT_PLAYING (5)
  • OA_ERROR_INVALID_PARAMETER (6)
  • OA_ERROR_MAX_CAPACITY (7)