Topics

[full discussion and detailed documents here]

I've noticed that the length of our discussions and the documents themselves seems to have made people reluctant to release their modules in fear of violating these guidelines.

And I agree the perceived amount of rules seems quite high at first. That's why I've written a short, easy-to-read summary of the guidelines that will hopefully encourage more people to release their modules.

NOTE: This is a summary, you can find the full discussion and detailed documents here.

SCRIPT MODULE GUIDELINES

Please note that we agreed on these guidelines to bring all modules in line and to ensure that they work smoothly together. You are encouraged to follow them, but these are merely suggestions and we'd rather you publish your module as-is than not at all.
If you just want to make sure that your module doesn't interfere with others, pay special attention to the suggestions in bold.

PROGRAMMING CONVENTIONS
Module
- Unique name: Check this Tech Archive and the AGS Wiki
- Name at least 3 characters long (for auto-completion), as short but as descriptive as possible
- Name in camel notation: MyModule

Definitions/Macros
- Name in uppercase: #define MYMACRO 500
- If in module header, prefix module name: #define MyModule_MYMACRO 500

Variables
- If declared in function (dynamic): Lowercase name
- If declared in module script (static): Camel notation name
- If declared in module script & imported into header (global): Module prefix & camel notation name

Code: ags

// module script

int MyModule_MyVariable; // global
export MyModule_MyVariable; // global

int MyVariable; // static

function do_stuff() {
  int my_variable; // dynamic
}

Code: ags

// module header

import int MyModule_MyVariable; // global

Functions
- If only used in module script: Camel notation name
- If imported into script header (global): Module prefix + camel notation name
- Grouping of functions by using static member functions is recommended:

Code: ags

// module header

struct MyModule { // IMPORTANT: The bracket needs to be placed directly after the struct name
  import static function MyStaticFunc();
  //...more functions here
};

Code: ags

// module script

static function MyModule::MyStaticFunc() {
  // do stuff
}

Code: ags

  // some script

  MyModule.MyStaticFunc();
  // typing "MyModule." will pop up all available functions

GUIs ^*3
- GUI name: Uppercase module name+number: MYMODULE1 (Truncate module name if necessary)
- GUI control name: Prefix name of its GUI: MYMODULE1_Jump

Enums
- Enum name in camel notation, prefixed with ModuleName
- Value names in camel notation, prefixed with e+ModuleName ^*4

Code: ags

enum MyModule_MyEnum {
  eMyModule_Value1,
  eMyModule_Value2,
  eMyModule_ValueN
};

Structs
- If defined in module script: Lowercase name

Code: ags

// module script

struct mystruct {
  int MyInt;
  char MyChar;   
  short MyShort;
  float MyFloat;    
  String MyString; // AGS v2.71+
};

- If defined in module header: ModuleName + camel notation name

Code: ags

// module header

struct MyModule_MyStruct {
  int MyInt;
  char MyChar;   
  short MyShort;
  float MyFloat;    
  String MyString; // AGS v2.71+
};

- For instances of structs the variable name rules apply
- Struct members:

Code: ags

// module header

struct MyModule {

  // Public member variables
  int MyVar;
  writeprotected int MyReadOnlyVar;

  // Public member functions
  import function MyFunc();

  // Public static member functions
  import static function MyStaticFunc();
       
  // Private member variables (only accessible by other members)
  protected int my_var;

  // Private member functions (only accessible by other members)
  import protected function my_func();
}

Module version info
- Put definitions in module header for dependent modules to check for:

Code: ags

// module header

#define MyModule_VERSION 200 // current version
#define MyModule_VERSION_200 // provides v2.00 functionality
#define MyModule_VERSION_100 // provides v1.00 functionality

DOCUMENTATION
- Plain text or html file for maximum compatibility
- Same name as module
- Should contain:
  - Module name
  - Module version
  - Authors
  - Description of what module does and what it can be used for
  - Dependencies on other modules / plugins / AGS versions
  - List of all public functions and variables and how/where they are used
  - Revision history / Changelog with date
  - License: Free for non-commercial AND commercial use? Credit required or optional?
    We suggest the MIT license:

/ Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
// DEALINGS IN THE SOFTWARE.

PUBLISHING
- Download should include at least the .scm module file & documentation
- A demo game is optional
- Zip format preferred for maximum compatibility
- Post the announcement thread in the main Technical Forum
- Thread subject line: "MODULE: MyModule v1.00 - Optional short description"
- State which version of AGS it was written for
- Moderators will move the thread to the Technical Archive at the appropriate time
- Finally, add your module to the list of script modules in the AGS Wiki


<sub>^*3 This is my idea, I don't think we reached a consensus yet? What do you think?
^*4 e moved to front to avoid value names popping up when typing the module name



Changes:
- btnJump -> Jump
- Added note about placing bracket direclty after struct name
- Fixed full discussion link (Thanks SSH)
- Removed reference to post below
- Added link to Candle's upload space
- Removed link to Candle's upload space
- Fixed AGS Wiki links
- Removed link to Neole's upload space
- Updated code sections</sub>