Force Field

Applies a gravitational planet effect around the player vehicle, pushing or pulling other vehicles. Toggled via radial menu. Disabled automatically during career mode.

Public API

Function	Signature	Returns	Description
`M.activate`	`()`	`nil`	Enables the force field; shows UI message with mode (attraction/repulsion)
`M.deactivate`	`(silent?)`	`nil`	Disables force field; clears all vehicle planets; shows message unless silent
`M.toggleActive`	`()`	`nil`	Toggles between active/inactive
`M.isActive`	`()`	`boolean`	Returns current state
`M.setForceMultiplier`	`(factor)`	`nil`	Sets force direction/strength (positive=repulsion, negative=attraction)
`M.getForceMultiplier`	`()`	`number`	Returns current multiplier
`M.onCareerActive`	`(enabled)`	-	Callback for CareerActive event
`M.onClientEndMission`	`()`	-	Callback for ClientEndMission event
`M.onDeserialized`	`()`	-	Callback for Deserialized event
`M.onSerialize`	`()`	-	Callback for Serialize event
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`	-	Callback for Update event
`M.onVehicleSwitched`	`()`	-	Callback for VehicleSwitched event

Hooks

Hook	Description
`onUpdate`	Sends planet commands to all non-player vehicles every 0.05s
`onClientEndMission`	Deactivates on mission end
`onVehicleSwitched`	Deactivates on vehicle switch
`onSerialize`	Deactivates before serialize
`onCareerActive`	Deactivates when career enables

Internals

Planet Physics

Uses obj:setPlanets({x, y, z, radius, mass}) vlua command. The planet is centered on the player vehicle's OBB center with:

planetRadius = 5
mass = -60000000000000 (base, scaled by vehicle size and multiplier)
vehicleSizeFactor = longestBBHalfExtent / 3

Update Throttling

Only sends planet commands every 0.05s (20Hz) to reduce overhead. Iterates all be objects except the player vehicle.

Force Direction

forceMultiplier > 0 → repulsion (default=1)
forceMultiplier < 0 → attraction
UI message reflects mode via translation keys

How It Works

Player activates via radial menu → activate()
Every 0.05s, computes planet position from player OBB center
Sends obj:setPlanets(...) to every other vehicle
On deactivate, sends empty planets obj:setPlanets({}) to all vehicles

Usage Example

-- Toggle from radial menu
gameplay_forceField.toggleActive()

-- Switch to attraction mode
gameplay_forceField.setForceMultiplier(-1)
gameplay_forceField.activate()

Public API

Function	Signature	Returns	Description
`M.activate`	`()`	`nil`	Enables the force field; shows UI message with mode (attraction/repulsion)
`M.deactivate`	`(silent?)`	`nil`	Disables force field; clears all vehicle planets; shows message unless silent
`M.toggleActive`	`()`	`nil`	Toggles between active/inactive
`M.isActive`	`()`	`boolean`	Returns current state
`M.setForceMultiplier`	`(factor)`	`nil`	Sets force direction/strength (positive=repulsion, negative=attraction)
`M.getForceMultiplier`	`()`	`number`	Returns current multiplier
`M.onCareerActive`	`(enabled)`	-	Callback for CareerActive event
`M.onClientEndMission`	`()`	-	Callback for ClientEndMission event
`M.onDeserialized`	`()`	-	Callback for Deserialized event
`M.onSerialize`	`()`	-	Callback for Serialize event
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`	-	Callback for Update event
`M.onVehicleSwitched`	`()`	-	Callback for VehicleSwitched event

Hooks

Hook	Description
`onUpdate`	Sends planet commands to all non-player vehicles every 0.05s
`onClientEndMission`	Deactivates on mission end
`onVehicleSwitched`	Deactivates on vehicle switch
`onSerialize`	Deactivates before serialize
`onCareerActive`	Deactivates when career enables

Internals

Planet Physics

Uses obj:setPlanets({x, y, z, radius, mass}) vlua command. The planet is centered on the player vehicle's OBB center with:

planetRadius = 5
mass = -60000000000000 (base, scaled by vehicle size and multiplier)
vehicleSizeFactor = longestBBHalfExtent / 3

Update Throttling

Only sends planet commands every 0.05s (20Hz) to reduce overhead. Iterates all be objects except the player vehicle.

Force Direction

forceMultiplier > 0 → repulsion (default=1)
forceMultiplier < 0 → attraction
UI message reflects mode via translation keys

How It Works

Player activates via radial menu → activate()
Every 0.05s, computes planet position from player OBB center
Sends obj:setPlanets(...) to every other vehicle
On deactivate, sends empty planets obj:setPlanets({}) to all vehicles

Usage Example

-- Toggle from radial menu
gameplay_forceField.toggleActive()

-- Switch to attraction mode
gameplay_forceField.setForceMultiplier(-1)
gameplay_forceField.activate()

Force Field

Public API

Hooks

Internals

Planet Physics

Update Throttling

Force Direction

How It Works

Usage Example

See Also

On this page

Force Field

Public API

Hooks

Internals

Planet Physics

Update Throttling

Force Direction

How It Works

Usage Example

See Also

On this page