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. Don’t forget to sign up for the Hive Cup. There’s a 555 EUR prize pool. Sign up now!
    Dismiss Notice
  4. The Hive Workshop Cup contest results have been announced! See the maps that'll be featured in the Hive Workshop Cup tournament!
    Dismiss Notice
  5. The results are out! Check them out.
    Dismiss Notice
  6. The poll for Hive's 12th Concept Art Contest is up! Go cast your vote for your favourite genie!
    Dismiss Notice
  7. The raddest synthwave tracks were chosen - Check out our Music Contest #12 - Results and congratulate the winners!
    Dismiss Notice
  8. 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.

[JASS/AI] Simple JASS tutorial - for beginners

Discussion in '"Graveyard"' started by BlueSaint, May 5, 2014.

  1. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,427
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    [citation needed]. It was just a guess/rumor that was spread around the mapping community. There isn't any proof of it though.

    That feels a little off-topic. I would probably remove it. It seems more like you're forcing your agenda in this part. Ultimately, it is up to you, but it is best to keep everything relevant to the topic at hand: learning JASS! :)

    After all, you have a section that later explains your technique. It is a bit weird to have that in your introduction.

    ---

    "Our First JASS Trigger" starts off rather quickly. When someone converts a blank trigger, they'll end up with a trigger action and an initialization function. But you changed it to a more "modern" trigger style. However, the issue with it is that you end up jumping to a whole bunch of new concepts at once: locals, returning a value, nulling, natives, etc.

    Generally, JASS tutorials are heavily dependent on structure. You must give simple examples to start off so that people get the concept down. From there, they can move on to creating "efficient" or "modern" JASS-type codes. See Ghan's tutorial: it starts off by explaining every aspect of an empty converted trigger. Or look at GhostWolf's, his starts off with an isolated function and goes through the process of explaining the entirety of what functions are about.

    Even though we use combined conditions and actions in our current scripts, GUI users won't necessarily understand that right away. They might question: "why are our actions placed inside condition functions?" You have to make sure you explain that properly.

    I'm not sure what you mean by "more modifiable". It'd probably be better said as "it adds additional features to JASS" (which is why it needs its own syntax checker).

    jassnewgenpack 2.0 already has the latest jasshelper, so you don't have to do any of that. That used to be a required step because the JNGP on wc3c had an older jasshelper, so people had to replace it with the latest jasshelper 0.A.2.B. 2 years ago, Mag uploaded the "standard" updated version to our tools section "JassNewGenPack 5d", and that problem has generally subsided since then. JNGP 2.0 also came out, which has the latest jasshelper, so that step isn't necessary (as long as they download it from our site or moyack's version).

    You have to be sure to both show and explain. You showed scopes and an "initializer", but you didn't mention it in the text. You have to explain what scopes are used for and what initializers are. It is good that you explained encapsulation (private/public), but I might add a little more information on it. Right now, you show what causes an error, but you need to give it some context in order for it to make sense. For example:

    "Normally, JASS won't allow you to have two functions with the same name. Scopes (and libraries) allow you to encapsulate them by adding the keyword "private" or "public". This will allow you to have common names such as "Act", "Init", etc. without worrying about colliding with other functions' names. However, those keywords have additional purposes: "private" will prevent the function from being called outside the scope. "public" will allow the function to be called outside the scope, but you must add the scope name as a prefix, followed by the underscore."

    Then you could provide examples or whatever. That is a rough example of a thorough explanation. There is quite a bit of information that can be covered. (you did a good job of covering the "public" keyword though, so you don't need to change much of that)

    It might be better if you explain a little bit more about how libraries are useful. This is how I always thought of it: in normal JASS, if you wanted to call a function from any trigger, you would have to place that function in the map's header. That can be inconvenient, unorganized, and it can clutter the map header really quickly. vJASS's libraries move those functions to the top of the script for you, allowing you to use them anywhere!

    Then you could explain a bit more on what "requiring" does. It allows you to "order" libraries, so if you want to use a function from library "A" in library "B", you simply need to add "requires A" to library B's declaration.

    Change the word "define" to "assign".

    This section suffers a bit from information overload. So many concepts are thrown out so rapidly, but the user won't know how to do anything with any of it. He will know what a struct looks like, but where should he use it? What is it used for? What are instances? What does it mean to overwrite the "create" method?

    Structs are a rather large topic, sufficient for an entire tutorial. There is so much to them.

    You should explain what rawcodes are. GUI users won't be familiar with it (most likely).

    You should go over loops in a much earlier section. Just the general syntax of looping. In GUI, you're familiar with loops (e.g. 1 to 10), but JASS behaves differently, particularly with the use of
    exitwhen
    . At this point, users might not know how to do a simple loop, so you should go over that first before showing a first of group loop.

    endif -> endloop

    Also, in the first of group loop section, you should mention that it empties the group. If you want to preserve the units in the group, you should use ForGroup (in general). If you just need to perform an instant action over some group of units (where you don't need the units stored later), you can use the FirstOfGroup loop.

    You should show the syntax of elseif. It will be a new feature to GUI users, and since it has its own syntax, you should include it in the example.

    It is good that you made a section for it. I think you should link to this section or write "see below" from the GetSpellAbilityId() == 'AHtc' line, otherwise readers might be confused.

    You should change the last part to Condition(function groupFilter). Yours won't cause an error in vJASS (because jasshelper will automatically wrap it in Condition() for you. it is a weird feature), but it will cause an error in regular JASS.

    ------

    Ultimately, I agree with edo and death's reviews. You try to cover everything, but by being too ambitious with the topic, you end up having only a little information in each section. It is nice as a "light" tutorial, or an overview, but IMO this wouldn't help new JASSers much. It would serve as a reference for beginner JASSers so they can look back and see how to do things.

    If I were you, I'd try to just stick with basic JASS or basic vJASS. Doing both is a ton of information.

    Sorry if this review was a little harsh at times. As such, I want to let you know that this tutorial still has a lot of redeeming qualities. The layout of the tutorial is great and pretty. The code examples are pretty good. Sometimes I like that it is brief. It serves as a good reference to check back on how to use particular features. In fact, I used a similar tutorial when I was learning vJASS. The manual is rather dense and technical, so I just needed a quick overview so I could get the gist of things (it was this tutorial to be exact).

    Still, this tutorial needs to decide what it wants to be. Does it want to be a reference? Does it want to be an in-depth tutorial? Does it want to cover JASS or vJASS (or both?)? Is it for moving on to JASS, or is it for mixing JASS with GUI? It is important for tutorials (and any writing in general) to have a clear focus. Being too broad and far-reaching is usually detrimental.
     
  2. BlueSaint

    BlueSaint

    Joined:
    Jun 18, 2012
    Messages:
    2,771
    Resources:
    3
    Tools:
    1
    Spells:
    2
    Resources:
    3
    That wasn't too harsh at all ^^ if someone is to learn from this, it needs to be as good as possible :)

    Atm I'm doing multiple projects (including the timelined zephyr contest entry) and have work in real life too so update might take a bit long, but please don't but this to graveyard in that time, I've put a lot of time to this.

    And thanks for a big review :)
     
  3. Chaosy

    Chaosy

    Joined:
    Jun 9, 2011
    Messages:
    10,611
    Resources:
    18
    Maps:
    1
    Spells:
    11
    Tutorials:
    6
    Resources:
    18
    +1 for amazing layout and structure

    however "for beginners" doesn't really suit in my opinion since the tutorial is a f*cking bible I don't know about you but structs are not simple, nor easy to learn so I don't why it is a section in the first place. Same with text macros.

    edit: libs shouldn't be there either since they don't give any benefit for starters. I feel kinda the same way about scopes.

    edit2: I think a tutorial for starters should include:
    1. creating variables
    2. calling functions
    3. JNGP function list
    4. if blocks
    5. loops

    you're done, with that knowledge you can start to make progress in a map, go and create a SPRPG so you wont have an issue with MUI.

    edit3: wow, I sound so negative take it with a grain of salt xd
     
    Last edited: Jul 14, 2014
  4. BlueSaint

    BlueSaint

    Joined:
    Jun 18, 2012
    Messages:
    2,771
    Resources:
    3
    Tools:
    1
    Spells:
    2
    Resources:
    3
    I replaced the GUI/JASS chapter with JASS efficiency tips chapter. Thanks to Malhorne for helping with it.

    I've not yet fixed the previous chapter which pnf highlighted, it's hard to fix thing instead of just creating.
     
  5. Mythic

    Mythic

    Joined:
    Apr 24, 2012
    Messages:
    7,728
    Resources:
    102
    Models:
    87
    Icons:
    4
    Maps:
    3
    Spells:
    6
    Tutorials:
    2
    Resources:
    102
    Good job, the length and content of this tutorial is incredible.
     
  6. BlueSaint

    BlueSaint

    Joined:
    Jun 18, 2012
    Messages:
    2,771
    Resources:
    3
    Tools:
    1
    Spells:
    2
    Resources:
    3
    I'm glad you liked it :)
     
  7. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,427
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    • About the Just Another Scripting Syntax thing, it is just a rumor. Whoever wrote that Wiki page didn't cite it. It was a joke that spread over the years, but there is no source. I'd rather not perpetuate that rumor. :p
      So just change:
      To:
      Or you can say something like "It is rumored to stand for Just Another Scripting Syntax".
    • *Release data from objects. Or rather, it "removes memory related to an object". It doesn't actually deal with the variable, since variables are just pointers to objects in memory.
    • Nice diagram. :D
    • You might want to rephrase that a little. Maybe:
      "As a side note, JASSers often put all their "Actions" into the condition function, instead of creating one function for a condition and one function for actions. It saves handles and is faster."
    • Add: "this will outprint message lol after 0 seconds of game-time has elapsed." It is a nice summary of the trigger as a whole.
    • In the "Scopes" section, add a sentence to explain the keyword
      initializer
      .
    • A zebra is a zebra. Maybe change it to something along the lines of: instance is an individual struct "object", created through .create() or .allocate().
    • A lot of people get confused about "thistype" when they're learning vJASS. Perhaps add a sentence saying that you can also write "myStruct". ("thistype" was originally intended for modules, but it is useful since it allows you to easily change the struct's name in one location).
    • Perhaps in "Basics of JASS", you should add a section that teaches you how to look up a function using TESH's function list. Most people have to use it at some point to become familiar with the natives, and it really helps you find what you're looking for (or if you are converting GUI to JASS, it helps you find the native equivalents).
    • In "Loops":
      Remove the "endif". Also, your function
      GetStrength
      has a typo -> endfunciton should be endfunction
    • In "Loops", you should add a sentence to explain "exitwhen". It is a new concept for GUI users.
    • This is a little bit of a weird tip. I think you should separate it into "Use arrays when you can" and "Avoid useless "wrapper" BJ's".
    • Pre-calculating for loops - that is true, but the example you gave is a little too vague.
    • PUI isn't for everyone. I think you should probably remove that section, or just change it to "Use Unit Indexers". But that is just fluff. I don't think you need to have that there.
    • Vexorian's table doesn't use gamecache. That is the pre-1.23 version. The post 1.23 version uses hashtables. Bribe extended Vexorian's "Table" to integrate a struct interface for all the hashtable natives.
    • I wouldn't recommend 5.9. It is just bad for beginners. Trying to make your own custom allocation is mostly useless (er.. struct extends array is very useful, but not in the way it is commonly used), and new JASSers won't understand it. It is okay to recommend Alloc, but IMO, it is better to just stick with regular allocation. If they find it to be insufficient, or if they are curious as to why so many resources have "struct extends array", then they can go and learn about custom allocation/deallocation.

    Well, that is it for now. It is definitely getting better. ;) I suppose this could be nice as a general overview of things.
     
  8. BlueSaint

    BlueSaint

    Joined:
    Jun 18, 2012
    Messages:
    2,771
    Resources:
    3
    Tools:
    1
    Spells:
    2
    Resources:
    3
    Those are good points, I'll update it when I've got time.

    Avoid native calls is a good suggestion, but I should change it to "avoid native calls in looping functions". Ye it might sound weird tip but the thing is native calls have their impact.

    I'll never get this approved at this rate >_< I've got high school starting next week so the next update comes this week or after a long time ..
     
  9. PurgeandFire

    PurgeandFire

    Code Moderator

    Joined:
    Nov 11, 2006
    Messages:
    7,427
    Resources:
    18
    Icons:
    1
    Spells:
    4
    Tutorials:
    9
    JASS:
    4
    Resources:
    18
    Nah, these are mostly the last stuff. My first review asked for a lot of revision and stuff. Since then, you've added more topics--so I had to add more to my second review. If you add more topics, it might require a 3rd review. But if you focus on fixing what I mentioned, it should be good to go!
     
  10. edo494

    edo494

    Joined:
    Apr 16, 2012
    Messages:
    3,855
    Resources:
    5
    Spells:
    1
    JASS:
    4
    Resources:
    5
    if you never call native function, you never get to do anything. Also impact of natives is very small, you can even call wrapper with no visible inpact
     
  11. BlueSaint

    BlueSaint

    Joined:
    Jun 18, 2012
    Messages:
    2,771
    Resources:
    3
    Tools:
    1
    Spells:
    2
    Resources:
    3
    "Native functions are super useful and without them you basically couldn't do anything visual or physical in-game."

    Ye it is. I just though that if someone is to learn from this tut, he'd better now all these little things told in ch 5.

    But the last thing is so geeky I added optional tag to it. But I added it cuz by default structs do security checks on whether they've exceeded the array limit. Jass starter might not know this but now he does.
     
  12. IcemanBo

    IcemanBo

    Joined:
    Sep 6, 2013
    Messages:
    6,181
    Resources:
    22
    Maps:
    3
    Spells:
    11
    Template:
    1
    Tutorials:
    4
    JASS:
    3
    Resources:
    22
    Haven't read all posts now, but I would wanna know if you're still caring for it?

    It's not really "simple" jass tutorial. And also covers vjass. I think the goal should be made clear of what it is about, so you and user can more easy know what to expect.
    Macros and other vjass tequniques are not really "basic" jass. There are some other things are could be changed or improved, but we first would need to know what you're currently thinking about it.

    I would probably suggest to focus only on some points, which you think are very important.
     
  13. BlueSaint

    BlueSaint

    Joined:
    Jun 18, 2012
    Messages:
    2,771
    Resources:
    3
    Tools:
    1
    Spells:
    2
    Resources:
    3
    This being from 2014, I would rather write it from scratch. But I don't have time. Maybe after I turn in my mini mapping submission.
     
  14. IcemanBo

    IcemanBo

    Joined:
    Sep 6, 2013
    Messages:
    6,181
    Resources:
    22
    Maps:
    3
    Spells:
    11
    Template:
    1
    Tutorials:
    4
    JASS:
    3
    Resources:
    22
    Yes. I can also undersand wanting to rewrite, at least parts, from scratch. Take time you need and feel free to inform us about progress.
     
  15. IcemanBo

    IcemanBo

    Joined:
    Sep 6, 2013
    Messages:
    6,181
    Resources:
    22
    Maps:
    3
    Spells:
    11
    Template:
    1
    Tutorials:
    4
    JASS:
    3
    Resources:
    22
    Hm, I still also share the thoughts of reqrite some parts, though approaches are pretty good.
    But there's also covered very much info and some specified tequniques, that makes it just harder to maintain for you as it's pretty big.

    But anyways, what's the current state? Are you working on it, or don't you care anymore?
     
  16. BlueSaint

    BlueSaint

    Joined:
    Jun 18, 2012
    Messages:
    2,771
    Resources:
    3
    Tools:
    1
    Spells:
    2
    Resources:
    3
  17. IcemanBo

    IcemanBo

    Joined:
    Sep 6, 2013
    Messages:
    6,181
    Resources:
    22
    Maps:
    3
    Spells:
    11
    Template:
    1
    Tutorials:
    4
    JASS:
    3
    Resources:
    22
    Ok, then I will graveyard it for now.
    Ping us on update. By the way (from pastebin link), I think you should write more noob friendly if you want it to have a "Simple Jass Tutorial For Beginners". They also don't necessairly need to know about byte code, for example.