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. We have recently started the 16th edition of the Mini Mapping Contest. The theme is mini RPG. Do check it out and have fun.
    Dismiss Notice
  4. Dismiss Notice
  5. The Highway to Hell has been laid open. Come along and participate in the 5th Special Effect Contest.
    Dismiss Notice
  6. 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.

GPAG - GUI Proper Application Guide

Discussion in 'Trigger (GUI) Editor Tutorials' started by IcemanBo, Feb 7, 2017.

  1. IcemanBo

    IcemanBo

    Joined:
    Sep 6, 2013
    Messages:
    6,222
    Resources:
    22
    Maps:
    3
    Spells:
    11
    Template:
    1
    Tutorials:
    4
    JASS:
    3
    Resources:
    22
    GPAG - GUI Proper Application Guide


    1. Introduction

    GPAG defines uniform standards and conventions that we strive to apply in our GUI submissions.
    The goal is to come on the same page for coding style, and to ensure clean and readable triggers.​


    2. Naming Conventions

    2.1. Prefix

    To avoid name collision each system is asked to define a PREFIX. The spell/system PREFIX is a constant name and should be resource descriptive. For example, if it's a fireball spell, the prefix might be "FIREBALL" or "Fireball". It's up to you, if you decide to write the prefix LIKE_CONSTANTS, or like VariableNames -- choose what you prefer. The PREFIX length should be at least 3-4 characters long, or even more, to ensure some uniqueness. Also, no matter what variables your system creates, all of them must be advanced by the PREFIX and an underscore _.​

    2.2. Variables


    VariableNames start with a capital letter and also each new word is indicated by a new capitalitzed letter. The name itself must be descriptive for the variable's purpose. - What does this mean? When you work with temporary variables it's totally okay to give generic names, like: "Unit, String, Real, Point". However, when the variable usage is specified, then its name should be specified as well. So then, the name style changes from generic to specific. Here are examples:
    Generic/Temporary usage
    • Unit

    • Real
    Specific Usage
    • Caster/Target

    • Damage/Distance

    The final variable name, combined with the prefix, looks like: PREFIX_VariableName:

    FIREBALL_Caster
    FIREBALL_Duration

    2.3. Constant Variables


    CONSTANT_VARIABLES are exclusivly written in capital letters and each new word is seperated with an underscore _ . Constant variables are only set once, usually after map loading, and the capital letters indicates to never change the variable's value. They are usually used to define some system default datas to get the system working.

    The final variable name for constants, combined with the prefix, looks like: PREFIX_CONSTANT_VARIABLE.

    FIREBALL_ABILITY_ID
    FIREBALL_ORDER_ID

    2.4 Triggers


    The same principle from variables applies to your triggers. The trigger's name will result in: PREFIX TriggerName.
    The TriggerName should be descriptive, similar like variable names. Example names for triggers for a fireball spell:

    FIREBALL Setup
    -> here the user can find everything config related.
    FIREBALL Cast
    -> this is the trigger with obivously "A Unit Casts" event.
    FIREBALL Periodic
    -> this trigger runs periodically. Probably used for fireball movement.​

    2.5 Object Data


    For object editor data, except for items and doodads, there exists a field named "Text - Editor Suffix". This field comes handy when your system uses custom object data, so you can use it to put in your PREFIX there. The idea behind is that the user will always be able to easily distinguish which object data belongs to which system or spell.

    There are cases though, where it doesn't really make sense to use a object suffix. For example, when we import a "Fireball" spell and the prefix is "Fireball".
    The name result in object editor would look like "Fireball (Fireball)", so you see that it doesn't really help anyone to distinguish data.
    However, when the object editor data differs from the prefix, then using "Text - Editor Suffix" is indeed often helpful and asked for.​


    3. Documentation

    Documentation is something good and each coder's friend. However, only when done correctly. We don't need to know uninteresting details like
    "Here I set my integer variable." We can see that! Instead, it's much more important to understand why/for what you do something. We want to understand the purpose.
    You usually don't need to document each single line, but instead, try to describe a whole code block in a concise manner, always when you think that some information could be helpful at that point. The bigger the code gets, the more benefits you will have from comments.​


    4. Configuration

    Configuration needs to be seperated from the system's core code. That's mostly done with putting all config-related parts into a seperate trigger.
    Usually, things like:" Damage, Size, Durations, Radius, Effects, ..." are meant to be configured. The user doesn't care about the system's core code and he only wants to know what he should change to get the code properly working. Therefore, also the configuration always requires a proper Documentation to ensure that the user easily can follow and understand everything related.​


    5. Last Word

    We prefer following GPAG, but at same time we won't blindly enforce it. So in case your personal standard sligthly differs from GPAG, it may be accepted as well, as long as clean and readable code is ensured. In case of uncertainties feel free to inquire about it with the respective moderators in Staff Contact or discuss it here in this thread.​
     
    Last edited: May 14, 2019
  2. Chaosy

    Chaosy

    Joined:
    Jun 9, 2011
    Messages:
    10,693
    Resources:
    18
    Maps:
    1
    Spells:
    11
    Tutorials:
    6
    Resources:
    18
    Prefixes:
    Firstly, I do not think 4 characters+ is needed. After all, with just two characters (Fireball > FB) you still have 729 possible combinations. So in theory, 729 GUI spells and systems. I mean sure you might be a tad unlucky and get a duplicate, all I am saying is that it's not that big of a deal. Also, I think consistency is more important than how you actually name them. So you don't do something like:
    FB_a
    FB_b
    FiBa_c
    FiBa_d

    My last point goes for variables as well. As long as all your variables are the same, all fine.


    Constant variables:
    This may make sense for someone who likes jass, but I do not think this is something to be enforced for everyone.

    Suppose I agree with everything else.
     
    Last edited: Jul 30, 2019
  3. KILLCIDE

    KILLCIDE

    Administrator

    Joined:
    Jul 22, 2015
    Messages:
    3,505
    Resources:
    20
    Models:
    2
    Icons:
    10
    Spells:
    7
    Tutorials:
    1
    Resources:
    20
     
  4. IcemanBo

    IcemanBo

    Joined:
    Sep 6, 2013
    Messages:
    6,222
    Resources:
    22
    Maps:
    3
    Spells:
    11
    Template:
    1
    Tutorials:
    4
    JASS:
    3
    Resources:
    22
    "2 letters" -> " much combinations"
    --
    well, in theory if you count the systems how many you import, then it might be enough. But practicaly also often same letters are chosen, and some aren't (like "ZZ", "YY", .. etc you probably won't find often)

    Yeh, this "constant" style in GUI is/was practicaly not often used, but when I tried it out, it was really a bit better to read in the GUI core code, because one could immediatly see that
    this variable is not instance-specific, but just a default constant.
     
  5. KILLCIDE

    KILLCIDE

    Administrator

    Joined:
    Jul 22, 2015
    Messages:
    3,505
    Resources:
    20
    Models:
    2
    Icons:
    10
    Spells:
    7
    Tutorials:
    1
    Resources:
    20
    Not sure why this is still sitting in Submissions. Approved and stickied!
     
  6. Daffa

    Daffa

    Joined:
    Jan 30, 2013
    Messages:
    7,821
    Resources:
    28
    Packs:
    1
    Maps:
    8
    Spells:
    17
    Tutorials:
    2
    Resources:
    28
    I find Periodic better with Loop instead.
     
  7. JC Helas

    JC Helas

    Joined:
    Oct 19, 2014
    Messages:
    127
    Resources:
    3
    Maps:
    1
    Spells:
    2
    Resources:
    3
    In system part should we document it too? Or maybe only those part which need to explain because we have our own acceptable style?
     
  8. IcemanBo

    IcemanBo

    Joined:
    Sep 6, 2013
    Messages:
    6,222
    Resources:
    22
    Maps:
    3
    Spells:
    11
    Template:
    1
    Tutorials:
    4
    JASS:
    3
    Resources:
    22
    Yes, it's usually useful if the system core code has some documentation. Documentation has a different meaning, depending if it's made in the config, or the core code.

    The core code
    Here documentation is used to understand how the system even works.

    The configuration
    Here documentation is used to understad how to take usage of the system.

    Readabilty and and documentation will help the reviewer, yourself, and just any reader that comes to read your code, and may safe so much time that's invested to understand it in future.