Discussion in 'The Lab' started by bowser499, Apr 15, 2015.

1. ### bowser499

Joined:
Jul 20, 2009
Messages:
782
Resources:
7
Tools:
1
Maps:
3
Spells:
3
Resources:
7
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
Code (vJASS):
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].

`native AddHeroXP takes unit whichHero, integer xpToAdd, boolean showEyeCandy returns nothing`

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.

`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`
.

`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.

`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.

`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"

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.

`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.

`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.

`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?

`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.
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:
Code (vJASS):
local string modelPath = ""

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

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`

`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?

`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.

`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.

`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.

`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.

`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.

`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.
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.
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 get an idea on how to add your own weather effects, you may read CryoniC's article about custom weather effects on wc3c.

`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
Code (vJASS):
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)

`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.
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].

`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].

`native Atan2 takes real y, real x returns real`

Arctangent function with two arguments. The result is returned in radians in range (-Pi;Pi].

`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).

Credits: nhocklanhox6 for inspiring me to do it by awesome spells;
Volchachka for helping out with tests.​

Last edited: Apr 23, 2015
2. ### Flux

Joined:
Feb 6, 2014
Messages:
2,333
Resources:
28
Maps:
1
Spells:
19
Tutorials:
2
JASS:
6
Resources:
28
This is a good idea for helping people starting Jass. The problem is that it takes a LOT of work. +rep for you sir.

### Code Moderator

Joined:
Nov 11, 2006
Messages:
7,429
Resources:
18
Icons:
1
Spells:
4
Tutorials:
9
JASS:
4
Resources:
18
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.

4. ### bowser499

Joined:
Jul 20, 2009
Messages:
782
Resources:
7
Tools:
1
Maps:
3
Spells:
3
Resources:
7
@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.

5. ### Waffle

Joined:
Jul 30, 2013
Messages:
280
Resources:
0
Resources:
0
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..

Last edited: Apr 15, 2015
6. ### LeP

Joined:
Feb 13, 2008
Messages:
476
Resources:
0
Resources:
0
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.

7. ### edo494

Joined:
Apr 16, 2012
Messages:
3,846
Resources:
5
Spells:
1
JASS:
4
Resources:
5
you can just bunch that into xml very easily even right now

8. ### Waffle

Joined:
Jul 30, 2013
Messages:
280
Resources:
0
Resources:
0
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

9. ### edo494

Joined:
Apr 16, 2012
Messages:
3,846
Resources:
5
Spells:
1
JASS:
4
Resources:
5
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)

### Tutorial Reviewer

Joined:
Jun 9, 2011
Messages:
11,041
Resources:
18
Icons:
1
Maps:
1
Spells:
10
Tutorials:
6
Resources:
18
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.

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.

11. ### Waffle

Joined:
Jul 30, 2013
Messages:
280
Resources:
0
Resources:
0
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

12. ### bowser499

Joined:
Jul 20, 2009
Messages:
782
Resources:
7
Tools:
1
Maps:
3
Spells:
3
Resources:
7
@Chaosy,
Go explain the arguments of
`SetTerrainFog`
. Not really self-explainable.

### Tutorial Reviewer

Joined:
Jun 9, 2011
Messages:
11,041
Resources:
18
Icons:
1
Maps:
1
Spells:
10
Tutorials:
6
Resources:
18
Fair enough. But then again, I didn't that there wasn't a single function that wasn't easy to understand.

14. ### bowser499

Joined:
Jul 20, 2009
Messages:
782
Resources:
7
Tools:
1
Maps:
3
Spells:
3
Resources:
7
First post updated with local block information.
Working on letter 'C'...

15. ### WaterKnight

Joined:
Aug 18, 2009
Messages:
4,035
Resources:
5
Maps:
1
Tutorials:
4
Resources:
5
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:

Code (vJASS):

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:

Code (vJASS):

if (GetLocalPlayer() == Player(0)) then
`AttachSoundToUnit`
`KillSoundWhenDone`