1. Updated Resource Submission Rules: All model & skin resource submissions must now include an in-game screenshot. This is to help speed up the moderation process and to show how the model and/or texture looks like from the in-game camera.
    Dismiss Notice
  2. DID YOU KNOW - That you can unlock new rank icons by posting on the forums or winning contests? Click here to customize your rank or read our User Rank Policy to see a list of ranks that you can unlock. Have you won a contest and still havn't received your rank award? Then please contact the administration.
    Dismiss Notice
  3. The Lich King demands your service! We've reached the 19th edition of the Icon Contest. Come along and make some chilling servants for the one true king.
    Dismiss Notice
  4. The 4th SFX Contest has started. Be sure to participate and have a fun factor in it.
    Dismiss Notice
  5. The poll for the 21st Terraining Contest is LIVE. Be sure to check out the entries and vote for one.
    Dismiss Notice
  6. The results are out! Check them out.
    Dismiss Notice
  7. Don’t forget to sign up for the Hive Cup. There’s a 555 EUR prize pool. Sign up now!
    Dismiss Notice
  8. The Hive Workshop Cup contest results have been announced! See the maps that'll be featured in the Hive Workshop Cup tournament!
    Dismiss Notice
  9. Check out the Staff job openings thread.
    Dismiss Notice
Dismiss Notice
60,000 passwords have been reset on July 8, 2019. If you cannot login, read this.

JASSPedia [Needs your feedback]

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

  1. bowser499

    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 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.
    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"
    • "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.
    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.
    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:
    Code (vJASS):
    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.
    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?
    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.
    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.
    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.
    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.
    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.
    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.
    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 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.

    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;
    PurgeandFire for linking useful information.
    Volchachka for helping out with tests.​
     
    Last edited: Apr 23, 2015
  2. Flux

    Flux

    Joined:
    Feb 6, 2014
    Messages:
    2,334
    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.
     
  3. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,427
    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

    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

    Waffle

    Joined:
    Jul 30, 2013
    Messages:
    271
    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

    LeP

    Joined:
    Feb 13, 2008
    Messages:
    448
    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

    edo494

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

    Waffle

    Joined:
    Jul 30, 2013
    Messages:
    271
    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

    edo494

    Joined:
    Apr 16, 2012
    Messages:
    3,855
    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)
     
  10. Chaosy

    Chaosy

    Joined:
    Jun 9, 2011
    Messages:
    10,611
    Resources:
    18
    Maps:
    1
    Spells:
    11
    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

    Waffle

    Joined:
    Jul 30, 2013
    Messages:
    271
    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():pass
     
  12. bowser499

    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. :)
     
  13. Chaosy

    Chaosy

    Joined:
    Jun 9, 2011
    Messages:
    10,611
    Resources:
    18
    Maps:
    1
    Spells:
    11
    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

    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

    WaterKnight

    Joined:
    Aug 18, 2009
    Messages:
    4,033
    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
        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?