From ba89303e043ddb64c84f13529a71fdc3e738ff3d Mon Sep 17 00:00:00 2001 From: Dillon Skaggs Date: Mon, 26 Aug 2024 10:55:55 -0500 Subject: [PATCH] feat(natives/task): document how to use the sequence natives (#1173) --- TASK/ClearSequenceTask.md | 9 +- TASK/CloseSequenceTask.md | 9 +- TASK/OpenSequenceTask.md | 109 ++++++++++++++++++++++- TASK/TaskPerformSequence.md | 9 +- TASK/TaskPerformSequenceFromProgress.md | 110 ++++++++++++++++++++++-- TASK/TaskPerformSequenceLocally.md | 12 +-- 6 files changed, 235 insertions(+), 23 deletions(-) diff --git a/TASK/ClearSequenceTask.md b/TASK/ClearSequenceTask.md index 6f413b7c3..f0b919f73 100644 --- a/TASK/ClearSequenceTask.md +++ b/TASK/ClearSequenceTask.md @@ -8,7 +8,10 @@ ns: TASK cs_type(Any) void CLEAR_SEQUENCE_TASK(int* taskSequenceId); ``` -## Parameters -* **taskSequenceId**: +For an example on how to use this please refer to [OPEN_SEQUENCE_TASK](#_0xE8854A4326B9E12B) + +#### NOTE +If you fail to call [`CLOSE_SEQUENCE_TASK`](#_0x39E72BC99E6360CB) and `CLEAR_SEQUENCE_TASK` the sequence system can get stuck in a broken state until you restart your client. -## Return value +## Parameters +* **taskSequenceId**: The task sequence to clear diff --git a/TASK/CloseSequenceTask.md b/TASK/CloseSequenceTask.md index 0a0c46521..9722d79ae 100644 --- a/TASK/CloseSequenceTask.md +++ b/TASK/CloseSequenceTask.md @@ -8,7 +8,10 @@ ns: TASK cs_type(Any) void CLOSE_SEQUENCE_TASK(int taskSequenceId); ``` -## Parameters -* **taskSequenceId**: +For an example on how to use this please refer to [OPEN_SEQUENCE_TASK](#_0xE8854A4326B9E12B) + +#### NOTE +If you fail to call `CLOSE_SEQUENCE_TASK` and [`CLEAR_SEQUENCE_TASK`](#_0x3841422E9C488D8C) this can get stuck in a broken state until you restart your client. -## Return value +## Parameters +* **taskSequenceId**: The task sequence to close diff --git a/TASK/OpenSequenceTask.md b/TASK/OpenSequenceTask.md index 5056524f1..278cf2ca0 100644 --- a/TASK/OpenSequenceTask.md +++ b/TASK/OpenSequenceTask.md @@ -8,7 +8,112 @@ ns: TASK cs_type(Any) void OPEN_SEQUENCE_TASK(int* taskSequenceId); ``` +### NOTE +If this returns 0 that means it failed to get a sequence id. + +If you fail to call [`CLOSE_SEQUENCE_TASK`](#_0x39E72BC99E6360CB) and [`CLEAR_SEQUENCE_TASK`](#_0x3841422E9C488D8C) the sequence system can get stuck in a broken state until you restart your client. + + ## Parameters -* **taskSequenceId**: +* **taskSequenceId**: The reference to bind to, in Lua/JS this will be returned as a value + +## Examples +```lua +Citizen.CreateThread(function() + local animDict = 'timetable@ron@ig_5_p3' + + RequestAnimDict(animDict) + while not HasAnimDictLoaded(animDict) do + Wait(0) + end + + local ped = PlayerPedId() + local pos = GetEntityCoords(ped) + + -- you can change the model, but you might have to change the offsets below. + local objModelHash = `prop_bench_01a` + + local obj = GetClosestObjectOfType(pos.x, pos.y, pos.z, 5.0, objModelHash, false, false, false) + if obj == 0 then + print("No valid object within range!") + return + end + + local tgtPos = GetOffsetFromEntityInWorldCoords(obj, 0.0, -0.7, 0.0) + + -- open the task sequence so we can get our sequence id + local sequence = OpenSequenceTask() + + -- set our desired heading to be the same as the objects + local desiredHeading = GetEntityHeading(obj) - 180.0 + + -- go to the entities offset + TaskGoStraightToCoord(nil, tgtPos.x, tgtPos.y, tgtPos.z, 1.0, 4000, desiredHeading, 1.0) + + -- sit on the bench indefinitely (you can change -1 here to however long you want to sit) + TaskPlayAnim(nil, animDict, 'ig_5_p3_base', 8.0, 8.0, -1, 1) + + -- close the sequence so we can perform it + CloseSequenceTask(sequence) + + -- perform the sequence, this will not work if the sequence is still open. + TaskPerformSequence(ped, sequence) + + -- free the sequence slot so it can be re-used + ClearSequenceTask(sequence) -## Return value + -- cleanup the animation dict so the engine can remove it when its no longer needed + RemoveAnimDict(animDict) +end) +``` + +```cs +using CitizenFX.Core; +using static CitizenFX.Core.Native.API; + +string animDict = "timetable@ron@ig_5_p3"; +RequestAnimDict(animDict); +while (!HasAnimDictLoaded(animDict)) +{ + await BaseScript.Delay(0); +} + +int ped = PlayerPedId(); +Vector3 pos = GetEntityCoords(ped, false); + +// you can change the model, but you might have to change the offsets below. +uint hash = Game.GenerateHashASCII("prop_bench_01a"); + +int obj = GetClosestObjectOfType(pos.X, pos.Y, pos.Z, 5.0f, hash, false, false, false); +if (obj == 0) +{ + Debug.WriteLine("No valid object within range!"); + return; +} + +Vector3 tgtPos = GetOffsetFromEntityInWorldCoords(obj, 0.0f, -0.7f, 0.0f); + +int sequenceId = 0; +// open the task sequence so we can get our sequence id +OpenSequenceTask(ref sequenceId); + +float desiredHeading = GetEntityHeading(obj) - 180.0f; + +// go to the entities offset +TaskGoStraightToCoord(0, tgtPos.X, tgtPos.Y, tgtPos.Z, 1.0f, 4000, desiredHeading, 1.0f); + +// sit on the bench indefinitely (you can change -1 here to however long you want to sit) +TaskPlayAnim(0, animDict, "ig_5_p3_base", 8.0f, 8.0f, -1, 1, 1.0f, false, false, false); + +// close the sequence so we can perform it +CloseSequenceTask(sequenceId); + +// perform the sequence, this will not work if the sequence is still open. +TaskPerformSequence(ped, sequenceId); + +// free the sequence slot so it can be re-used +ClearSequenceTask(ref sequenceId); + +// cleanup the animation dict so the engine can remove it when its no longer needed +RemoveAnimDict(animDict); +``` diff --git a/TASK/TaskPerformSequence.md b/TASK/TaskPerformSequence.md index b6dbe90af..93d706571 100644 --- a/TASK/TaskPerformSequence.md +++ b/TASK/TaskPerformSequence.md @@ -8,8 +8,9 @@ ns: TASK cs_type(Any) void TASK_PERFORM_SEQUENCE(Ped ped, int taskSequenceId); ``` -## Parameters -* **ped**: -* **taskSequenceId**: +For an example on how to use this please refer to [OPEN_SEQUENCE_TASK](#_0xE8854A4326B9E12B) + -## Return value +## Parameters +* **ped**: The ped to perform the sequence on +* **taskSequenceId**: The sequenceId to perform diff --git a/TASK/TaskPerformSequenceFromProgress.md b/TASK/TaskPerformSequenceFromProgress.md index 7bd106c5b..20747120e 100644 --- a/TASK/TaskPerformSequenceFromProgress.md +++ b/TASK/TaskPerformSequenceFromProgress.md @@ -5,13 +5,113 @@ ns: TASK ```c // 0x89221B16730234F0 0xFA60601B -void TASK_PERFORM_SEQUENCE_FROM_PROGRESS(Any p0, Any p1, Any p2, Any p3); +void TASK_PERFORM_SEQUENCE_FROM_PROGRESS(Ped ped, int taskIndex, int progress1, int progress2); ``` ## Parameters -* **p0**: -* **p1**: -* **p2**: -* **p3**: +* **ped**: The ped to perform the task on +* **taskIndex**: +* **progress1**: The progress to start from +* **progress2**: Unknown what it does, it has to be set higher than 0 to not break the sequence +## Examples +```lua +Citizen.CreateThread(function() + local animDict = 'timetable@ron@ig_5_p3' + + RequestAnimDict(animDict) + while not HasAnimDictLoaded(animDict) do + Wait(0) + end + + local ped = PlayerPedId() + local pos = GetEntityCoords(ped) + + -- you can change the model, but you might have to change the offsets below. + local objModelHash = `prop_bench_01a` + + local obj = GetClosestObjectOfType(pos.x, pos.y, pos.z, 5.0, objModelHash, false, false, false) + if obj == 0 then + print("No valid object within range!") + return + end + + local tgtPos = GetOffsetFromEntityInWorldCoords(obj, 0.0, -0.7, 0.0) + + -- open the task sequence so we can get our sequence id + local sequence = OpenSequenceTask() + + local desiredHeading = GetEntityHeading(obj) - 180.0 + + -- go to the entities offset + TaskGoStraightToCoord(nil, tgtPos.x, tgtPos.y, tgtPos.z, 1.0, 4000, desiredHeading, 1.0) + + -- sit on the bench indefinitely (you can change -1 here to however long you want to sit) + TaskPlayAnim(nil, animDict, 'ig_5_p3_base', 8.0, 8.0, -1, 1) + + -- close the sequence so we can perform it + CloseSequenceTask(sequence) + + -- perform the sequence, this will not work if the sequence is still open. + -- note that progress1 is set to 1, this means it will skip the first sequence + TaskPerformSequenceFromProgress(ped, sequence, 1, 1) + + -- free the sequence slot so it can be re-used + ClearSequenceTask(sequence) + + -- cleanup the animation dict so the engine can remove it when its no longer needed + RemoveAnimDict(animDict) +end) +``` +```cs +using CitizenFX.Core; +using static CitizenFX.Core.Native.API; + +string animDict = "timetable@ron@ig_5_p3"; +RequestAnimDict(animDict); +while (!HasAnimDictLoaded(animDict)) +{ + await BaseScript.Delay(0); +} + +int ped = PlayerPedId(); +Vector3 pos = GetEntityCoords(ped, false); + +// you can change the model, but you might have to change the offsets below. +uint hash = Game.GenerateHashASCII("prop_bench_01a"); + +int obj = GetClosestObjectOfType(pos.X, pos.Y, pos.Z, 5.0f, hash, false, false, false); +if (obj == 0) +{ + Debug.WriteLine("No valid object within range!"); + return; +} + +Vector3 tgtPos = GetOffsetFromEntityInWorldCoords(obj, 0.0f, -0.7f, 0.0f); + +int sequenceId = 0; +// open the task sequence so we can get our sequence id +OpenSequenceTask(ref sequenceId); + +float desiredHeading = GetEntityHeading(obj) - 180.0f; + +// go to the entitys offset +TaskGoStraightToCoord(0, tgtPos.X, tgtPos.Y, tgtPos.Z, 1.0f, 4000, desiredHeading, 1.0f); + +// sit on the bench indefinitely (you can change -1 here to however long you want to sit) +TaskPlayAnim(0, animDict, "ig_5_p3_base", 8.0f, 8.0f, -1, 1, 1.0f, false, false, false); + +// close the sequence so we can perform it +CloseSequenceTask(sequenceId); + +// perform the sequence, this will not work if the sequence is still open. +// note that progress1 is set to 1, this means it will skip the first sequence +TaskPerformSequenceFromProgress(ped, sequenceId, 1, 1); + +// free the sequence slot so it can be re-used +ClearSequenceTask(ref sequenceId); + +// cleanup the animation dict so the engine can remove it when its no longer needed +RemoveAnimDict(animDict); +``` diff --git a/TASK/TaskPerformSequenceLocally.md b/TASK/TaskPerformSequenceLocally.md index 11a2f1a91..708b231d5 100644 --- a/TASK/TaskPerformSequenceLocally.md +++ b/TASK/TaskPerformSequenceLocally.md @@ -1,16 +1,16 @@ --- ns: TASK -aliases: ["0x8C33220C8D78CA0D"] +aliases: ["0x8C33220C8D78CA0D", "_TASK_PERFORM_SEQUENCE_LOCALLY"] --- -## _TASK_PERFORM_SEQUENCE_LOCALLY +## TASK_PERFORM_SEQUENCE_LOCALLY ```c // 0x8C33220C8D78CA0D -void _TASK_PERFORM_SEQUENCE_LOCALLY(Ped ped, int taskSequenceId); +void TASK_PERFORM_SEQUENCE_LOCALLY(Ped ped, int taskSequenceId); ``` +For an example on how to use this please refer to [OPEN_SEQUENCE_TASK](#_0xE8854A4326B9E12B ## Parameters -* **ped**: -* **taskSequenceId**: - +* **ped**: The ped to perform the sequence on +* **taskSequenceId**: The sequence to perform