document 2 force natives (#1203)

* document 2 force natives * add back links * add back links * remove link * Apply suggestions from code review --------- Co-authored-by: Dillon Skaggs <[email protected]>
citizenfx · Feb 25, 2025 · 6198ca2 · 6198ca2
1 parent eab3379
commit 6198ca2
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 62 deletions.
diff --git a/ENTITY/ApplyForceToEntity.md b/ENTITY/ApplyForceToEntity.md
@@ -5,76 +5,61 @@ ns: ENTITY
 
 ```c
 // 0xC5F68BE9613E2D18 0xC1C0855A
-void APPLY_FORCE_TO_ENTITY(Entity entity, int forceType, float x, float y, float z, float offX, float offY, float offZ, int boneIndex, BOOL isDirectionRel, BOOL ignoreUpVec, BOOL isForceRel, BOOL p12, BOOL p13);
+void APPLY_FORCE_TO_ENTITY(Entity entity, int forceType, float x, float y, float z, float offX, float offY, float offZ, int nComponent, BOOL bLocalForce, BOOL bLocalOffset, BOOL bScaleByMass, BOOL bPlayAudio, BOOL bScaleByTimeWarp);
 ```
 
-Applies a force to the specified entity.
 
 ```c
-enum eForceType
-{
-    MinForce = 0,
-    MaxForceRot = 1,
-    MinForce2 = 2,
-    MaxForceRot2 = 3,
-    ForceNoRot = 4,
-    ForceRotPlusForce = 5
+enum eApplyForceTypes {
+    APPLY_TYPE_FORCE = 0,
+    APPLY_TYPE_IMPULSE = 1,
+    APPLY_TYPE_EXTERNAL_FORCE = 2,
+    APPLY_TYPE_EXTERNAL_IMPULSE = 3,
+    APPLY_TYPE_TORQUE = 4,
+    APPLY_TYPE_ANGULAR_IMPULSE = 5
 }
 ```
 
-Research/documentation on the gtaforums can be found [here](https://gtaforums.com/topic/885669-precisely-define-object-physics/) and [here](https://gtaforums.com/topic/887362-apply-forces-and-momentums-to-entityobject/).
-
-
 ## Parameters
-* **entity**: The entity you want to apply a force on
-* **forceType**: Refer to `eForceType`
-* **x**: Force amount (X)
-* **y**: Force amount (Y)
-* **z**: Force amount (Z)
-* **offX**: Rotation/offset force (X)
-* **offY**: Rotation/offset force (Y)
-* **offZ**: Rotation/offset force (Z)
-* **boneIndex**: (Often 0) Entity bone index
-* **isDirectionRel**: (Usually false) Vector defined in local (body-fixed) coordinate frame
-* **ignoreUpVec**: (Usually true)
-* **isForceRel**: (Usually true) When true, force gets multiplied with the objects mass and different objects will have the same acceleration
-* **p12**: (Usually false)
-* **p13**: (Usually true)
-
+* **entity**: The entity handle
+* **forceType**: The force type
+* **x**: The x component of the force to apply
+* **y**: The y component of the force to apply
+* **z**: The z component of the force to apply
+* **offX**: Offset from center of entity (X)
+* **offY**: Offset from center of entity (Y)
+* **offZ**: Offset from center of entity (Z)
+* **nComponent**: Component of the entity to apply the force too. Only matters for breakable or articulated (ragdoll) physics. 0 means the root or parent component
+* **bLocalForce**: Specifies whether the force vector passed in is in local or world coordinates. `true` means the force will get automatically transformed into world space before being applied
+* **bLocalOffset**: Specifies whether the offset passed in is in local or world coordinates
+* **bScaleByMass**: Specifies whether to scale the force by mass
+* **bPlayAudio**: Specifies whether to play audio events related to the force being applied. The audio will depend on the entity type. Currently vehicles are the only entity types supported, and will play a suspension squeal depending on the magnitude of the force
+* **bScaleByTimeWarp**: Specifies whether to scale the force by time warp. Default is `true`
 
 ## Examples
 ```lua
-local forceTypes = {
-    MinForce = 0,
-    MaxForceRot = 1,
-    MinForce2 = 2,
-    MaxForceRot2 = 3,
-    ForceNoRot = 4,
-    ForceRotPlusForce = 5
-}
-
 local entity = PlayerPedId()
-local forceType = forceTypes.MaxForceRot2
+local forceType = 2
  -- sends the entity straight up into the sky:
 local direction = vector3(0.0, 0.0, 15.0)
-local rotation = vector3(0.0, 0.0, 0.0)
-local boneIndex = 0
-local isDirectionRel = false
-local ignoreUpVec = true
-local isForceRel = true
-local p12 = false
-local p13 = true
+local offset = vector3(0.0, 0.0, 0.0)
+local component = 0
+local localForce = false
+local localOffset = true
+local scaleByMass = true
+local playAudio = false
+local scaleByTimeWarp = true
 
 ApplyForceToEntity(
     entity,
     forceType,
     direction,
-    rotation,
+    offset,
     boneIndex,
-    isDirectionRel,
-    ignoreUpVec,
-    isForceRel,
-    p12,
-    p13
+    localForce,
+    localOffset,
+    scaleByMass,
+    playAudio,
+    scaleByTimeWarp
 )
 ```
diff --git a/ENTITY/ApplyForceToEntityCenterOfMass.md b/ENTITY/ApplyForceToEntityCenterOfMass.md
@@ -5,17 +5,18 @@ ns: ENTITY
 
 ```c
 // 0x18FF00FC7EFF559E 0x28924E98
-void APPLY_FORCE_TO_ENTITY_CENTER_OF_MASS(Entity entity, int forceType, float x, float y, float z, BOOL p5, BOOL isDirectionRel, BOOL isForceRel, BOOL p8);
+void APPLY_FORCE_TO_ENTITY_CENTER_OF_MASS(Entity entity, int forceType, float x, float y, float z, cs_type(BOOL) int nComponent, BOOL bLocalForce, BOOL bScaleByMass, BOOL bApplyToChildren);
 ```
 
-## Parameters
-* **entity**: 
-* **forceType**: Refer to [APPLY_FORCE_TO_ENTITY](#_0xC5F68BE9613E2D18)
-* **x**: 
-* **y**: 
-* **z**: 
-* **p5**: 
-* **isDirectionRel**: 
-* **isForceRel**: 
-* **p8**: 
+Apply a force to an entities center of mass.
 
+## Parameters
+* **entity**: The entity handle
+* **forceType**: The force type, see [`APPLY_FORCE_TO_ENTITY`](#_0xC5F68BE9613E2D18)
+* **x**: The x component of the force to apply
+* **y**: The y component of the force to apply
+* **z**: The z component of the force to apply
+* **nComponent**: Component of the entity to apply the force too. Only matters for breakable or articulated (ragdoll) physics. 0 means the root or parent component
+* **bLocalForce**: Specifies whether the force vector passed in is in local or world coordinates. `true` means the force will get automatically transformed into world space before being applied
+* **bScaleByMass**: Specifies whether to scale the force by mass
+* **bApplyToChildren**: Default `false`. If the force should be applied to any attached children