Lua Submission Rules

[Jampion]

Lua Submissions Rules

The Lua-Submissions forum is a great place to share your custom script for WarCraft III. Here you may submit Lua resources that you would like to share with the community.

Spells or systems which require a demo map or would make the most sense to have a demo map should be submitted to the Spells section. If the code is simple or straightforward enough to be more or less copy & paste, you should submit it here.

If your resource is unfinished or you are unsure whether or not it even works, has bugs or may have already been done before (ie. a Timer system), you should submit it to The Lab for feedback before making your official submission.

Rules

• Global site rules apply here. There are some exceptions, for example double-posting is allowed if you want to bring to attention that you have updated your resource. In this case it makes more sense than editing your last post like you would do in another forum.
• First post in the Thread must contain:
  • A description of the resource
  • The code of the resource and/or a link to the code on github
  • Documentation on how to use the code and/or a link to documentation.
• Code Quality:
  • Resources must function properly before they can be approved. Some resources have a rating which bears in mind efficiency, readability and usefulness.
  • There must be no avoidable memory leaks.
  • Resources must work in multiplayer. The only exception are resources that are only useful in singleplayer. Lua itself is not always synced, so there are constructs that should be used with care:
    • Iteration order within pairs-loops is not guaranteed to be the same for all players, so changing game state within such a loop can lead to a desync.
• Coding Conventions:
  • Naming conventions should follow the standards set by Blizzard:
    • CONSTANT_VARIABLES use all capital letters and words are separated by underscores
    • Public FunctionNames start with an uppercase and each new word is indicated by a new capitalized letter.
    • variableNames should begin with a lowercase letter and each new word separated by a new capitalized letter.
    • As local functions can also be seen as local variables in Lua, you can choose between FunctionNames and variableNames.
  • Indentation is 4 spaces and every block is required to be indented, with the rare exception of indenting the contents of an all-encompassing do-end-block because it's usually obvious then.
  • Your submission must be in its own block, so that local variables are only accessible within your submission.
  • Your submission should not depend on specific module systems or build tools and the public API should be initialized immediately. This makes it easy for your submission to be used with any module system or build tool the user may prefer.
    • For initialization code that contains natives and cannot be run immediately, [Lua] Global Initialization or a similar dependency should be used. Having the user to manually call an initialization function should be avoided if possible.
  • In Lua, arrays start at index 1. If you use arrays as input or output of your global API, the arrays should start at index 1, so the user can apply standard Lua array operations on them.
• Documentation:
  • Dependencies on other resources. (This includes but is not limited to the name of the library, the author, and a link to the library's thread.)
  • Instructions on how to import the script into a map should it not be simply copy and paste.
  • A clear description on how and why the script should be used. Usually this should include an example of the usage.
  • All public API functions must clarify the valid parameter types and the return types. This can be done with comments or having descriptive parameter and function names.
  • All existing functions that may be overridden by your submission must be specified. Additionally, if there are compatibility concerns with other overrides of the same function, they should also be stated.
• An already approved resource may be deprecated if a replacement is obviously superior in many aspects.
• New threads represent new submissions. Do not make a post here unless it is a submission. 1 thread must contain 1 submission. No more, no less. 2 submissions can only be in the same thread if the purpose of one is to add an extra field to the other without making any radical changes to the core. (Add-ons)
• Please do not include your signature in the submitted source. It is distracting and looks tacky.
• If you wish to submit a resource that is not your own, credit must be given and you must have written permission from its author.
• If you port a resource from a different language to Lua please give credit to the original resource. It might also be a good idea to provide a link to it.
• If your resource has not been reviewed or if you do not agree with the reasons a moderator has not approved your resource, feel free to PM another moderator addressing the issue.
• If your resource was moved to the Graveyard, check if the resource followed the above rules. If you would like to update it, feel free to resubmit it or PM a moderator about the situation if you feel that the graveyarding was in error.