JASSPedia [Needs your feedback]

[bowser499]

JASSPedia
The natives gathered all together with detailed explanations of them.

- A -

constant native AbilityId takes string abilityIdString returns integer
constant native AbilityId2String takes integer abilityId returns string
These functions were supposed to convert raw codes of abilities to strings and back. But, as the comment in common.j states...
// Not currently working correctly...

...which means that these functions are bugged and can't be used properly. But there is the way to convert raw codes to strings and back. April 17, 2007 AceHart published working alternative to these functions.

Char2Id and String2Id functions

function Char2Id takes string c returns integer
        local integer i = 0
        local string abc = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
        local string t

        loop
            set t = SubString(abc,i,i + 1)
            exitwhen t == null
            exitwhen t == c
            set i = i + 1
        endloop
        if i < 10 then
            return i + 48
        elseif i < 36 then
            return i + 65 - 10
        endif
        return i + 97 - 36
endfunction

function String2Id takes string s returns integer
        return ((Char2Id(SubString(s,0,1)) * 256 + Char2Id(SubString(s,1,2))) * 256 + Char2Id(SubString(s,2,3))) * 256 + Char2Id(SubString(s,3,4))
endfunction

native Acos takes real x returns real
Arccosine, one of inverse trigonometric functions. The result is returned in radians in range [0;Pi].

• Safe to use in local blocks: Yes

native AddHeroXP takes unit whichHero, integer xpToAdd, boolean showEyeCandy returns nothing
This function adds xpToAdd experience to the given hero (whichHero).
This function has a glitch: adding negative value to experience will decrease it by the stated value, but won't lower the level even if the experience value after deduction is lower than the lower bound of the experience required to get the stated level. If the value will become lower than zero, the experience won't be negative, instead of it it'll be equal to 4294967296+(supposed_negative_experience_value) which actually proves that WarCraft III uses unsigned int type for storing experience points.

• Safe to use in local blocks: No

native AddIndicator takes widget whichWidget, integer red, integer green, integer blue, integer alpha returns nothing
Adds a blinking circle around widget with the color (red,green,blue,alpha). The circle blinks twice. This function is commonly used for cinematic modes and is seen in TransmissionFromUnitWithNameBJ.

• Safe to use in local blocks: Yes

native AddItemToAllStock takes integer itemId, integer currentStock, integer stockMax returns nothing
Adds an item of the type itemId with current stock of currentStock and max stock of stockMax to all shops in game. Some issues with default Blizzard initialization and that function were met. See this thread for getting details.

• Safe to use in local blocks: No

native AddItemToStock takes unit whichUnit, integer itemId, integer currentStock, integer stockMax returns nothing
Adds an item of the type itemId with current stock of currentStock and max stock of stockMax to the specific shop whichUnit. Some issues with default Blizzard initialization and that function were met. See this thread for getting details.

• Safe to use in local blocks: No

native AddLightning takes string codeName, boolean checkVisibility, real x1, real y1, real x2, real y2 returns lightning
Adds the lightning of type codeName between two points with coordinates (x1;y1) and (x2;y2). The checkVisibility parameter allows to toggle lightning's visibility in fog of war and black mask: true will force it to show in the fog of war and black mask when false is the reverse operation. This function is making Z coordinates of both lightning edges equal to 0.

List of lightning types to put as codeName parameter

• "Chain Lightning Primary" - "CLPB"
• "Chain Lightning Secondary" - "CLSB"
• "Drain" - "DRAB"
• "Drain Life" - "DRAL"
• "Drain Mana" - "DRAM"
• "Finger of Death" - "AFOD"
• "Forked Lightning" - "FORK"
• "Healing Wave Primary" - "HWPB"
• "Healing Wave Secondary" - "HWSB"
• "Lightning Attack" - "CHIM"
• "Magic Leash" - "LEAS"
• "Mana Burn" - "MBUR"
• "Mana Flare" - "MFPB"
• "Spirit Link" - "SPLK"

For details about Lightnings, you can visit -Derp-'s tutorial about lightnings, from where I've got lightning types.
You can also import custom lightnings in your map in addition to default. For those who wants to know how it's done, I advise to read Softmints' tutorial about custom lightning effects.

• Safe to use in local blocks: Yes

native AddLightningEx takes string codeName, boolean checkVisibility, real x1, real y1, real z1, real x2, real y2, real z2 returns lightning
Same as above, but also allows to control Z coordinate of the lightning.

• Safe to use in local blocks: Yes

constant native AddPlayerTechResearched takes player whichPlayer, integer techid, integer levels returns nothing
Adds the levels more levels to the tech with raw code techid for player whichPlayer.

• Safe to use in local blocks: No

native AddResourceAmount takes unit whichUnit, integer amount returns nothing
Adds the amount more gold to the whichUnit gold mine. This function has the glitch: if the value after adding negative amount will be less than zero, then it will display negative resource amount, but if some peasant or peon will try to gather resources from such a mine, he will bring back 0 gold and the mine will be auto-destroyed.
As for me, I'm really confused on why to use signed ints for mine's resource amount. Maybe somebody is able to explain that?

• Safe to use in local blocks: No

native AddSpecialEffect takes string modelName, real x, real y returns effect
Creates the special effect in point with coordinates (x;y) with Z = 0 using the model file with a path modelName.

• Safe to use in local blocks: In some cases

Special notes about using AddSpecialEffect in a local block

The usage of this function in a local block is safe if the path to the model will be something which will be changed locally. Look at the example of Holy Bolt effect created in the center of the map and shown only to red player:

local string modelPath = ""

if GetLocalPlayer() == Player(0) then
    set modelPath = "Abilities\\Spells\\Human\\HolyBolt\\HolyBoltSpecialArt.mdl"
endif

call DestroyEffect(AddSpecialEffect(modelPath,0.,0.))

Trying to create the local effect any other way will cause a desynchronization. Mind it when using the effects in local blocks.

native AddSpecialEffectLoc takes string modelName, location where returns effect
Creates the special effect in the stated location where with Z = 0 using the model file with a path modelName.

• Safe to use in local blocks: In some cases - look AddSpecialEffect function for more information.

native AddSpecialEffectTarget takes string modelName, widget targetWidget, string attachPointName returns effect
Attaches the special effect to the attachment point attachPointName of the target widget, using the model file with a path modelName.

• Safe to use in local blocks: In some cases - look AddSpecialEffect function for more information.

native AddSpellEffect takes string abilityString, effecttype t, real x, real y returns effect
I still don't know what abilityString ever is and what are we supposed to put in that. Please link me more information about this function.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required.

native AddSpellEffectById takes integer abilityId, effecttype t,real x, real y returns effect
Creates the special effect in point with coordinates (x;y) with Z = 0 using the model file from the Object Editor field of type t from the ability, unit or buff (works with all these types, though the name states it's ability-only function) with raw code abilityId. If this field has more than one effect inside, it will only create the first effect stated in the field, ignoring all others.
I have no idea how this operates with EFFECT_TYPE_LIGHTNING. Maybe some of you have that idea?

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required.

native AddSpellEffectByIdLoc takes integer abilityId, effecttype t,location where returns effect
Creates the special effect in location where with Z = 0 using the model file from the Object Editor field of type t from the ability, unit or buff (works with all these types, though the name states it's ability-only function) with raw code abilityId. If this field has more than one effect inside, it will only create the first effect stated in the field, ignoring all others.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required.

native AddSpellEffectLoc takes string abilityString, effecttype t,location where returns effect
I don't fully know how it works because I don't know what am I supposed to put in abilityString field.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required.

native AddSpellEffectTarget takes string modelName, effecttype t, widget targetWidget, string attachPoint returns effect
I don't fully know how it works because I don't know what am I supposed to put in modelName field.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required.

native AddSpellEffectTargetById takes integer abilityId, effecttype t, widget targetWidget, string attachPoint returns effect
Attaches the special effect to the attachment point attachPointName of the target widget, using the model file from the Object Editor field of type t from the ability, unit or buff (works with all these types, though the name states it's ability-only function) with raw code abilityId. If this field has more than one effect inside, it will only create the first effect stated in the field, ignoring all others.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required.

native AddUnitAnimationProperties takes unit whichUnit, string animProperties, boolean add returns nothing
Adds the animation tag animProperties to the unit whichUnit. For example, adding animation tag "alternate" will make the unit play "stand alternate" animation instead of just "stand". Boolean add determines if the tag is added or removed.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required. I don't know if adding the animation tag desyncs or not.

native AddUnitToAllStock takes integer unitId, integer currentStock, integer stockMax returns nothing
Adds a unit of the type unitId with current stock of currentStock and max stock of stockMax to all shops in game. Some issues with default Blizzard initialization and that function were met. See this thread for getting details.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required. Most likely adding an item or unit to shops locally will desync but to be sure in that I need to test it properly.

native AddUnitToStock takes unit whichUnit, integer unitId, integer currentStock, integer stockMax returns nothing
Adds a unit of the type unitId with current stock of currentStock and max stock of stockMax to the specific shop whichUnit. Some issues with default Blizzard initialization and that function were met. See this thread for getting details.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required. Most likely adding an item or unit to shops locally will desync but to be sure in that I need to test it properly.

native AddWeatherEffect takes rect where, integer effectID returns weathereffect
Adds the weather effect with id effectID to the rect where.
To understand more about weather effects nature, I advise to read Ammorth's article about weather effects on wc3c.
To get an idea on how to add your own weather effects, you may read CryoniC's article about custom weather effects on wc3c.

• Safe to use in local blocks: No

native AdjustCameraField takes camerafield whichField, real offset, real duration returns nothing
Changes one of the game camera's options whichField by offset over duration seconds.

List of possible camera options from common.j

    constant camerafield CAMERA_FIELD_TARGET_DISTANCE       = ConvertCameraField(0)
    constant camerafield CAMERA_FIELD_FARZ                  = ConvertCameraField(1)
    constant camerafield CAMERA_FIELD_ANGLE_OF_ATTACK       = ConvertCameraField(2)
    constant camerafield CAMERA_FIELD_FIELD_OF_VIEW         = ConvertCameraField(3)
    constant camerafield CAMERA_FIELD_ROLL                  = ConvertCameraField(4)
    constant camerafield CAMERA_FIELD_ROTATION              = ConvertCameraField(5)
    constant camerafield CAMERA_FIELD_ZOFFSET               = ConvertCameraField(6)

• Safe to use in local blocks: Yes

native And takes boolexpr operandA, boolexpr operandB returns boolexpr
This function is used as and operator, but for boolexpr types. So, it's same as (operandA and operandB) in code terms.

• Safe to use in local blocks: Unknown

More information about the local block usage safety is required. I honestly have no idea on how boolexprs will react if they are in a local block. Maybe that depends on their content.

native Asin takes real y returns real
Arcsine, one of inverse trigonometric functions. The result is returned in radians in range [-Pi/2;Pi/2].

• Safe to use in local blocks: Yes

native Atan takes real x returns real
Arctangent, one of inverse trigonometric functions. The result is returned in radians in range [-Pi/2;Pi/2].

• Safe to use in local blocks: Yes

native Atan2 takes real y, real x returns real
Arctangent function with two arguments. The result is returned in radians in range (-Pi;Pi].

• Safe to use in local blocks: Yes

native AttachSoundToUnit takes sound soundHandle, unit whichUnit returns nothing
Attaches the sound soundHandle to unit whichUnit. Attaching sound to unit means that more far player stays from the unit to which the sound is attached, less loud the sound plays (the volume of the attached sound decreases with increasing distance).

• Safe to use in local blocks: Yes

Credits: nhocklanhox6 for inspiring me to do it by awesome spells;
PurgeandFire for linking useful information.
Volchachka for helping out with tests.

 

[Flux]

This is a good idea for helping people starting Jass. The problem is that it takes a LOT of work. +rep for you sir.

 

[PurgeandFire]

It might be a bit messy to do it all in one thread. It may be better to use a new wiki or an established wiki, e.g. our affiliate's wiki (thehelper.net):
http://wiki.thehelper.net/Category:Jass_Natives

I filled in descriptions for most of them up until DialogAddButton (and some random functions throughout). If you need any descriptions, you can feel free to use ones from there.

 

[bowser499]

@Purge,
I actually planned to make title post as the header post and link the posts in the topics on it. I'd like to suggest Ralle to make a pseudo-"hosted project" wiki called JASSPedia. I can organize it well with the current structure of hosted projects.

 

[Waffle]

this will be so useful in a few weeks time

thx a bunch!

aww.. just took a look at common.j source.. this gonna be bloody painful..

 

[LeP]

Oh i like this very much. Always wanted to do something like this.
I might write (or pull texts from others together) something about the basic types.
There are many natives with hidden knowledge which is buried deep in forum posts and we should really do something about that.
But i also think as important it is to make this human readable it should be as important to make this computer readable so that maybe
eventually tesh/wurst could use these docs.

 

[edo494]

you can just bunch that into xml very easily even right now

 

[Waffle]

well on some reflection a good format might just be.. the source file itself ( the .j one ) with just comments added.

but yeah, a good aggregate of all the hidden knowledge about jass quirks and rarities is really really valuable. easy parsibility for tools is just a perk

 

[edo494]

I want to say that And is a bit different. It is a lot heavier than just running 2 codes, because you have to evaulate them too(check what they return), so it is essentially the same as giving trigger 2 triggerconditions and calling TriggerEvaluate, with maybe a very tiny little bit of speed advantage of having the functions at rather more easily accesable places(arguments) as opposed to inside your structure(most likely some kind of list or tree, which is complete rubbish for lookup speed)

 

[Chaosy]

As sad and thankless as it sounds, I don't think it's worth the effort.

There are many natives I've never used, which means that I don't know what they do. But pretty much all functions are understood by just reading the name. So I'd suggest that you only post those that aren't so easy to understand. But even then, I don't think it's very useful.

Sorry, just my opinion.

This is a good idea for helping people starting Jass.

Not really. There is a function list included in JNGP. and 95% of the functions speak for themselves. I am pretty sure Createunit(arguments) creates a unit. In the end it'd be easier and better to google since they often provide code examples with the function in question.

This is only useful for those who start with jass without learning GUI because in that case the function names don't explain themselves, but in that case google is still a better way of finding help.

 

[Waffle]

im kind of planning on implementing a subset of jass pretty soon and well if i wanted to say use it for unit testing or stuff all this info about quirks and such is really useful..

also.. for common usage..
i think it is very good to know that the function that "function list included in JNGP" lists as a plausible solution for your problem might not be fully functional.. or might randomly implode ( Player(-1) anybody?,.. set unitX/Y.. etc) or might simply be a def a()ass

 

[bowser499]

@Chaosy,
Go explain the arguments of SetTerrainFog. Not really self-explainable.

 

[Chaosy]

Fair enough. But then again, I didn't that there wasn't a single function that wasn't easy to understand.

 

[bowser499]

First post updated with local block information.
Working on letter 'C'...

 

[WaterKnight]

Local block is the conditional block where GetLocalPlayer() is present in the condition

Imprecise, there are other ways to span local blocks or run code asynchronously.

The Z of the effect created by AddSpecialEffect is not always 0. It is on the terrain height, which is also affected by walkable destructables. So a dummy destructable can be used to create it mid-air. And when you mark it as local-safe, I guess AddHeroXP could be declared likewise because the showEyeCandy does not (should not) really matter. It is not that simple to state that a function could not be used locally. Infact any function would work if you use it that way:

if (GetLocalPlayer() == Player(0)) then
    call func(params)
else
    call func(params)
endif

You just have to pay attention which function when creates traffic that would alternate and force other players into different game states which are noticed by the engine. It's just that preventing it quickly becomes next to impossible to handle in case you use functions which are gameplay-relevant.

AddSpellEffect and consorts of course inherit the local-behavior as they create an effect as well.

No reason why AddUnitAnimationProperties would be local-unsafe. AddUnitToAllStock naturally is. AddWeatherEffect is similar to lightnings or ubersplats, they got their own id stack, not ref-counted, no reason to desync unless you cause a crash.

And is not local-safe for it runs new threads with the contained function pointers on use. Also, it's is an agent in the common stack. But what may work under circumstances is:

if (GetLocalPlayer() == Player(0)) then
    call TriggerAddCondition(trig, And(boolexpr1, boolexpr2))
else
    call TriggerAddCondition(trig, And(boolexpr3, boolexpr4))
end

Have you tested AttachSoundToUnit local-safety in conjunction with KillSoundWhenDone and the like?