Writing a Map Script

Starting version 2.4 you can create Javascript scripts that make your map interactive! First of all, you should know at least the basics of javascript before you continue with the guide. If you have any questions related to javascript, please google them. Please note that only .XML maps can have scripts.

Anyways, a script is a javascript file, named the same as the map, but using the .js extension, so if my map is called road_works.xml the script should be named road_works.js. The script file must be placed in the same directory as the file. The script is executed on map load.

Your script is exposed to ScriptHookVDotNet via the API namespace, plus some helper functions in script object.

To get more information on Javascript-.NET pipeline, you can read the documentation here: https://www.codeplex.com/Download?ProjectName=clearscript&DownloadId=632497

Some ideas for scripts:

• Call API.GTA.Game.Player.WantedLevel = 0 in the OnTick event so you can build in restricted areas, such as the Zancudo Base.
• Create teleportation markers.
• Create complex tasks for your peds, such as patrol routes.
• Add modifications to your vehicles.
• Set weather and time of day to set a mood for your map.
• Any many more!

Creating a simple script: Kill a ped

You may have noticed that all of the map objects now have an 'Identification' property. This is used to access your ped/vehicle/prop from the script. You can set it to whatever you want as long as it is considered valid by javascript (here's a nifty tool for that: https://mothereff.in/js-variables). We start by placing a ped and setting it's Identification to 'suicidalPed'. Then we save the map as 'killerMap.xml' using the XML format. Next step is creating the script file. We then create a file named 'killerMap.js', and open it with any text editor (I like to use Notepad++).

We now have access to the ScriptHookVDotNet API, and our ped. For example, if we want to access the World class from ScriptHookVDotNet and call the SetBlackout method, we prepend API to the full namespace: API.GTA.World.SetBlackout(true);. Anyways, onto our ped. Any object you have set an indetification for will be easily available to you in the script. For example, to kill our suicidalPed, we just invoke the Kill() method on his object: suicidalPed.Kill();. That's it. All of the methods and properties ScriptHookVDotNet gives you for Props, Vehicles and Peds are available. Then when we load the map, our ped gets instantly killed!

Available Methods

You can find more information on ScriptHookVDotNet on their wiki page. Apart from the API.GTA namespace, you have access to the script object:

void script.CallNative(string nativeHash, params object[] args)

Call a game native by it's name. You can still use ScriptHookVDotNet's API.GTA.Native.Function.Call() if you prefer. Example:

script.CallNative("GIVE_WEAPON_TO_PED", API.GTA.Game.Player.Character, 453432689, 50, true, true); // Give pistol to player

object script.ReturnNative(string nativeHash, int returnType, params object[] args)

Return a game native's value. Return types are as follow: Int = 0, UInt = 1, Long = 2, ULong = 3, String = 4, Vector3 = 5, Vector2 = 6, Float = 7

void script.MoveProp(Prop prop, Vector3 newPosition, Vector3 newRotation, int durationInMs)

Move a prop from it's current position to the specified new position & rotation. Be careful though, this method blocks the executing thread.

bool script.IsPed(int handle)

Returns whether the handle belongs to a Ped.

bool script.IsVehicle(int handle)

Returns whether the handle belongs to a Vehicle.

bool script.IsProp(int handle)

Returns whether the handle belongs to a Prop.

int[] script.GetCurrentMap()

Get all of the map's handles. To get an object out of the handle, first you find out whether the handle belongs to a prop, ped or a vehicle, then you create a new ped/prop/vehicle object with the handle: var firstProp = new Prop(script.GetCurrentMap()[0]);

You also have access to the NativeUI library: API.NativeUI.UIMenu(). Please see the NativeUI wiki for more information.

Script Events

script object offers four events: OnDispose, OnTick, OnKeyDown and OnKeyUp. To suscribe to an event, use the connect method:

script.OnKeyDown.connect(function (sender, args) {
    if (args.KeyCode === Keys.D1 && API.GTA.Game.Player.Character.IsInVehicle()) {
        // Do something
    }
});