kdani-99/fivepd-api

A wrapper that allows you to create FivePD callouts/plugins.

Reporting errors

Create a new issue here (on GitHub) in the Issues tab with the appropriate label regarding your issue. This way, we can easily manage and solve issues quickly.

Important issue: World.GetNextPositionOnSidewalk() FiveM Source code sets that to Vector3.Zero if it couldn't find a good position around the area you specified (works within like 20-30ft of the player). (Source)

Requesting new features

To request a new feature, either create a pull request or create a new issue with the feature request label.

Get started

Before you start making your callouts, it's recommended to take a look at how to write your first script in FiveM as this API is basically nothing more, but a wrapper to make it easier to write callouts with the reduced chance of doing something error prone (With extended features).

Creating a new callout using the example and cmd compiler

1. Download one of the examples.
2. Open the file and start making your new callout.
3. Type the following command in cmd (cs compiler) to compile your code.: (Assuming that you have the references in the same directory)
   Note: .net.dll must be the assembly name. (For detailed instructions, visit the official command line building csc)

csc -target:library CalloutName.cs -reference:CalloutAPI.net.dll -reference:CitizenFX.Core.dll -out:CalloutName.net.dll

From scratch in Visual Studio

1. Create a new C# Class Library project and make sure the target framework version is 4.5.2.
2. Go to Project > Properties > Change the assembly name to .net
3. Add CalloutAPI.dll from the FivePD download as a reference.
4. Add CitizenFX.Core.dll from your FiveM client as a reference. (<client-root>\citizen\clr2\lib\mono\4.5\CitizenFX.Core.dll)
5. Derive Callout class

(For detailed instructions on how to create your first FiveM script, click here)

For documentation, visit the official FivePD documentation website.

If you wish to upgrade your old callouts, click here

Additional Support/Resources

We have an Offical FivePD API Discord Server which you can visit HERE.

If you wish to view videos on creating callouts using this API you can find a playlist of videos HERE.

fivepd-api's Issues

Pursuit - Request

Hey! It would be amazing if we can have the option to make a car automatically flee once the player get’s into range.

Example: In my newest callout pack I have a pursuit of armed suspects. Right now I have them manually speeding and driving away from the player though FivePD does not think the players pursuing them. So an option to make the player in pursuit on arrival would be amazing.

CheckRequirements - Department

It appears that the new CheckRequirements() method can't be used to check a player's department as the object is only created after the call out is received?

It would be good if this object is accessible by CheckRequirements() so that you can specify callouts to certain depts.

Automatically notify dept for backup

Functionality to allow you as the callout developer to automatically notify people in a certain department for backup on a callout. This would be good for callouts where they are a major incident, or in cases where people make use of jurisdictions more and want to notify the local PD too. I.E Call based in Paleto Bay comes to BCSO, but on the acceptance of that call, it automatically calls any units in Paleto Bay Police Department as well.

Reckless Driver/GTA

Would be nice to see a call added for Reckless Driver or a GTA that leads into a pursuit.

Add function to set Ped's items for frisk down.

Being able to set specific items for Peds would boost a lot, so if there's a Drug Deal callout there is actually drugs involved in itmes not like a bar of soap lol.

Callouts

Can we improve the callouts that make all the callouts actually work out in the end cause when we show up half the time no one is there.

Better error information for callout developers

Right now, when you made a derp and the callout couldn't be loaded or initialized for some reason, a rather generic "The callout could not be accepted" error is shown. As a callout developer, that's pretty useless, seeing as we have no clue what actually happened or what is actually causing the error. I think not bothering the day-to-day FivePD users with stacktraces is a good thing, however, we have to strike a balance between end-users and developers.

It would be really nice if there was a little bit more information in said error. Perhaps even a stacktrace? I'm thinking of allowing a debug- or developer-mode through the FivePD settings file? Or as an option in the debug menu in FivePD?

(request)

When a callout causes an error, have the callout named in the F8 console. When one crashes, admins have no idea which one died to remove/disable it.

Reckless Driver/GTA

Would be nice to have a reckless driver call or GTA call that leads into a pursuit

Ability to add items to vehicles

Same way you can add illegal items to a peds inventory, make it so we can add items to vehicles.

subject.NetworkID

Not sure If i'm doing something incorrectly, but Visual Studio is throwing issues when I use the following:

dynamic data = await this.GetPedData(subject.NetworkId);

where subject is a spawned ped above. Newest API is referenced, but the VS advises "Ped does not contain a definition for Network ID' and asks if I am missing any references?

CheckRequirements does not work

Independent of the value being returned within CheckRequirements, the callout is being displayed.

Reproduce:
Hardcode return Task.Fromresult(false); into CheckRequirements.

Expected behaviour:
Callout get's ignored and not displayed for acceptance.

Actual behaviour:
Callout get's displayed and can be accepted.

Overridable OnStart(Ped closest) not found when relacing downloaded CitizenFX.Core with nuget CitizenFX.Core.Client

I tried replacing the CitizenFX.Core dependency with the official nuget package of CitizenFX.Core.Client. However, after replacing I get an error that the overridable method OnStart(Ped closest) was not found.

The nuget package is up-to-date and seems to be identical to the downloadable dll of the FiveM client. Without insight into the FivePD source I cannot tell what dependency may break here.

This may not be a high priority but with the possible implementation of #36 and automated builds via GitHub actions, this would be a nice addition to the QoL development of FivePD addons.

MenuAPI integration

Let callouts add MenuItem entries to the interaction menu.

Expose Department / Rank

We should be able to reference what department / rank a user is assigned preferably before the callout is available to be accepted so we can route specific calls per department or rank

distance checking

Perhaps a nicety, but clearly FivePD has distance checking built in as this how the callouts are triggered. As you will likely know, checking the distance between player and call is a bit clunky if you are to write your own stuff.
Would it be possible for the API to expose the use of that distance checking method? Just to save duplicitous code.

Callouts For Multiple Players

Custom (and possibly in game default) callouts have trouble with blips and backup requests. If a second player accepts the backup request for a callout they receive the "Marker" blip leading to the start location, but do not receive additional blips related to the task. For example in a street racing callout (https://gtapolicemods.com/index.php?/files/file/820-fivepd-street-race-callout/) the initial accepting player can see all blips for the racers, but a backup player can't see any of the racer blips, but only the initial yellow start blip. Is there a way to add this functionality in custom callouts?

Ability to change models/loadouts in the F11 menu through configs

I would like to see a config file similar to the car config for both the peds and loadouts in the F11 menu.

Discord Rich Presence customization/hooking

A way to hook into FivePD's rich presence would be good. Maybe a way to allow callouts to access SetRichPresence (small text).

Feature request - Longer key press or chat command to open CAD system

Another cool thing would be adding a feature to allow for a longer keypress to open the CAD system. It could help prevent the computer opening randomly or unintentionally, especially if it conflicts with a common keybind

Question events

Can we get the functionality to trigger a method or some-such in the event of certain question responses?

For instance, you could have the question "Do you have anything on you that you shouldn't have" and in response to this, the Ped answers "No" but it triggers a method to make the ped flee?

It'd make interactions a bit more in depth.

api ideas

make a resource or something along the lines to link to a discord so that we can see active calls and the officers that accept calls and maybe show the call information

Publish FivePD-API as nuget package

I'd apprechiate a publication of the API as a nuget package. That way it's easier to download and upload the package within one's own development projects.

Only start the callout when one of the AssignedPlayers is in range

I have noticed that callouts get started when any player is in range of the callout. In my opinion it would be better if the call only starts when one of the assigned players are near.

The use case for this is that I'd like to create some logic that allows for the responding officer to see a person comitting a crime. If another officer happens to be in range of said call, but is doing something else and does not know the existance of the specific call, the officer is not going to pay attention or do anything with the call. Resulting in the original responding officer driving up to a scene that is completely finished.

Given, this is a little fix on the callout developer side, but I think it'd be neat if it was fixed on the FivePD side (perhaps even with a boolean flag in the callout).

Workaround for now:

public override void OnStart(Ped closest)
{
    if (!AssignedPlayers.Contains(closest))
        return;

    base.OnStart(closest);

    // etc
}

Feature request - Obtaining information

Something that would be useful is a method to obtain information on a ped, such as their name/address. That as well as information about a vehicle, such as owner, plate and such. Not sure if information is randomly generated now or such, but could be very useful to use in callouts.

Pursuit - TrafficStop control

For callouts it would be nice to be able to make a Ped ignore Traffic Stops so if a Suspect flees in a car after a murder for example, he won't just stop for a regular Traffic Stop.

FivePD API Suggestions.

The current API is amazing if matched well with the Native FiveM functions, but I think it could go a long way if some additional events are added in.

Suggestions:

1. OnLoad() - Could be an event that gets executed when FivePD Loads in your callout, so we can preload needed stuff from config files etc and don't have to read the config files everytime the Callout is getting initialized.
2. PedOnDeath() - Not sure if this can be done inside FivePD or rather a FiveM issue but gonna put it here anyway, would be nice to execute something when a specific Ped Dies (For example a victim in a callout) rather then having to put a "while(ped.IsAlive) { BaseScript.Delay(100) }" combo in your code.
3. PedOnRevive() - Again unsure if this is a FivePD or FiveM thing, but it would be nice if we get "notified" when for example a called EMS can revive someone. So the Ped is not just dumbfounded and standing in the middle of the roads.
4. PedGotArrested() - Speaks for itself but it would be nice to have an event when a ped gets arrested.
5. Some kind of way of setting an objective for a player or ending a call with a function, for example if a specific ped gets arrested the call should end with Code 4, so people don't have to end calls manually all the time.

Not event related stuff:

• Having some sort of access to the top left 911 call indicator, so people could change what is being written out instead of the default "Responding", status. Would be fun to redo them like "En Route to Scene", "On Scene", "In Pursuit" or whatever people wanna put out there.
• Would be nice to get some sort of menu inside callouts so for example in a suicide situation an Officers could try to talk down the suspect from jumping, and based on the officers question the subject could decide about the sucide..

These are the ones I could currently think of.

Expose Arrested Event

are we able to expose an event when the player takes someone that was arrested to the jail icon or when they are transported via transport unit?

Callout requirements - only show a call when requirements are met

As a callout developer I'd like to be able to set callout requirements. I'd like to prevent the callout from showing up at all when requirements are not met.

Possible use cases:

• Only allow the callout to be shown when the time in game is between 9PM and 3AM.
• Only allow callout when ped skin is firefighter.
• Only allow callout when it is raining.

I think this can be done rather easily without breaking backwards compatibility too much. My suggestion would be to set a flag in the InitBase method which tells the CalloutManager if the script has been initialized and ready for use or not. If not, the CalloutManager should try a different callout.

Improved date/time handling

I'm currently making a discord bot that reads reports and other things from the FivePD DB. From the looks of it, you store the date and time in the players timezone in the DB? This makes it awkward for me to handle as many of us are in different timezones, and therefore I can't easily convert it without knowing them all first.

Would it be possible to store all dates/times in a fixed timezone (e.g. UTC), or store the users timezones as well?

Update player data method

Could we get a method to update player data (like rank, department etc.)?
Right now when we make change to player in database from plugin it's not updating in game.

Request to Force Callout

As an admin, I would like to be able to force callouts upon players.

Override callout address

I'd like to override the callout adress with a custom text (e.g. "Central Los Santos Medical Center") to include custom POIs for FixedPosition callouts.

This feature could also be useful for multi-stage callouts where the address changes.

Set Ped Identity

In order to increase uniformity, the ability to modify elements of the Ped identity would be nice.

For instance, being able to set if a ped has a warrant when you spawn them in your callouts.

Further to this, specifying what they have in their inventory too, this would lead to players having to search suspects to see if they have drugs etc.

Config Support into FivePD

I think it would be really nice to have Config support in FivePD.

My suggestion on how you guys could do this the easiest way.
If you would include configs into the "__resource.lua" under files like

files{
   'callouts/*.json',
}

This would make so developers could use a FiveM native to access their files.
for example if I have my callout.dll named as "OfficerDown.net.dll" and I want a config file for it called "OfficerDown.json", I can access that file with the FiveM Native "0x76A9EE1F" the following way:

string config = LoadResourceFile("fivepd", "callouts/OfficerDown.json");

So the .dll and the .json config files can be at the same place, and every developer can use their config files the way they want. :)

Ps.: Hopefully I wasn't too confusing.

Thoughts about open-source?

What are your thoughts about open-source, and community contributions to the code base?

Call 'In Progress'

I've not noted any clashes yet, so perhaps logic exists already. However it might be pertinent to have an identifier that allows you either set if a callout can be generated repeatedly, or block it from occurring if it's already in progress.
For calls with random locations, its fine if a callout is repeatedly generated for different players, however I have some more in-depth callouts where a static location is used, and in this instance, it'd be quite annoying if a second player has the same callout loaded for them halfway through our run-through of the call.

GetRandomPed() Spawns PedHash.Humpback

While very comical, the GetRandomPed's while loop is missing "ped == PedHash.Humpback"

Adding functionality make extensions for FivePD

This came to mind when I tried to make my plugin turn on and off the "On duty" state. After digging in the code I saw that you had tons of EventHandlers for handling custom events. I hope that you could add functionality to use events to control parts of FivePD. It would also be interesting if we could add listeners and retrieve data, like what mission you're on, when a mission is completed, etc..

Duty Notification

Would it be possible to incorporate in the configs, the ability to toggle the duty notification to all players. I have an RP server gathering traction and we would like to use fivepd for our emergency services while using ESX for our Civilians, our problem is that when someone goes on duty it notifies everyone, ruining roleplay. It would be nice to be able to turn it off so your crims dont hide when someone shows on duty. Thx in advance.

Example callout is Incorrect

https://github.com/KDani-99/FivePD-API/wiki/Example-Callout

This page has incorrect CalloutProperties and could confuse new users. The author string seems to be missing.

Incorrect
[CalloutProperties("Trespassing", "1.0", Probability.Medium)]

Correct
[CalloutProperties("Drunk & Disorderly", "Alexa", "1.0", Probability.Medium)]

Errors within Init() should be thrown to the console

Right now errors within Task Init() only produce the error message: An error has occured, could not accept callout. This should be more verbose to make debugging more easy.

Additional API features

Per Daniel's request I submit these suggestions here.

1. Add an 'action' key which can be common across all callouts but the functionality of is defined on a callout by callout basis

2. Create API editable vehicle information, similar in nature to peds (i.e Owner, Is stolen, Registration, Defected, etc)

3. Add the ability to update call information which can be reflected in the MDT and to other players with an event in the API (think daniel is onto this already). Adding in some sort of sound effect to signify that the call has been updated in the MDT could be good as well.

4. Potentially add something in for determining if two players are riding two-up, and who is partnering with who. I can see some interesting dynamics coming from this, but right now it's still rumbling in my mind. You guys might have some ideas on this.

Cheers,
SNIT