API v1.0

FivePD API Update 1.0

FivePD v1.1 comes with a lot of new,exciting features as well as the new API. In v1.1, both the old (0.6.4) and new (1.0) API will be usable, however, 0.6.4 will be deprecated in the next versions of FivePD. Since this API is not only for callouts, CalloutAPI.net.dll has been renamed to FivePD.net.dll ( you need to reference this file if you want to interact with FivePD ).

(The wiki will be reorganized soon)

FivePD v1.1 now supports plugins!

New features:

Important changes (PR #44)
Creating a FivePD plugin
Converting old callouts

Utilities (namespace)

Vector3Extensions
Around

Callout

ShowDialog
ShowNetworkedNotification
UpdateData
CalloutPropertiesAttribute

Events

OnCalloutReceived
OnCalloutAccepted
OnCalloutCompleted
OnDutyStatusChange
OnServiceCalled

Utilities (class)

GetClosestPed
ForceCallout
GetCurrentCallout
GetCallouts
RequestService
CancelService
GetVehicleData
SetVehicleData
GetPedData
SetPedData
GetPlayerData
ExcludeVehicleFromTrafficStop

Renamed

We had to rename a few methods, making it more logical and easier to understand. These names will now reflect the real purpose of each method.

• OnAccept to InitBlip
• Init to OnAccept
• InitBase to InitInfo

However, the logic behind these methods have not changed.

Utility classes

• Vector3Extensions (Thanks to LukeD!) - Extensions
• WorldZone (Thanks to LukeD!)

Examples: soon

Callout class

In v1.0, you can't specify the probability of your callout, but instead, server owners can change it in the callout config file (if you don't provide a config file with your callout, default config will be used. Read more about callout config here here. ).

New features:

ShowDialog

Displays a networked dialog message for every player in a specific radius.

Params:

• text <string>
  • The message that you want to display.
• duration <int>
  • Display time ( in ms, 1000 ms = 1s )
• radius <float>
  • Display radius

Example:

The following code displays 'Hello!' in a 15f radius for 5 seconds ( 5000 ms ).

ShowDialog("Hello!",5000,15f);

ShowNetworkedNotification

Displays a networked notification message for every player in a specific radius.

Params:

• text <string>
  • The message that you want to display.
• textureDict <string>
  • Texture dictionary
• textureName <string>
  • Texture name
• sender <string>
  • Sender
• subject <string>
  • Subject
• radius <float>
  • Display radius

Example:

The following code displays a notification in a 15f radius.

ShowNetworkedNotification("Hello!","CHAR_CALL911","CHAR_CALL911","Sender","Subject",15f);

UpdateData

Updates the following data in the computer (and in the Dispatch container):

• ShortName
• ResponseCode
• Description
• Location (based on coordinates)

To change the values, just update these fields in your class and call the UpdateData() method.
By calling UpdateData(), the computer and callout notification will display the latest info of your callout.

If you pass a string (optional) to UpdateData, the location will be changed to that string, so you can add custom text aswell.

Example (without custom location):

// call UpdateData() somewhere in your code
...
this.ShortName = "New name!";
this.ResponseCode = 1;
this.Description = "New description!";
this.Location = new Vector3(x,y,z);
  
UpdateData();
...

Example (with custom location):

UpdateData("My location!");

CalloutPropertiesAttribute

As it was mentioned mentioned before, Probability has been moved to config.json.

Events class

In v1.0, you can subscribe to FivePD events. These events can be used after the script has loaded (FivePD).
Note that these events are independent and don't require you to use it in callouts (so you can create addon scripts with FivePD events).

OnCalloutReceived

Raised when the player receives a callout.
Passed:

• callout <Callout>
• The callout that the player has received

Example:

...
using CitizenFX.Core;
using FivePD.API;

class MyScript : BaseScript
{
  public MyScript()
  {
    Events.OnCalloutReceived += OnCalloutReceived;
  }
  public async Task OnCalloutReceived(FivePD.API.Callout callout)
  {
    ...
  }
}

OnCalloutAccepted

Raised when the player accepts a callout.
Passed:

• callout <Callout>
• The callout that the player has accepted

Example:

...
using CitizenFX.Core;
using FivePD.API;

class MyScript : BaseScript
{
  public MyScript()
  {
    Events.OnCalloutAccepted += OnCalloutAccepted;
  }
  public async Task OnCalloutAccepted(FivePD.API.Callout callout)
  {
    ...
  }
}

OnCalloutCompleted

Raised when the player completes a callout.
Passed:

• callout <Callout>
• The callout that the player has completed

Example:

...
using CitizenFX.Core;
using FivePD.API;

class MyScript : BaseScript
{
  public MyScript()
  {
    Events.OnCalloutCompleted += OnCalloutCompleted;
  }
  public async Task OnCalloutCompleted(FivePD.API.Callout callout)
  {
    ...
  }
}

OnDutyStatusChange

Raised when the player goes on/off duty.
Params: onDuty <bool> (true = on, false = off)

Example:

...
using CitizenFX.Core;
using FivePD.API;

class MyScript : BaseScript
{
  public MyScript()
  {
    Events.OnDutyStatusChange += OnDutyChange;
  }
  public async Task OnDutyChange(bool onDuty)
  {
    if(onDuty)
    {
      // the player went on duty
      ...
    }
    else
    {
      // the player went off duty
      ...
    }
  }
}

OnServiceCalled

Raised when the player requests a service.
Params: service <enum>

Services:

• Ambulance
• AirAmbulance
• FireDept
• Coroner
• AnimalControl
• TowTruck
• Mechanic
• PrisonTransport

Example:

...
using CitizenFX.Core;
using FivePD.API;

class MyScript : BaseScript
{
  public MyScript()
  {
    Events.OnServiceCalled += OnServiceCalled;
  }
  // The `Utilities` class contains the Services enum (available services)
  public async Task OnServiceCalled(Utilities.Services service)
  {
    ...
  }
}

Utilities class

The Utilities class provides you utility methods that can be used not only in callouts, but in individual scripts aswell. So in other words, you can make plugins for FivePD.

GetClosestPed

Returns the closest ped relative to the given ped.

Example: To get the closest ped to the player:

Ped closest = GetClosestPed(Game.PlayerPed);

ForceCallout

Force a FivePD callout by its GUID or name.

If no callout could be forced, an error message will be printed in the console.

Note: If there are multiple callouts with the same name, the first appearance (in the callouts collection) will be forced.

Example:

ForceCallout("a6f854c1-371a-4b2b-93c5-d99989552898"); // Forces a callout with the given GUID
...
ForceCallout("Mugging"); // Forces the "Mugging" callout

GetCurrentCallout

Returns the current ongoing callout. (FivePD.API.Callout)

Example:

...
FivePD.API.Callout callout = GetCurrentCallout();

GetCallouts

Returns a List<string> containing every enabled callout name.

Example:

...
List<string> calloutNames = GetCallouts();

RequestService

Requests a FivePD service to a given position.

You can only request the following services:

• Ambulance
• AirAmbulance
• FireDept
• Coroner
• AnimalControl

Example:

To request an ambulance at x = 0, y = 0, z = 0 position:

RequestService(Services.Ambulance,new Vector3(0,0,0));

CancelService

Cancels the last requested service.

Example:

CancelService(Services.Ambulance); // Cancels the last requested Ambulance

GetVehicleData

Returns the following data of the given vehicle (with NetworkId)

• LicensePlate <string>
• Flag <string> (eg. "Stolen")
• OwnerNetworkID <int>
• OwnerFirstname <string>
• OwnerLastname <string>
• Items <List<dynamic>>
• An item object contains:
  • Name <string>
  • IsIllegal <bool>
• Insurance <bool>
• Registration <bool>
• VehicleColor <string>
• VehicleName <string>
• ID <int> (networkId)

Example:

Vehicle vehicle;
...
dynamic data = await GetVehicleData(vehicle.NetworkId);

To get the license plate:

string licensePlate = data.LicensePlate;

To get the flag:

string flag = data.Flag;

To get the owner's network id

int ownerNetworkID = data.OwnerNetworkID;

To get the owner's firstname:

string ownerFirstname = data.OwnerFirstname;

To get the owner's lastname:

string ownerLastname = data.OwnerLastname;

To get the insurance status: (true = value, false = invalid)

bool insurance = data.Insurance;

To get the registration status: (true = value, false = invalid)

bool registration = data.Registration;

To get the color of the vehicle:

string color = data.VehicleColor;

To get the name of the vehicle:

string vehicleName = data.VehicleName;

To get the id of the vehicle: (networkID)

int vehicleID = data.ID;

To get the items:

List<dynamic> items = data.Items;

foreach (var elem in items)
{
	string itemName = elem.Name;
	bool isIllegal = elem.IsIllegal;
}

SetVehicleData

Params:

• networkID <int>
  • NetworkID of the vehicle
• vehicleData <ExpandoObject>
  • Vehicle data

Optional

• insurance <bool>
• registration <bool>
• items <object>

First, you need to create a new ExpandoObject:

dynamic vehicleData = new ExpandoObject();

To set insurance status:

vehicleData.insurance = false;

To set registration status:

vehicleData.registration = false;

To set items:

List<object> items = new List<object>();

object phone = new {
	Name = "Phone",
	IsIllegal = false
};

items.Add(phone);
vehicleData.items = items;

And then call the SetVehicleData method:

SetVehicleData(vehicle.NetworkId,vehicleData);

GetPedData

Documentation

SetPedData

Documentation

Extended with (Keys):

• dob <ExpandoObject>
• warrant <string>

Example:

dynamic pedData = new ExpandoObject();
pedData.dob = new ExpandoObject();
pedData.dob.day = 1;
pedData.dob.month = 1;
pedData.dob.year = 1970;
pedData.warrant = "<warrant>";

GetPlayerData

Documentation

ExcludeVehicleFromTrafficStop

Params:

• networkID <int>
  • Network ID of the vehicle.
• exclude <bool>
  • If set to true, the vehicle won't be affected by the traffic stop function.
  • If set to false, the vehicle can be stopped by the player again.

The following example disables the traffic stop on the given vehicle:

Vehicle vehicle;
...
ExcludeVehicleFromTrafficStop(vehicle.NetworkId,true);

Vector3Extensions

(Made by @LukeD1994)

Around

Returns a random Vector3 relative to the specified position, given a set radius as distance

Example:

To get a random position around the PlayerPed in a 50f radius:

Vector3 randomPosition = Game.PlayerPed.Position.Around(50f);

Callout config

Server owners are now able to configure each callout with a config file. The easiest way to store a callout is to create a new folder with the callout name and place the .net.dll (callout file) and the config.json (must use this name) in that folder.

{
  "IgnoreDistance":false, // If set to true, the callout can appear outside of the department area
  "MinTimeout":0, // The minimum timeout before this callout can be instantiated again (0 = immediately)
  "Probability":1, // Moved it here instead of being hardcoded
  "Department":[1,5,9] // Restricts the callout only for these departments (identified by their ID)
}

Default config:

If no config file could be found, default values will be used.

• IgnoreDistance false
• MinTimeout 0
• Probability 1
• Departments null (null = any department)

Creating a FivePD plugin

To start off, you need to inherit the FivePD.API.Plugin class. By doing that, FivePD will only load these resources from the "plugins" folder, if there weren't any errors in the loading process (so if FivePD fails to load, your plugins won't be started or it'll unload the plugins once an error occurs - prevents random NullReferenceExceptions ). Another important note is that the constructor must be internal.

Example:

...
using CitizenFX.Core;
using FivePD.API;

public class MyPlugin : FivePD.API.Plugin
{	
	// Must be internal!
	internal MyPlugin()
	{

	}
	...
}

Converting old callouts

Examples

Steps:

• Change using CalloutAPI; to using FivePD.API;
• Inherit from FivePD.API.Callout instead of CalloutAPI.Callout

public class Trespassing : FivePD.API.Callout
{
   ...
}

• You must remove probability from CalloutPropertiesAttribute

[CalloutProperties("Trespassing","FivePD", "1.1")]
public class Trespassing : FivePD.API.Callout
{
   ...
}

• In the constructor, rename InitBase() to InitInfo()

public Trespassing()
{
   ...
   this.InitInfo(new Vector3(-935, 196, 67)); 
   ...
}

• Rename your Init() method to OnAccept()
• In OnAccept(), call this.InitBlip() instead of base.OnAccept()
• And now you are all set!