diff --git a/pages/ox_lib/Modules/CreateObject/Client.mdx b/pages/ox_lib/Modules/CreateObject/Client.mdx new file mode 100644 index 000000000..58d038784 --- /dev/null +++ b/pages/ox_lib/Modules/CreateObject/Client.mdx @@ -0,0 +1,112 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; + +# Client + +Spawn an object client-side. Loads the model, calls `CreateObject`, then releases the model. + +## lib.createObject + + + + + + ```lua + lib.createObject(model, coords, isNetwork, netMissionEntity, doorFlag, heading, rotation) + ``` + + + ```ts + import lib from '@overextended/ox_lib/client' + + lib.createObject(model, coords, isNetwork, netMissionEntity, doorFlag, heading, rotation) + ``` + + + + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the object at. + - isNetwork?: `boolean` + - Create as a network object. If `false`, the object exists only locally. + - Default: `false` + - netMissionEntity?: `boolean` + - Pin the object to the script host in the R\* network model. + - Default: `false` + - doorFlag?: `boolean` + - Set `true` to spawn door models in network mode. + - Default: `false` + - heading?: `number` + - Heading of the object, in degrees. + - rotation?: `vector3` + - Rotation of the object. If omitted the object spawns with no rotation. + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the object could not be created. + + ```lua + local object = lib.createObject( + 'prop_chair_01a', + GetEntityCoords(cache.ped), + true, true, false, + GetEntityHeading(cache.ped) + ) + ``` + + + + + + ```lua + lib.createObject(model, coords, isNetwork, bScriptHostObj, dynamic, p7, p8, heading, rotation) + ``` + + + ```ts + import lib from '@overextended/ox_lib/client' + + lib.createObject(model, coords, isNetwork, bScriptHostObj, dynamic, p7, p8, heading, rotation) + ``` + + + + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the object at. + - isNetwork?: `boolean` + - Create as a network object. If `false`, the object exists only locally. + - Default: `false` + - bScriptHostObj?: `boolean` + - Pin the object to the script host in the R\* network model. + - Default: `false` + - dynamic?: `boolean` + - Whether the object should be dynamic (physics-driven, can move). + - Default: `false` + - p7?: `boolean` + - Undocumented RedM parameter forwarded to the native. + - Default: `false` + - p8?: `boolean` + - Undocumented RedM parameter forwarded to the native. + - Default: `false` + - heading?: `number` + - Heading of the object, in degrees. + - rotation?: `vector3` + - Rotation of the object. If omitted the object spawns with no rotation. + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the object could not be created. + + ```lua + local object = lib.createObject( + 'p_amb_tent01x', + GetEntityCoords(cache.ped), + true, true, false, + nil, nil, + GetEntityHeading(cache.ped) + ) + ``` + + diff --git a/pages/ox_lib/Modules/CreateObject/Server.mdx b/pages/ox_lib/Modules/CreateObject/Server.mdx new file mode 100644 index 000000000..21fbcb138 --- /dev/null +++ b/pages/ox_lib/Modules/CreateObject/Server.mdx @@ -0,0 +1,60 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; + +# Server + +Spawn an object server-side. The helper waits for the entity to materialize and applies +an orphan mode so the entity is not cleaned up automatically. + +## lib.createObject + + + + ```lua + lib.createObject(model, coords, doorFlag, heading, rotation, orphanMode) + ``` + + + ```ts + import lib from '@overextended/ox_lib/server' + + lib.createObject(model, coords, doorFlag, heading, rotation, orphanMode) + ``` + + + +- model: `string | number` + - Model name or precomputed hash. +- coords: `vector3` + - World coordinate to spawn the object at. +- doorFlag?: `boolean` + - Set `true` to spawn door models in network mode. + - Default: `false` +- heading?: `number` + - Heading of the object, in degrees. +- rotation?: `vector3` + - Rotation of the object. If omitted the object spawns with no rotation. +- orphanMode?: `EntityOrphanMode` + - Server-side cleanup behavior applied via `SetEntityOrphanMode`. + - Default: `2` (KeepEntity) + +**Returns:** +- entity: `number` + - Entity handle, or `0` if the object could not be created. + +### EntityOrphanMode + +``` +0 DeleteWhenNotRelevant — default game behavior; deletes when no player is relevant. +1 DeleteOnOwnerDisconnect — deletes when the original owner disconnects. +2 KeepEntity — never deleted by server relevancy checks. +``` + +```lua +local playerPed = GetPlayerPed(source) +local object = lib.createObject( + 'prop_chair_01a', + GetEntityCoords(playerPed), + false, + GetEntityHeading(playerPed) +) +``` diff --git a/pages/ox_lib/Modules/CreatePed/Client.mdx b/pages/ox_lib/Modules/CreatePed/Client.mdx new file mode 100644 index 000000000..713f23eef --- /dev/null +++ b/pages/ox_lib/Modules/CreatePed/Client.mdx @@ -0,0 +1,104 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; + +# Client + +Spawn a ped client-side. Loads the model, calls `CreatePed`, then releases the model. + +## lib.createPed + + + + + + ```lua + lib.createPed(pedType, model, coords, heading, isNetwork, bScriptHostPed) + ``` + + + ```ts + import lib from '@overextended/ox_lib/client' + + lib.createPed(pedType, model, coords, heading, isNetwork, bScriptHostPed) + ``` + + + + - pedType: `number` + - AI behavior type. `4` = CIVMALE, `5` = CIVFEMALE, etc. + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the ped at. + - heading?: `number` + - Heading of the ped, in degrees. + - isNetwork?: `boolean` + - Create as a network ped. If `false`, the ped exists only locally. + - Default: `false` + - bScriptHostPed?: `boolean` + - Pin the ped to the script host in the R\* network model. + - Default: `false` + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the ped could not be created. + + ```lua + local ped = lib.createPed( + 4, + 'a_m_y_business_01', + GetEntityCoords(cache.ped), + GetEntityHeading(cache.ped), + true, true + ) + ``` + + + + + + ```lua + lib.createPed(model, coords, heading, isNetwork, bScriptHostPed, p7, p8) + ``` + + + ```ts + import lib from '@overextended/ox_lib/client' + + lib.createPed(model, coords, heading, isNetwork, bScriptHostPed, p7, p8) + ``` + + + + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the ped at. + - heading?: `number` + - Heading of the ped, in degrees. + - isNetwork?: `boolean` + - Create as a network ped. If `false`, the ped exists only locally. + - Default: `false` + - bScriptHostPed?: `boolean` + - Pin the ped to the script host in the R\* network model. + - Default: `false` + - p7?: `boolean` + - Undocumented RedM parameter forwarded to the native. + - Default: `false` + - p8?: `boolean` + - Undocumented RedM parameter forwarded to the native. + - Default: `false` + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the ped could not be created. + + ```lua + local ped = lib.createPed( + 'mp_male', + GetEntityCoords(cache.ped), + GetEntityHeading(cache.ped), + true, true + ) + ``` + + diff --git a/pages/ox_lib/Modules/CreatePed/Server.mdx b/pages/ox_lib/Modules/CreatePed/Server.mdx new file mode 100644 index 000000000..a28c4a699 --- /dev/null +++ b/pages/ox_lib/Modules/CreatePed/Server.mdx @@ -0,0 +1,57 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; + +# Server + +Spawn a ped server-side. The helper waits for the entity to materialize and applies an +orphan mode so the ped is not cleaned up automatically. + +## lib.createPed + + + + ```lua + lib.createPed(pedType, model, coords, heading, orphanMode) + ``` + + + ```ts + import lib from '@overextended/ox_lib/server' + + lib.createPed(pedType, model, coords, heading, orphanMode) + ``` + + + +- pedType: `number` + - AI behavior type. `4` = CIVMALE, `5` = CIVFEMALE, etc. Ignored on RedM (`Unused` per the native docs). +- model: `string | number` + - Model name or precomputed hash. +- coords: `vector3` + - World coordinate to spawn the ped at. +- heading?: `number` + - Heading of the ped, in degrees. +- orphanMode?: `EntityOrphanMode` + - Server-side cleanup behavior applied via `SetEntityOrphanMode`. + - Default: `2` (KeepEntity) + +**Returns:** +- entity: `number` + - Entity handle, or `0` if the ped could not be created. + +### EntityOrphanMode + +``` +0 DeleteWhenNotRelevant — default game behavior; deletes when no player is relevant. +1 DeleteOnOwnerDisconnect — deletes when the original owner disconnects. +2 KeepEntity — never deleted by server relevancy checks. +``` + +```lua +local playerPed = GetPlayerPed(source) +local ped = lib.createPed( + 4, + 'a_m_y_business_01', + GetEntityCoords(playerPed), + GetEntityHeading(playerPed) +) +``` diff --git a/pages/ox_lib/Modules/CreateVehicle/Client.mdx b/pages/ox_lib/Modules/CreateVehicle/Client.mdx new file mode 100644 index 000000000..7f4adabcc --- /dev/null +++ b/pages/ox_lib/Modules/CreateVehicle/Client.mdx @@ -0,0 +1,123 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; + +# Client + +Spawn a vehicle client-side. Loads the model, calls `CreateVehicle`, optionally warps +the local player into a seat, and applies vehicle properties. + +## lib.createVehicle + + + + + + ```lua + lib.createVehicle(model, coords, heading, isNetwork, netMissionEntity, seat, properties) + ``` + + + ```ts + import lib from '@overextended/ox_lib/client' + + lib.createVehicle(model, coords, heading, isNetwork, netMissionEntity, seat, properties) + ``` + + + + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the vehicle at. + - heading?: `number` + - Heading the vehicle should face, in degrees. + - isNetwork?: `boolean` + - Create as a network vehicle. If `false`, the vehicle exists only locally. + - Default: `false` + - netMissionEntity?: `boolean` + - Pin the vehicle to the script host in the R\* network model. + - Default: `false` + - seat?: `SeatPosition` + - Warps the local player into the specified seat after spawning. + - properties?: `table` + - Properties applied via [`lib.setVehicleProperties`](/ox_lib/Modules/VehicleProperties/Client#libsetvehicleproperties) + after spawning. + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the vehicle could not be created. + + ### SeatPosition + + ``` + -2 SF_ANY + -1 SF_FrontDriverSide + 0 SF_FrontPassengerSide + 1 SF_BackDriverSide + 2 SF_BackPassengerSide + 3 SF_AltFrontDriverSide + 4 SF_AltFrontPassengerSide + 5 SF_AltBackDriverSide + 6 SF_AltBackPassengerSide + ``` + + ```lua + local vehicle = lib.createVehicle( + 'adder', + GetEntityCoords(cache.ped), + GetEntityHeading(cache.ped), + true, true, + -1 + ) + ``` + + + + + + ```lua + lib.createVehicle(model, coords, heading, isNetwork, bScriptHostVeh, bDontAutoCreateDraftAnimals, p8) + ``` + + + ```ts + import lib from '@overextended/ox_lib/client' + + lib.createVehicle(model, coords, heading, isNetwork, bScriptHostVeh, bDontAutoCreateDraftAnimals, p8) + ``` + + + + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the vehicle at. + - heading?: `number` + - Heading the vehicle should face, in degrees. + - isNetwork?: `boolean` + - Create as a network vehicle. If `false`, the vehicle exists only locally. + - Default: `false` + - bScriptHostVeh?: `boolean` + - Pin the vehicle to the script host in the R\* network model. + - Default: `false` + - bDontAutoCreateDraftAnimals?: `boolean` + - Skip automatic creation of draft animals (e.g. the horses harnessed to a wagon). + - Default: `false` + - p8?: `boolean` + - Undocumented RedM parameter forwarded to the native. + - Default: `false` + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the vehicle could not be created. + + ```lua + local wagon = lib.createVehicle( + 'wagon04x', + GetEntityCoords(cache.ped), + GetEntityHeading(cache.ped), + true, true, + true + ) + ``` + + diff --git a/pages/ox_lib/Modules/CreateVehicle/Server.mdx b/pages/ox_lib/Modules/CreateVehicle/Server.mdx new file mode 100644 index 000000000..410dada59 --- /dev/null +++ b/pages/ox_lib/Modules/CreateVehicle/Server.mdx @@ -0,0 +1,127 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; +import { Callout } from 'nextra/components'; + +# Server + +Spawn a vehicle server-side. The helper waits for the entity to materialize and applies +an orphan mode so the vehicle is not cleaned up automatically. + +## lib.createVehicle + + + + Calls `CreateVehicleServerSetter` with the supplied `vehicleType`. Optionally + applies vehicle properties and warps a player into a seat after spawning. + + + The `vehicleType` argument is forwarded to `CreateVehicleServerSetter` and must + match the actual category of the model — passing the wrong type may prevent the + vehicle from spawning correctly. + + + + + ```lua + lib.createVehicle(model, coords, heading, vehicleType, properties, seat, orphanMode) + ``` + + + ```ts + import lib from '@overextended/ox_lib/server' + + lib.createVehicle(model, coords, heading, vehicleType, properties, seat, orphanMode) + ``` + + + + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the vehicle at. + - heading?: `number` + - Heading the vehicle should face, in degrees. + - vehicleType?: `VehicleType` + - Category passed to `CreateVehicleServerSetter`. + - Default: `'automobile'` + - properties?: `table` + - Properties applied via [`lib.setVehicleProperties`](/ox_lib/Modules/VehicleProperties/Client#libsetvehicleproperties) + after spawning. + - seat?: `{ source: number, seat: SeatPosition }` + - Warps the player identified by `source` into the specified seat after spawning. + - orphanMode?: `EntityOrphanMode` + - Server-side cleanup behavior applied via `SetEntityOrphanMode`. + - Default: `2` (KeepEntity) + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the vehicle could not be created. + + ### VehicleType + + ``` + 'automobile' + 'bike' + 'boat' + 'heli' + 'plane' + 'submarine' + 'trailer' + 'train' + ``` + + ```lua + local playerPed = GetPlayerPed(source) + local vehicle = lib.createVehicle( + 'adder', + GetEntityCoords(playerPed), + GetEntityHeading(playerPed), + 'automobile' + ) + ``` + + + + Calls the CFX `CREATE_VEHICLE` server native + (`modelHash, x, y, z, heading, isNetwork, netMissionEntity`). The wrapper + always pins the entity to the script host. `vehicleType`, `properties`, and + `seat` from the FiveM wrapper are not available on RedM. + + + + ```lua + lib.createVehicle(model, coords, heading, orphanMode) + ``` + + + ```ts + import lib from '@overextended/ox_lib/server' + + lib.createVehicle(model, coords, heading, orphanMode) + ``` + + + + - model: `string | number` + - Model name or precomputed hash. + - coords: `vector3` + - World coordinate to spawn the vehicle at. + - heading?: `number` + - Heading the vehicle should face, in degrees. + - orphanMode?: `EntityOrphanMode` + - Server-side cleanup behavior applied via `SetEntityOrphanMode`. + - Default: `2` (KeepEntity) + + **Returns:** + - entity: `number` + - Entity handle, or `0` if the vehicle could not be created. + + ```lua + local playerPed = GetPlayerPed(source) + local wagon = lib.createVehicle( + 'wagon04x', + GetEntityCoords(playerPed), + GetEntityHeading(playerPed) + ) + ``` + + diff --git a/pages/ox_lib/Modules/SpawnEntity/Client.mdx b/pages/ox_lib/Modules/SpawnEntity/Client.mdx new file mode 100644 index 000000000..3e2db309f --- /dev/null +++ b/pages/ox_lib/Modules/SpawnEntity/Client.mdx @@ -0,0 +1,46 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; +import { Callout } from 'nextra/components'; + +# Client + +Internal helper used by `lib.createObject`, `lib.createPed`, and `lib.createVehicle` to +load a model, run the provided spawner native, and release the model afterwards. + +## lib.spawnEntity + + + The model is automatically released with `SetModelAsNoLongerNeeded` after the entity is created. + + + + + ```lua + lib.spawnEntity(model, spawn, timeout) + ``` + + + ```ts + import lib from '@overextended/ox_lib/client' + + lib.spawnEntity(model, spawn, timeout) + ``` + + + +- model: `string | number` + - Model name or precomputed hash. +- spawn: `fun(modelHash: number): number` + - Native spawner, called once the model has loaded. Must return the created entity handle. +- timeout?: `number` + - Milliseconds to wait for the model to load. + - Default: `10000` + +**Returns:** +- entity: `number` + - Entity handle, or `0` if the entity could not be created. + +```lua +local object = lib.spawnEntity('prop_chair_01a', function(modelHash) + return CreateObject(modelHash, coords.x, coords.y, coords.z, true, true, false) +end) +``` diff --git a/pages/ox_lib/Modules/SpawnEntity/Server.mdx b/pages/ox_lib/Modules/SpawnEntity/Server.mdx new file mode 100644 index 000000000..0bec0a76a --- /dev/null +++ b/pages/ox_lib/Modules/SpawnEntity/Server.mdx @@ -0,0 +1,60 @@ +import { Tabs, Tab } from 'nextra-theme-docs'; +import { Callout } from 'nextra/components'; + +# Server + +Internal helper used by `lib.createObject`, `lib.createPed`, and `lib.createVehicle` to +spawn a server-side entity, wait for it to materialize, and apply an orphan mode. + +## lib.spawnEntity + + + Spawning may lag in high-population sessions. The helper waits up to `timeout` ms + for `DoesEntityExist` to return true before returning `0`. + + + + + ```lua + lib.spawnEntity(assetType, model, spawn, orphanMode, timeout) + ``` + + + ```ts + import lib from '@overextended/ox_lib/server' + + lib.spawnEntity(assetType, model, spawn, orphanMode, timeout) + ``` + + + +- assetType: `string` + - Label used in error messages, e.g. `'object'`, `'ped'`, `'vehicle'`. +- model: `string | number` + - Model name or precomputed hash. +- spawn: `fun(modelHash: number): number` + - Native spawner, called with the resolved hash. Must return the created entity handle. +- orphanMode?: `EntityOrphanMode` + - Server-side cleanup behavior applied via `SetEntityOrphanMode`. + - Default: `2` (KeepEntity) +- timeout?: `number` + - Milliseconds to wait for the entity to exist. + - Default: `5000` + +**Returns:** +- entity: `number` + - Entity handle, or `0` if the entity could not be created or did not materialize in time. + +### EntityOrphanMode + +``` +0 DeleteWhenNotRelevant — default game behavior; deletes when no player is relevant. +1 DeleteOnOwnerDisconnect — deletes when the original owner disconnects. +2 KeepEntity — never deleted by server relevancy checks. +``` + +```lua +local object = lib.spawnEntity('object', 'prop_chair_01a', function(modelHash) + return CreateObject(modelHash, coords.x, coords.y, coords.z, true, true, false) +end) +```