[Release][C#] VStancer

[Neos7]

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

1. Download the zip file from the release page
2. Extract the content of the zip to the resources folder of your server (it should be a folder named vstancer)
3. 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

• VStancer by ikt
• FiveM by CitizenFX
• MenuAPI by Vespura
• GTADrifting members
• All the testers

[Mumin_Khan]

Some pic would be Nice…

[Envious]

Besides making me cringe at the possibility of horribly modified cars at least the people on my server would enjoy this.

[Neos7]

@Mumin_Khan i’ve added a video which shows the experimental version.
And I suggest to use the experimental version

[Neos7]

Now the server also sends the current settings on ClientReady event

[GMBSxHAPPY]

How do I actually use this mod i downloaded the experimental version and f7 does nothing

[Neos7]

@GMBSxHAPPY If you read the description, the F7 is a vehicle spawner just included (and required) in the master version.
The experimental version instead just needs you to be in any vehicle and press F6 to open the menu.

[GMBSxHAPPY]

thank you! also is it possible to add in a way to lift vehicles with this?

[Neos7]

@GMBSxHAPPY I will add that feature when FiveM devs add the ExtraNative to the API

[GMBSxHAPPY]

AWSOME! I can’t wait to lift my trucks and make them look super aggresive

[Neos7]

Updated NativeUI to the latest version available, moved the menu on the top-right corner of the screen so it doesn’t overlap the chat.

[Neos7]

KNOWN BUGS

• If you enter a new vehicle without resetting the previous one, it will break the default values of the previous, same thing may happen if you enter a vehicle which was previously edited by someone else
• UI might show incorrectly on resolutions with aspect ratio different than 16:9 (I will try to replace NativeUI)

Fixed these previous known bugs.
Now the script resets the previous vehicle when you enter a new one.
Now the script won’t refresh anymore the local unsynched vehicle if it is resetted or hasn’t been edited.

[TibyPork123]

Can you please add the option to lower the car and modify the wheel size?

[Neos7]

I’ve already replied above, these features will be added when FiveM devs add the extranatives

[Hi_Im_Champa]

How to install? Where do I put the files?

[Neos7]

it’s a server resource, you need to stream it from a server and will be available to each player when in a car by pressing F6.

Added a beta version of this script, it’s called “livesync” and it features auto synchronization if required.
Additional fixes and changes will be listed once this version will be close to be complete.

[CrackHead]

Hello! Nice script! Is it possible to change the F6 KEY TO ANOTHER ONE?

[Neos7]

Yes
you need to change this line

if (IsControlJustPressed(1, 167) || IsDisabledControlJustPressed(1, 167)) // TOGGLE MENU VISIBLE
wheelsEditorMenu.Visible = !wheelsEditorMenu.Visible;

Replace the 167 with the number of another Control, you can find them here
https://wiki.fivem.net/wiki/Controls

[Flatracer]

You could add a config file, so the end-users don’t have to compile it themselves just for the opening key etc.

[Neos7]

Good idea, I might add it