- Areas: http://www.alandfaraway.org/docs/Technical/ACR2Areas
- Doors: http://www.alandfaraway.org/docs/Technical/ACR2Doors
- Creatures: http://www.alandfaraway.org/docs/Techni ... 2Creatures
- Placeables: http://www.alandfaraway.org/docs/Techni ... Placeables
- Triggers: http://www.alandfaraway.org/docs/Technical/ACR2Triggers
Conventions & Procedures
Moderators: ALFA Administrators, Staff - Technical
-
ç i p h é r
- Retired
- Posts: 2904
- Joined: Fri Oct 21, 2005 4:12 pm
- Location: US Central (GMT - 6)
Conventions & Procedures
The following articles detail the conventions and the guidelines for creating proper ALFA NWN2 blueprints:
Last edited by ç i p h é r on Tue Feb 06, 2007 5:27 am, edited 3 times in total.
-
ç i p h é r
- Retired
- Posts: 2904
- Joined: Fri Oct 21, 2005 4:12 pm
- Location: US Central (GMT - 6)
Coding Standards
http://www.nwnlexicon.com/compiled/prim ... dards.html
http://www.nwnlexicon.com/compiled/prim ... tions.html
Constants should be entirely uppercase to easily distinguish them from variables.
Script Header Template
This is a sample header template to be used at the top of all custom scripts. For the sake of consistency and to make sure we organize the information in scripts the proper way, we all need to use one. The top half can be used in comment areas of NWN objects as well particularly if the object requires setup or contains configuration information for any system we're building that we need to explain.
Function Prototyping
All functions need to be prototyped. This means they are listed in the appropriate section of the script and can be referenced by any function in that file or outside it. A brief explanation of the function's purpose followed by an explanation of all function arguments and return values should exist in comments directly above the function. Function arguments should be described in terms of what they represent and the range of values they can hold, where appropriate. This will allow any user in the toolset to simply double click on the function name and understand how the function should be used.
Example:
// This function determines if oObject has at least one level of sClassName
// sClassName is a case sensitive text representation of the class
// oObject is the creature to be examined
// Return Values:
// 0 - creature does not have any levels of the class
// 1 - creature has at least one level of the class
int HasClass(string sClassName, object oObject);
Local & Global Definitions
Local constants and functions should be defined in the file that requires them.
Global constants and functions (shared among multiple modules) should be defined in a "library" file which can be included by whatever script requires them.
Library files (non executables) containing constants, functions, and other definitions should be tagged with "_i".
Public & Private Access
All access to data (variables, constants, etc) or functions is assumed to be public unless prefixed with an underscore ("_") character. Information that is public can be accessed by anyone from any file or function. Information that is private should not be accessed by anyone from any file or function outside of the system it's used in. The intent here is to prevent intermediary functions and variables from being misused or corrupted through inappropriate invocations.
Modularity
All systems need to be designed for modularity. This means that systems must be self-contained, must preserve their interfaces across version updates, and be as independant of other systems as possible.
http://www.nwnlexicon.com/compiled/prim ... dards.html
http://www.nwnlexicon.com/compiled/prim ... tions.html
Constants should be entirely uppercase to easily distinguish them from variables.
Script Header Template
This is a sample header template to be used at the top of all custom scripts. For the sake of consistency and to make sure we organize the information in scripts the proper way, we all need to use one. The top half can be used in comment areas of NWN objects as well particularly if the object requires setup or contains configuration information for any system we're building that we need to explain.
Code: Select all
////////////////////////////////////////////////////////////////////////////////
//
// System Name : name of the system or NWN object the script pertains to
// Filename : name of the script file
// $Revision:: $ current version of the file
// $Date:: $ date the file was created or modified
// Author : name of the person who authored the script or changes to it
//
// Var Prefix: unique name comprised of 3 letter system and feature acronyms
// Dependencies: external object dependencies outside of nwscript
//
// Description
//
// Revision History
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
// Includes ////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
// Constants ///////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
// Structures //////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
// Global Variables ////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
// Function Prototypes /////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////
// Function Definitions ////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////All functions need to be prototyped. This means they are listed in the appropriate section of the script and can be referenced by any function in that file or outside it. A brief explanation of the function's purpose followed by an explanation of all function arguments and return values should exist in comments directly above the function. Function arguments should be described in terms of what they represent and the range of values they can hold, where appropriate. This will allow any user in the toolset to simply double click on the function name and understand how the function should be used.
Example:
// This function determines if oObject has at least one level of sClassName
// sClassName is a case sensitive text representation of the class
// oObject is the creature to be examined
// Return Values:
// 0 - creature does not have any levels of the class
// 1 - creature has at least one level of the class
int HasClass(string sClassName, object oObject);
Local & Global Definitions
Local constants and functions should be defined in the file that requires them.
Global constants and functions (shared among multiple modules) should be defined in a "library" file which can be included by whatever script requires them.
Library files (non executables) containing constants, functions, and other definitions should be tagged with "_i".
Public & Private Access
All access to data (variables, constants, etc) or functions is assumed to be public unless prefixed with an underscore ("_") character. Information that is public can be accessed by anyone from any file or function. Information that is private should not be accessed by anyone from any file or function outside of the system it's used in. The intent here is to prevent intermediary functions and variables from being misused or corrupted through inappropriate invocations.
Modularity
All systems need to be designed for modularity. This means that systems must be self-contained, must preserve their interfaces across version updates, and be as independant of other systems as possible.
Last edited by ç i p h é r on Sat Oct 28, 2006 3:40 pm, edited 12 times in total.
-
ç i p h é r
- Retired
- Posts: 2904
- Joined: Fri Oct 21, 2005 4:12 pm
- Location: US Central (GMT - 6)
Version Control
A central version controlled repository for our project has been created. This will host all our global content for PUBLIC distribution and hopefully allow broader participation from the community as well.
https://sourceforge.net/projects/alfa-bmf
SourceForge gives us access to both CVS and Subversion repositories, but we'll be using the latter. All members of the project will have access to the content in the repository and to their assigned tasks, but there will only be one integrator/release coordinator to ensure proper conflict arbitration. Developer access to the repository will either be through a secure shell or a subversion client (Tortoise or Standard clients) which will require configuration by end users. The admin user for this project is generic so it can be accessed by present day or future project administrators and to facilitate the transfer of responsibilities accordingly.
Usage Guidelines
When submitting content to the repository, please make sure you commit your files to the correct directories. If you require a new directory for the system(s) you are working on or have any questions about where/how to store your content, please contact the SVN admin (currently ç i p h é r).
Whenever a change is made to a file, regardless of how small or large the change, please add a comment in the revision history and increment the revision number. This will help us identify the correct file versions of ACR scripts in modules and keep people informed of the changes made.
Do not modify files currently being worked on by other developers UNLESS you have been given permission to do so by the developer or SVN admin. This will limit conflicts and the need for complex arbitration.
Do not delete files committed to the repository UNLESS approved by the SVN admin. Use the SVN Rename function to rename files that require changing and SVN Move to move files that need to migrate from one directory to another. This will allow us to preserve ALL code and never lose anything we've ever written. Deletes must be reserved for files/content we want to remove outright from the repository, though this should be few and far between (there's rarely a need for this frankly).
Always make sure you UPDATE your local repository prior to making edits to a file. This will ensure you're working off the latest versions of the files.
DO NOT commit files to the repository that don't compile or that break the current working version. If you need to update files other than your own, contact the authors or the SVN admin to determine the proper course of action. You'll likely need to make the changes but it's best to be sure your work doesn't conflict with anyone elses first.
A central version controlled repository for our project has been created. This will host all our global content for PUBLIC distribution and hopefully allow broader participation from the community as well.
https://sourceforge.net/projects/alfa-bmf
SourceForge gives us access to both CVS and Subversion repositories, but we'll be using the latter. All members of the project will have access to the content in the repository and to their assigned tasks, but there will only be one integrator/release coordinator to ensure proper conflict arbitration. Developer access to the repository will either be through a secure shell or a subversion client (Tortoise or Standard clients) which will require configuration by end users. The admin user for this project is generic so it can be accessed by present day or future project administrators and to facilitate the transfer of responsibilities accordingly.
Usage Guidelines
When submitting content to the repository, please make sure you commit your files to the correct directories. If you require a new directory for the system(s) you are working on or have any questions about where/how to store your content, please contact the SVN admin (currently ç i p h é r).
Whenever a change is made to a file, regardless of how small or large the change, please add a comment in the revision history and increment the revision number. This will help us identify the correct file versions of ACR scripts in modules and keep people informed of the changes made.
Do not modify files currently being worked on by other developers UNLESS you have been given permission to do so by the developer or SVN admin. This will limit conflicts and the need for complex arbitration.
Do not delete files committed to the repository UNLESS approved by the SVN admin. Use the SVN Rename function to rename files that require changing and SVN Move to move files that need to migrate from one directory to another. This will allow us to preserve ALL code and never lose anything we've ever written. Deletes must be reserved for files/content we want to remove outright from the repository, though this should be few and far between (there's rarely a need for this frankly).
Always make sure you UPDATE your local repository prior to making edits to a file. This will ensure you're working off the latest versions of the files.
DO NOT commit files to the repository that don't compile or that break the current working version. If you need to update files other than your own, contact the authors or the SVN admin to determine the proper course of action. You'll likely need to make the changes but it's best to be sure your work doesn't conflict with anyone elses first.