WC3 JASS.com
"The Jass Vault" plus vJASS and Zinc

You create a struct of type CustomRace, with the following constructor:
static method create takes string Name, race Race, real Handicap returns CustomRace

Each of the parameters are described below:

• string Name  - The name for your race
• race Race  - The standard race it will be based on (eg, RACE_HUMAN).
• real Handicap  - The handicap value users need to set so they can pick the race. Accpetable values are 0.5, 0.6, onwards up to 1.0 (which means you can overwrite the standard races too)

You can also create and register a custom race for all handicaps of a single race with:
static method createAll takes string Name, race Race returns CustomRace


You can extend the registration of a custom race to more than one handicap with:
method register takes race Race, real Handicap returns nothing
 
 
 

Once created, you still need to register its townhall, the workers types (you can have more than one type of worker) and hero(es). You can do it by using the following methods:

method setTownHall takes integer TownHallId returns nothing

• integer TownHallId   - The rawcode of the race's Townhall (eg 'ogre' for Orc Great Hall)

method addWorkerType takes integer WorkerId, integer Priority, integer Quantity returns nothing

• integer WorkerId   - The rawcode of the race's Worker (eg 'hpea' for Human Peasant)
• integer Priority  - The priority where the worker type unit will be created. Acceptable values are
• CustomRace.NEAR_MINE  - Spawns them near the closest mine. Normally all worker units should use this value.
• CustomRace.NEAR_HALL  - Spawns them near the starting Town Hall unit type. This is included if you want additional workers, in the same vein Ghouls are for the Undead race.
• integer Quantity   - The amount of initial workers of that type.

method addHeroType takes integer HeroId returns nothing

• integer HeroId  - The rawcode of the race's hero (eg 'Hpal' for Human Paladin)

If you've got an AI ready to be implemented, then you've already done the hard part. All this takes is a string for the file path and it takes care of the rest. Custom races that were registered but don't have AI scripts cannot be played by the computer. Of course, you can circumvent this (for whatever silly reason) by using this with a string that doesn't refer to an .ai file ("poop" for example).

method setAIScript takes string FilePath returns nothing

• string FilePath  - The filepath of the .ai script, either in an MPQ or imported to the map

Finally, if your race needs extended initialization beyond the creation of worker units, you can do so by assigning a custom callback function that will run after all the initial units are created; this might be useful to replicate behaviour like the initial Haunted Goldmine the Undead start with, or the Entagled Goldmine for the Night Elves. For that you use the following method:

method setCallback takes CustomRaceCall callback returns nothing

• CustomRaceCall callback  - A function that matches the CustomRaceCall function interface. More on that below.

The CustomRaceCall function interface is used for the aforementioned callback. It is defined as follows:

function interface CustomRaceCall takes player Player, group Workers, unit Goldmine, unit Townhall, unit Randhero returns nothing

• player Player  - The owning player of the units passed to the callback function.
• group Workers  - A unit group with all the created workers created, regardless of type.
• unit Goldmine  - The nearest Goldmine found at the start location. If there isn't a Goldmine nearby, this parameter is null.
• unit Townhall  - The townhall created on initialization.
• unit Randhero  - If the "Use a Random Hero" option is checked before starting the game, this parameter points to the randomly created Hero; otherwise, it will be null.

If you need to get the custom race of a player, GetPlayerCustomRaceName will return a name string of the custom race. Hopefully, you aren't silly enough to name your custom races identically.

function GetPlayerCustomRaceName takes player Player returns string

• player Player  - The player with a custom race. Players without a custom race associated with them will return an empty string.