VStancer

Master	Development

Description

An attempt to use the features from ikt's VStancer as resource for FiveM servers to synchronize the edited vehicles with all the players. It is built using FiveM API and MenuAPI.

When a client edits a vehicle, it will be automatically synchronized with all the players. If a vehicle is reset to the default values it will stop from being synchronized. The synchronization is made using decorators.

The default key to open the menu is F6

Glossary

Track Width: It's the X offset of the vehicle's wheels bones in the entity local coords system. Because wheels model are rotated it means to have a positivie Track Width you have to assign a negative value.
Camber: It's the Y rotation of the vehicle's wheels bones in the entity local coords system.
Wheel Mod: It refers to a custom wheel you can apply on a vehicle from in-game tuning features. Since this term can create ambiguity with custom assets mods (wheel modifications), we will refers to these as "tuning wheels" and to game modifications as "wheel mods"

Features of the script

Edit Track Width of vehicles
Edit Camber of vehicles
Edit Tuning Wheel Size of vehicles (Requires a tuning wheel to be installed on the vehicle)
Edit Tuning Wheel Width of vehicles (Requires a tuning wheel to be installed on the vehicle)
Manage presets

Note

When a preset is created for the first time, it will use the current wheels' state as default. So in case of damaged vehicles (e.g. deformed wheels), the default values might be incorrect. Workaround: If a vehicle is damaged, be sure to fix it before to enter it and create a preset. (e.g. reset preset, fix the vehicle, exit the vehicle and enter again)

Client Commands

vstancer_preset: Prints the preset of the current vehicle
vstancer_decorators: Prints the info about decorators on the current vehicle
vstancer_decorators <int>: Prints the info about decorators on the vehicle with the specified int as local handle
vstancer_print: Prints the list of all the vehicles with any decorator of this script
vstancer_range <float>: Sets the specified float as the maximum distance used to refresh wheels of the vehicles with decorators
vstancer_debug <bool>: Enables or disables the logs to be printed in the console
vstancer: Toggles the menu, this command has to be enabled in the config

Config

Debug: Enables the debug mode, which prints some logs in the console
DisableMenu: Allows to disable the menu in case you want to allow editing in your own menu using the provided API
ExposeCommand: Enables the /vstancer command to toggle the menu
ExposeEvent: Enable the "vstancer:toggleMenu" event to toggle the menu
ScriptRange: The max distance within which each client refreshes edited vehicles
Timer: The value in milliseconds used by each client to do some specific timed tasks
ToggleMenuControl:The Control to toggle the Menu, default is 167 which is F6 (check the controls list)
FloatStep: The step used to increase and decrease a value
EnableWheelMod: Enables the script to edit wheel size and width of tuning wheels
EnableClientPresets: Enables the script to manage clients' presets
WheelLimits:
- FrontTrackWidth: The max value you can increase or decrease the front Track Width from its default value
- RearTrackWidth: The max value you can increase or decrease the rear Track Width from its default value
- FrontCamber: The max value you can increase or decrease the front Camber from its default value
- RearCamber: The max value you can increase or decrease the rear Camber from its default value
WheelModLimits:
- WheelSize: The max value you can increase or decrease the size of tuning wheels from its default value
- WheelWidth: The max value you can increase or decrease the width of tuning wheels from its default value

Exports

The script exposes some API to manage the main features from other scripts:

bool SetWheelPreset(int vehicle, float frontTrackWidth, float frontCamber, float rearTrackWidth, float rearCamber);
float[] GetWheelPreset(int vehicle);
bool ResetWheelPreset(int vehicle);
float[] GetFrontCamber(int vehicle);
float[] GetRearCamber(int vehicle);
float[] GetFrontTrackWidth(int vehicle);
float[] GetRearTrackWidth(int vehicle);
bool SetFrontCamber(int vehicle, float value);
bool SetRearCamber(int vehicle, float value);
bool SetFrontTrackWidth(int vehicle, float value);
bool SetRearTrackWidth(int vehicle, float value);
bool SaveClientPreset(string presetName, int vehicle);
bool LoadClientPreset(string presetName, int vehicle);
bool DeleteClientPreset(string presetName);
string[] GetClientPresetList();

NOTE Current API don't support editing of tuning wheel data (wheelSize and wheelWidth) yet.

Remember that API require the resource to be called exactly “vstancer”

API Usage

SetWheelPreset
- int vehicle: the handle of the vehicle entity
- float frontTrackWidth: the value you want to assign as front track width
- float frontCamber: the value you want to assign as front camber
- float rearTrackWidth: the value you want to assign as rear track width
- float rearCamber: the value you want to assign as rear camber
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].SetWheelPreset(vehicle, frontTrackWidth, frontCamber, rearTrackWidth, rearCamber);
```
Lua:
```
local result = exports["vstancer"]:SetWheelPreset(vehicle, frontTrackWidth, frontCamber, rearTrackWidth, rearCamber)
```
GetWheelPreset
- int vehicle: the handle of the vehicle entity
- float result: the array containing the oreset values in this order frontTrackWidth, frontCamber, rearTrackWidth, rearCamber.
Example

C#:
```
float[] result = Exports["vstancer"].GetWheelPreset(vehicle);
```
Lua:
```
local result = exports["vstancer"]:GetWheelPreset(vehicle);
```
ResetWheelPreset
- int vehicle: the handle of the vehicle entity
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].ResetWheelPreset(vehicle);
```
Lua:
```
local result = exports["vstancer"]:ResetWheelPreset(vehicle);
```
GetFrontCamber
- int vehicle: the handle of the vehicle entity
- float[] frontCamber: an array which contains the value as first element if the request has success, otherwise is empty
Example

C#:
```
float[] frontCamber = Exports["vstancer"].GetFrontCamber(vehicle);
```
Lua:
```
local frontCamber = exports["vstancer"]:GetFrontCamber(vehicle);
```
GetRearCamber
- int vehicle: the handle of the vehicle entity
- float[] rearCamber: an array which contains the value as first element if the request has success, otherwise is empty
Example

C#:
```
float[] rearCamber = Exports["vstancer"].GetRearCamber(vehicle);
```
Lua:
```
local rearCamber = exports["vstancer"]:GetRearCamber(vehicle);
```
GetFrontTrackWidth
- int vehicle: the handle of the vehicle entity
- float[] frontTrackWidth: an array which contains the value as first element if the request has success, otherwise is empty
Example

C#:
```
float[] frontTrackWidth = Exports["vstancer"].GetFrontTrackWidth(vehicle);
```
Lua:
```
local frontTrackWidth = exports["vstancer"]:GetFrontTrackWidth(vehicle);
```
GetRearTrackWidth
- int vehicle: the handle of the vehicle entity
- float[] rearTrackWidth: an array which contains the value as first element if the request has success, otherwise is empty
Example

C#:
```
float[] rearTrackWidth = Exports["vstancer"].GetRearTrackWidth(vehicle);
```
Lua:
```
local rearTrackWidth = exports["vstancer"]:GetRearTrackWidth(vehicle);
```
SetFrontCamber
- int vehicle: the handle of the vehicle entity
- float frontCamber: the value you want to assign as front camber
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].SetFrontCamber(vehicle, frontCamber);
```
Lua:
```
local result = exports["vstancer"]:SetFrontCamber(vehicle, frontCamber);
```
SetRearCamber
- int vehicle: the handle of the vehicle entity
- float rearCamber: the value you want to assign as rear camber
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].SetRearCamber(vehicle, rearCamber);
```
Lua:
```
local result = exports["vstancer"]:SetRearCamber(vehicle, rearCamber);
```
SetFrontTrackWidth
- int vehicle: the handle of the vehicle entity
- float frontTrackWidth: the value you want to assign as front track width
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].SetFrontTrackWidth(vehicle, frontTrackWidth);
```
Lua:
```
local result = exports["vstancer"]:SetFrontTrackWidth(vehicle, frontTrackWidth);
```
SetRearTrackWidth
- int vehicle: the handle of the vehicle entity
- float rearTrackWidth: the value you want to assign as rear track width
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].SetRearTrackWidth(vehicle, rearTrackWidth);
```
Lua:
```
local result = exports["vstancer"]:SetRearTrackWidth(vehicle, rearTrackWidth);
```
SaveClientPreset
- string presetName: the name you want to use for the saved preset
- int vehicle: the handle of the vehicle entity you want to save the preset from
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].SaveClientPreset(presetName, vehicle);
```
Lua:
```
local result = exports["vstancer"]:SaveClientPreset(presetName, vehicle);
```
LoadClientPreset
- string presetName: the name of the preset you want to load
- int vehicle: the handle of the vehicle entity you want to load the preset on
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].LoadClientPreset(presetName, vehicle);
```
Lua:
```
local result = exports["vstancer"]:LoadClientPreset(presetName, vehicle);
```
DeleteClientPreset
- string presetName: the name of the preset you want to delete
- bool result: returns true if the action successfully executed otherwise false
Example

C#:
```
bool result = Exports["vstancer"].DeleteClientPreset(presetName);
```
Lua:
```
local result = exports["vstancer"]:DeleteClientPreset(presetName);
```

GetClientPresetList

string[] presetList: the list of all the presets saved locally

Example

C#:

string[] presetList = Exports["vstancer"].GetClientPresetList();

Lua:

local presetList = exports["vstancer"]:GetClientPresetList();

Source Download I am open to any kind of feedback. Report suggestions and bugs you find.

Build

Open the postbuild.bat and edit the path of the resource folder. If in Debug configuration, the post build event will copy the following files to the specified path: the built assembly of the script, the config.json, the fxmanifest.lua.

Requirements

The script uses MenuAPI by Vespura to render the UI, ~~it uses FiveM built-in resource dependency, so the script will only work if MenuAPI resource is found and running~~ and comes already with a built assembly so that it's ready to use.

Installation

Download the zip file from the release page
Extract the content of the zip to the resources folder of your server (it should be a folder named vstancer)
Enable the resource in your server config (start vstancer)

Todo

Add API for wheel mod data
Update local presets API to support wheel mod data
Add limits check for API
Add limits check for preset loading
Workaround wheel mod data being reset after any tuning component is changed
Clean duplicated code
API shouldn't allow to edit vehicles other players are driving

Roadmap

Once FiveM exposes extra-natives to edit SubHandlingData fields at runtime, the script will allow to edit XYZ rotation using the native handling fields of CCarHandlingData such as fToeFront, fToeRear, fCamberFront, fCamberRear, fCastor. (This will also improve a lot performances as such values won't need to be set each tick)

Credits

Support

If you would like to support my work, you can through:

Patreon

EGUltraTM/fivem-vstancer