Skip to content

feat(extra-natives-five): add msgpack support for scripted animation natives#3998

Open
Rogui20 wants to merge 3 commits into
citizenfx:masterfrom
Rogui20:master
Open

feat(extra-natives-five): add msgpack support for scripted animation natives#3998
Rogui20 wants to merge 3 commits into
citizenfx:masterfrom
Rogui20:master

Conversation

@Rogui20
Copy link
Copy Markdown

@Rogui20 Rogui20 commented May 19, 2026

Goal of this PR

This PR makes TASK_SCRIPTED_ANIMATION and PLAY_ENTITY_SCRIPTED_ANIM usable from script runtimes by allowing their animation data parameters to be passed as msgpack objects.

These natives expect internal animation slot data structs. This PR converts structured script data into the layout expected by the game native before forwarding the call.
...

How is this PR achieving the goal

This PR registers wrappers for:

  • TASK_SCRIPTED_ANIMATION
  • PLAY_ENTITY_SCRIPTED_ANIM

The wrappers:

  • read fx::scrObject msgpack arguments from the script runtime;
  • deserialize them into std::map<std::string, msgpack::object>;
  • populate a ScriptInitSlotData layout expected by the native;
  • keep string storage alive while assigning the internal string pointer fields;
  • replace the script arguments with pointers to the generated structs;
  • forward the call to the original native handler.

Empty or malformed msgpack data falls back to a default empty animation slot, allowing unused slots to be passed as an empty string or an empty msgpack object.

The native behavior itself is unchanged. This PR only adds argument translation.
...

This PR applies to the following area(s)

FiveM
Natives
ScRT: Lua
ScRT: JS
ScRT: C#
...

Successfully tested on

Latest FiveM Build
Game builds: ..
3095

Platforms: Windows, Linux
Windows

Checklist

  • Code compiles and has been tested successfully.
  • Code explains itself well and/or is documented.
  • My commit message explains what the changes do and what they are for.
  • No extra compilation warnings are added by these changes.

Fixes issues

Lua usage example

local data = msgpack.pack({
state = 1,
dict0 = "clip@chopper_generic",
clip0 = "hover",
phase0 = 0.0,
rate0 = 1.0,
weight0 = 1.0,
filter = 0,
blendInDuration = 0.1,
blendOutDuration = 0.1,
timeToPlay = -1,
flags = 1,
ikFlags = 0
})

-- Empty strings can be used for unused animation slots.
Citizen.InvokeNative(
0x77A1EEC547E7FCF1,
entity,
data,
"",
"",
0.125,
0.125
)

-- Same argument format also applies to TASK_SCRIPTED_ANIMATION.
Citizen.InvokeNative(
0x126EF75F1E17ABE5,
PlayerPedId(),
data,
"",
"",
0.125,
0.125
)

Scripted animation data fields

Each animation slot object can define up to three clips:

state
dict0, clip0, phase0, rate0, weight0
dict1, clip1, phase1, rate1, weight1
dict2, clip2, phase2, rate2, weight2
filter
blendInDuration
blendOutDuration
timeToPlay
flags
ikFlags

Known state values:

0: disabled / empty slot
1: single clip
2: blended slot using the configured clip entries

@github-actions github-actions Bot added the invalid Requires changes before it's considered valid and can be (re)triaged label May 19, 2026
@github-actions github-actions Bot added triage Needs a preliminary assessment to determine the urgency and required action invalid Requires changes before it's considered valid and can be (re)triaged and removed invalid Requires changes before it's considered valid and can be (re)triaged triage Needs a preliminary assessment to determine the urgency and required action labels May 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

invalid Requires changes before it's considered valid and can be (re)triaged

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant