A Guide To Scripting

From IV:MP Wiki

Jump to: navigation, search

This is supposed to be a simple guide to making a squirrel script. It's aimed at IV-MP version 0.1 and above.

We assume you have the ability to think and follow some advice.



How to use this wiki

This wiki is a great place for info, just like this guide. It has information on possible functions, the syntax for those functions and what callbacks you can latch on to. You can navigate the wiki by clicking one of the lists on the left (Server/Client -> Functions/Events) and finding what you need.

Alternatively if you know the name of what you're looking for, e.g. you're getting a wrong parameter amount error, just type the function-name in the search box at the top right of this wiki and hit return.

How to use this guide

This guide will not teach you how to create a fully functioning RolePlay or DeathMatch gamemode. It will however teach you how to use the various events and functions required to do so.

After all, give a man a fish and he'll eat for a day, teach a man how to fish and he'll eat for a lifetime (Or until there's no more fish to catch ;))

More help

If you can't find what you need on the wiki, I suggest you search around the forum. Big chances are your question has already been asked and answered. If you've searched both the wiki and the forum and still haven't found what you needed you can always make a topic yourself.

But please, do search before you make a topic, it's quite annoying to answer a question for the 100th time a day.

((TO DO: Add links to the squirrel manual here))

Two kinds of scripts

There is two kinds of scripts in IV-MP (Version 0.1 and up).

One is the client side scripts, these are scripts that run on the client side and allow you to manipulate things like the user interface that people see. It also allows you to handle key events.

On the other side there are the server scripts. As the name suggests these run on the server, they let you hook into global events such as a player connecting or entering a vehicle.

The two scripts can communicate by creating events and triggering those (triggerServerEvent to trigger a server event from the client, and triggerClientEvent to trigger a client event from the server).

Getting Started with a Server Script

For now we'll just let client scripts go. Your main functionality will come from the server script, it's where you keep track of player kills, money etc.

In order to do anything in a script you need to respond to events. You do this by creating a function and telling the server we wan't to use that function to respond to an event. Let's create a simple function that will tell everyone on the server a player has joined.

function onPlayerConnect ( playerid )
    sendMessageToAll(getPlayerName(playerid) + " (" + playerid + ") has joined the server.");
    return 1;
addEvent("playerConnect", onPlayerConnect);

First we create a function named "onPlayerConnect". Then we send a message to all the connected player telling them that the player has joined the server. We return 1 to let the server know everything was successful (Some events will use the return value to decide what to do, the onPlayerConnect ignores this value, more on this later) Last but not least, we tell our server to add an event listener for the playerConnect event and call our onPlayerConnect function, without this the function would never been called.

This bit of information is really all you need to write a gamemode for your server, pretty cool huh? Let's try something a bit more complex though. We'll create a script that denies everyone with an odd playerid to enter a car, not very useful but funny enough.

function oddOneOut ( playerid )
    if ( playerid % 2 == 1) // The playerid is odd
         sendPlayerMessage(playerid, "You're not allowed to ride in vehicles with an odd playerid. Please rejoin the server and hope you get lucky!");
         return 0;
    else if (playerid % 2 == 0) // The playerid is even
         sendPlayerMessage(playerid, "Enjoy your ride");
         return 1;
addEvent("playerEnterVehicle", oddOneOut);

So if you compare this to our last example you should get a basic idea of what we do. We create a function and let the server call it when the playerEnterVehicle event is triggered. As you can see it doesn't matter what our function is called as long as the right name is passed as second parameter to addEvent.

What you might have noticed is the different return values depending on the if statement. Let's take a look at that. The % sign is the modulus sign, in this case, we take the playerid, divide it by two and then compare the remainder of that (So 3 / 2 would be 1 with a remainder of 1 and 2 / 2 would be 1 with a remainder of 0) against either 1 or 0. A sharp eye might have noticed the second else if (...) could've been replaced by an else since it's the only other possibility, but for this example leaving the if is more clear.

If we determine that the playerid is an odd number (The first part of the if statement) we tell the player they can't enter a vehicle, we do this with the sendPlayerMessage function instead of the sendMessageToAll because we want to address a single player. Then we return 0, this is the little bit of magic, remember my earlier comment about return statements? The playerEnterVehicle event uses the return statement to determine whether or not it should let a user enter a vehicle, returning 0 tells the server it has to throw the player out again. So what do we do if we determine the playerid is an even number? Exactly, we tell them to have fun and tell the server to let them get in the car.


This wiki page is still under construction, I will add more info soon.
Meanwhile, please use the discussion page if you wish to leave a comment about this page.

-- Kingdutch 03:43, 7 April 2011 (EDT)

Personal tools