As of version 1.1.2, the race registration system has changed to allow a race to have different number of skills (although we still recommend 3 skill 1 ultimate races)


To get started making a race, you must meed ALL of the following REQUIREMENTS (yes its repetitive):
1 Know what sourcemod is.
2 Know how to compile a sourcemod plugin.
3 Know the sourcepawn programming language itself.
4 Know to use how sourcepawn/sourcemod to do specific tasks.
5 Able to create the race you are thinking of in a standalone plugin. This means that you are theoretically able to make a plugin that gives everyone the functions of that race without war3source, you demonstrate that you know how to hook events and set player properties.
6 You are not copy and pasting other races.

If you don't have all requirements met, you need to hang out more in the sourcemod forums, and ask scripting questions there.

This is NOT the place to ask: how do I set heath, how do I set ammo, how do I set gravity...etc. You should know how to set these before creating such a race.

This is also NOT the place to ask how to use War3Source to set things for you, post these questions in their own topics: how do I set health with War3Source, how do i set gravity with War3Source, how do i set speed with War3Source.


This tutorial teaches you the inner workings of the main War3Source plugin and allows you, the race developer, to run your race under the war3source plugin, and properly use the war3source interface (natives and forwards) to do tasks. After this tutorial, you are encouraged to use default packaged races as examples to help you create your new race.

Please follow the conventions given in this tutorial, such as variable names, it really helps us help you.

After you have read this tutorial, i have some recorded video sessions with beginner programmers. Download teamviewer (@teamviewer.com) and download the videos.
http://ownageclan.com/teamviewer/753%20789%20456%202010-07-29%2010.35.tvs building a copy cat race: low gravity, criticals, evasion, and flame strike.

If you have any specific questions about this tutorial, please do post a topic.

Lets get started!

Lets start coding shall we?



Create a new .sp file. Preferably name it War3Source_<race name here>.sp

Open it with your text editor for .sp files
(I use the defunct PawnStudio which still crashes alot, but IntelliSense-autocompletion is great for new programmers)

Add the following if it does not exist (probably not because we made a new blank file)


Declare global variables before OnPluginStart() as we go... ie new Handle:ultCooldownCvar;
Every race needs a thisRaceID, it stores what race number itself is registered to. Since forwards call every plugin, forwards with the race parameter will be checked against this variable and to the appropriate action.
thisRaceID will be > 0 if registered successfully.

As the awesome sourcepawn programmer you are, you would know every plugin needs to register itself with sourcemod in OnPluginStart...meanwhile do the stuff you need to do in here (dont just copy everything).

After you registered your race and skills, you basically start implementing what they do. Start hooking events or use War3Source functions to modify their properties. HOWEVER, you must only do it if the person has a relation to your race. this is when thisRaceID and War3_GetRace comes in.

Following the example of the Undead race

when the player dies, we make some explosion effects and deal damage to enemies
IF: he is our race, and he has our ultimate skill leveled, he hasnt already suicided since last spawn (exploit check)
War3_GetSkillLevel( client, race, what skill id of this race) returns what level the player is at this skill.
For now we just check if skill level is > 0, to say that he has a level in this skill.

//DelayedBomber expires, it just calls SuicideBomber. DelayedBomber is what i call a "timer helper function" lol.

When player spawns he should be able to suicide again (if hes our race lol):

And whats this InitSkills(client)??
It grants passive abilities to the player: speed and low gravity.
You will get a lesson in "buffs and debuffs" later.

We also set his buff on race selection (instead of waiting at next spawn to grant his powers)
But we also have to be aware if he switches to another race, we need to cancel his buffs!

If he leveled up (or leveled down by an admin), we can re-initiate his skills, but with different levels since InitSkills gives buffs based on his current skill level.
We could have combined InitSkills to check if he is this race, and if he is not just remove all buffs.
This is separated just to let you know in which situations you should deal with passive skills, otherwise if not done right the player gets to double stack a race's skill with another race or do some exploits!

Active skills (abilities and ultimates)

There are forwards when the player presses the ability or ultimate button. You usually check to see if the player is valid, if they are your race, and see if they have the skill that you are interested in activating.

You dont always have to check the "ability" argument, its for if you have multiple abilities, the one would be activated via +ability (number==0) and the second one activated by +ability1 (number==1)
Same concept with ultimates. OnUltimateCommand passes a "race" variable (this is very old but we didnt bother changing it). You can for now use it to compare it to your own thisRaceID.

The Buff System (you must be joking if you don't know what a buff is)

War3Source has a buff system (and debuff but its the same system) which removes many conflicts between races. Like one race wants to set the gravity to X and another wants to set the gravity to Y, and the two races don't know each other. To solve this problem we have all the races that want to set gravity pass on their intended value to War3Source buff system and the buff system has the final say on what gravity the player gets.

The buff system also helps in denying buffs (debuffs). If one races disables low gravity for other races, that that race can set a debuff on the client in the buff system, instead of telling every other race to cancel their gravity.

All the available buffs are listed in the constants.inc
sample here:
Each race only has ONE say about EACH buff, so if you have two skills that modifies the same buff, you need to keep track of the stacking yourself! We made fSlow and fSlow2 specifically to allow your race to have stacking slows, but this wont always be the case.
The last buff value set for that property overwrites the previous value for your own race. So if u set client gravity to 0.4 then 0.6, 0.6 is the final value registered on the buff system.

The syntax:

set his low gravity

remove his low gravity

force someone to lose their gravity buffs (debuff)

See races for more examples!