A P I G U I D E A N D D O C U M E N TAT I O N

VERSION 1.0 PUBLIC

D E VE LO PE D B Y G 17 M E D IA
w w w . l c pd f r . c om
 CONTENTS TABLE OF CONTENTS

SECTION 1 - INTRODUCTION TO THE LCPDFR API PAGE

SECTION 1 - INTRODUCTION AND FOREWORD 3

SECTION 2 - USING THE LCPDFR API 4

SECTION 2.1 - INTRODUCTION TO THE ARCHITECTURE 4

SECTION 2.2 - GETTING STARTED 4

SECTION 2.3 - COMPILING THE SAMPLES 4

SECTION 2.4 - THE SAMPLE PROJECT IN DETAIL 6 6

SECTION 2.5 - COMMON ACTIONS 7

SECTION 2.6 - CREATING A NEW PROJECT 8

SECTION 3 - CONCLUSION 10

SECTION 3 - CONCLUSION 10

2 G17 media
 SECTION 1 INTRODUCTION TO THE LCPDFR API

SECTION 1 - INTRODUCTION AND FOREWORD

The LCPDFR 1.0 API is a powerful set of scripting tools availble to GTA IV script modification developers. The API
uses the .Net Framework in the same way as the GTA IV .Net Scripthook, meaning that all API features work in tandem
with the native functions offered by the Scripthook, resulting in more powerful scripting capabilities.

In particular, the LCPDFR API runs as part of the LCPDFR modification, meaning all API scripts can communicate with
LCPDFR, which offers scripters greater control over how their modifications work with LCPDFR. The LCPDFR API
also has a number of functions which can be used by scripts, enabling anyone with a little bit of coding experience to
start pursuits on vehicles, check for the completion of an arrest on a suspect or simply call for a backup car.

Hello! In this document I want to give you a

short introduction into the powerful LCPDFR

1.0 API. I will cover the most important aspects,

as well as providing small code samples for

common actions. This document presumes a

basic knowledge of programming and the C#

language. LCPDFR 1.0 is the first release of

LCPDFR ever coming with an API and as such

will be extended further in the future to fit your

needs. It does not only allow you to create your

very own callouts, but also run scripts alongside

LCPDFR while having access to many new

functions. You can create epic chases with your

own set of rules in minutes or script your own

detailed callout and share it with fellow officers

around the globe. It’s all up to you!

LMS,
LCPDFR Lead Developer
lms@g17media.com

3 G17 media
 SECTION 2 USING THE LCPDFR API

SECTION 2.1 - INTRODUCTION TO THE ARCHITECTURE

But before we take a look at actual code now, let me explain the basic architecture. The API resists inside the LCPD
First Response.dll library and can be accessed by any .NET language. Please note that all examples will be provided
in C#, as it is the language of my choice when it comes to .NET. It works similar to the ScriptHookDotNet architecture,
where one inherits from GTA.Script to have its code loaded. Because the API is not limited to callouts only, the main
class where your entry point will be, is Plugin. So by inheriting from Plugin, LCPDFR will automatically recognize the
class and create an instance of it once the game starts. The LCPDFR mod itself is developed as a plugin too and
loaded by the internal engine, thus all plugins will start when the game starts and even run when not on duty.

SECTION 2.2 - GETTING STARTED

Now that you know how the architecture works, let’s have a look at the assembly loading process. The LCPDFR mod
is created as a plugin too and merged into the engine assembly for simplicity, but third party plugins belong into a
special folder. This is: game\lcpdfr\plugins. Any .NET DLL in there will be checked for classes inheriting from Plugin
and registered, if so. You can replace the plugins while the game is running just as you can when using SHDN, simply
turn off LCPDFR in game, reload scripts and your new code will be loaded. So all you have to do is putting your .NET
assembly in this folder. Before we can start compiling the samples, you have to download and install Visual Studio
2012 or later (the free edition for C# is fine).

SECTION 2.3 - COMPILING THE SAMPLES

LCPDFR 1.0 ships with a sample project which shows how to register and create callouts and some other basic
functions. Now navigate to the samples folder and open API Example.csproj. In Visual Studio, double click Main.cs to
jump to the program’s entry point. You should see something similar to this:

4 G17 media
To see if everything works, hit F6 (or choose Build  Build solution). It should compile just fine. Congratulations,
you have just compiled your very first plugin for LCPDFR. Now navigate into the Bin folder of your project and from
Debug copy the API Example.dll to game\lcpdfr\plugins. But before we get in game now, let’s check what our plugin
is supposed to do.

In Main.cs we can see a function called Initialize.

As explained by the description, this function is called when the plugin itself has been registered, loaded and created
successfully. The moment you see your player character in game, this code is executed. We can ignore the first call
for the console commands for now, and focus on the OnDutyStateChanged event. This event is fired whenever the
on duty state is changed, whether the player goes on or off duty. Since our plugin is running even when we are not on
duty, this is the perfect start when we want to wait for the player to go on duty. Let’s have a look at the event handler:

As you can see, we check if onDuty is true, and if so, we register our callouts to LCPDFR. So this is how you can
make things happen only when player went on/off duty.

5 G17 media
Next thing to look at is Process. This function is called every single tick and is responsible for executing the main logic
of our plugin. For instance, the LCPDFR mod calls everything from here: The callouts, the key checks, the AI etc.

As you can see, we check whether the player is on duty, and then we check if the Z key is down, or if using a controller,
DPadRight is down. Yes, you are right, using a controller is as simple as that. If the condition is met, we spawn a new
ped using LPed. This is an advanced type which offers more functions than GTA.Ped and contains all new LCPDFR
features.

Just below we check whether this particular ped exists, and if so, we check whether it has been arrested and kill it in
case. So we now know, that we can spawn a ped in game using Z (or DPadRight) and it should die once arrested.
So let’s try it out.

Once in game, get on duty (ALT+P by default, then type forceduty in console). Now make the ped spawn and arrest it.
Note that the arrest state is either set when you decide to take it to a station or it has been successfully placed inside
an AI vehicle. That’s it, we just verified that this simple script works and we can easily read the arrest state of a ped.

SECTION 2.4 - THE SAMPLE PROJECT IN DETAIL

For users looking for more advanced stuff, I’ll share a few important things about the sample. This requires some
knowledge of the C# language and general programming.

• The RegisterConsoleCommands call binds all console commands to the instance of the class. Look at the Start-
Callout function to see how easy binding console commands is now!

• In Finally all resources are freed when the plugin is unloaded, do all your final cleanup here!

• Callouts have to be registered as shown in the example earlier and you have to be on duty to register them already.
They also have to inherit from Callout in order for them to work properly.

• To see how more complex scripts can be developed, check out both sample callouts. There are lots of comments
that should help you getting an idea of how things are done. Also be sure to check out the Common samples
section below.

• If you plan to develop a whole mod using the plugin architecture, you may come across the ScriptManager class
which can be used to start subscripts. All you have to do is make your class inherit from GameScript and set up
the necessary attribute data. Then it can be started via the ScriptManager. This is also how LCPDFR internally
operates: The main plugin creates a new ScriptManager instance and creates scripts when needed. For instance,
when you want to arrest a ped, the Arrest script is created. Once the ped is arrested, the script ends and is removed
from the ScriptManager automatically again. It is an ideal tool to separate things from each other and only run
certain things when you really need them.

6 G17 media
SECTION 2.5 - COMMON ACTIONS
One of the most important things is to specify, who controls an entity. This means, who is responsible for making
the entity doing things, who cleans it up, who needs it and who doesn’t want it to be used by other scripts or actions.
This is achieved by a set of API calls:

• void AddToScriptDeletionList(LPed ped, GameScript gameScript)

• void AddToScriptDeletionList(LVehicle vehicle, GameScript gameScript)
• bool DoesPedHaveAnOwner(LPed ped)
• void SetPedIsOwnedByScript(LPed ped, GameScript gameScript, bool owned)

Don’t panic, they seem more complicated than they are.

AddToScriptDeletionList: Adds a ped or vehicle to the local deletion list of the script. That is, once the script (or callout,
since it inherits from GameScript) ends, the entity is being freed automatically. So this manages the creating and
freeing of entities.

SetPedIsOwnedByScript: Marks a ped as not-available to other scripts internally, thus effectively preventing them
from accessing it (e.g. for creating world events). This will also mark the ped as mission ped. If a ped set as owned
is freed by the deletion list, it is still unavailable. This can only be undone by calling it again with owned set to false.

DoesPedHaveAnOwner: This should be pretty self-explanatory now. It simply returns whether the ped has an owner.
Use this to ensure you can make use of a ped.

Last but not least, all classes inheriting from GameScript (so including callouts), can implement the following virtual
function:

virtual void PedLeftScript(LPed ped)

This function is called every time, a ped owned by the current script is being requested by another script which is more
important. Thus the current script will lose ownership. You have to free the ped here and do all cleanup necessary so it
can be used by another script. For instance, when a ped owned by a callout is being arrested by the player, the arrest
script will take control and thus the callout has to free the ped. In most cases, an implementation like this works just fine:

public override void PedLeftScript(LPed ped)

{
base.PedLeftScript(ped);
// Free ped
Functions.RemoveFromDeletionList(ped, this);
Functions.SetPedIsOwnedByScript(ped, this, false);
}

For more code examples, please check out the two callouts that come with the API example project.

7 G17 media
SECTION 2.6 - CREATING A NEW PROJECT
When you choose to create a completely new project, you first have to add the references to make use of the LCPDFR
code. I’ve illustrated this case below by removing the References folder from the sample folder.

A window similar to this will show up:

Now you can see there are quite a few red-colored words and two warnings. Don’t worry, this is because we have not
yet setup the necessary dependencies. In your case even the SlimDX reference might be broken, but first things first.

8 G17 media
On the right, expand references like this:

You will see a couple of warnings (as stated above, you probably miss SlimDX too) because some references could
not be resolved. Right click on References and choose Add reference.

In the new dialog, choose Browse on the left, then Browse on the right and add the missing references.

9 G17 media
 SECTION 3 CONCLUSION

SECTION 3 - CONCLUSION
I hope this short documentation helped you getting started with creating plugins for LCPDFR and will assist you in
the future.

As said in the beginning, since this is our first API release, a lot of changes and additions are to be expected.

If you have any questions or requests regarding the API, please use the forums. Now good luck and happy coding!

- LMS, 23.12.2013.

10 G17 media
L CPD F IR ST R E SPO NSE 1.0 API M ANUAL
C O PYR IG HT © G 17 M ED IA 2 0 13 G17 media