Open Source Rule Set

Open Source Rule Set logo

The Open Source Rule Set (OSRS) provides a set of standardized script-only features for use in player-created NWN modules. These OSRS features are organized into OSRS builds. At the present time, OSRS has released a test module for OSRS build 0. OSRS had maintained a forum bulletin board at forum.nwn2wiki.org, but that forum is no longer accessible.

This set was formerly known as NWNWiki Rule Set (NRS) or Wiki Rules. The new name emphasizes "open source" and distances itself from any particular deployment platform (i.e. NWNWiki).

Since NWN2 scripting was expected to be exportable from existing NWN scripting content, OSRS had intended to port to NWN2 upon that game's release, but no progress has yet been made towards that goal.

Philosophy and objectives

OSRS follows the following philosophy.

1. OSRS will respect the NWN EULA.
2. 
   OSRS will follow the open source philosophy and the open source definition as specified here and in annotated form here.
   1. OSRS must allow free redistribution of its source code.
   2. OSRS must allow modifications and derived works.
   3. OSRS must preserve the integrity of of the author's source code.
   4. OSRS will not discriminate against persons, groups, or fields of endeavor.
   5. This OSRS license is not specific to any non-BioWare products. An OSRS release can not require particular hak paks or imports to be in use.
   6. The OSRS license must not restrict other software. OSRS should not attempt to restrict other types of software from working successfully.
3. All OSRS rights are granted to all recipients of the OSRS.
4. OSRS will produce, provide, and expand upon a reliable set of pre-scripted generic features for NWN modules to serve as the basis from which designers can write their stories.
5. OSRS will attempt to collect and reconcile interesting scripts into a standard open-source module or importable .erf distribution. OSRS will attempt to secure and include source code from all authors.
6. OSRS scripting must gracefully handle errors and exceptions.
7. OSRS will strive to treat all users like developers.
8. OSRS will encourage user input and will not restrict the free flow of information.
9. OSRS assumes that it is more desirable to module designers who wish to use a "generic" solution approved by "most" people "most" of the time, and arrive at a public consensus.
10. OSRS assumes that all non-PC activity within a NWN module occurs as the result of scripts being executed in response to events.
11. OSRS will allow competing OSRS builds to exist within its environment. Different builds may utilize different features. An optimized build of another version might exist.
12. Each OSRS script will be documented with a summary description at the beginning of its article in NWNWiki.
13. A feature submission will acknowledge the open source license in the feature summary.
14. A single file that summarizes a package submission in the form of one large comment should also be part of a submission. This documentation will be the initial posting of an OSRS feature on NWNWiki.

Technical goals

OSRS strives for the following technical goals.

1. An OSRS feature submission must be general in nature and not specific. If the submission references specific objects that might not exist in a general module, then the feature is probably too specific. Features which are too specific to a module should be removed from the OSRS code. Specific features only apply to specific settings and do not apply to any general module.
2. All scripts submitted for inclusion in the OSRS must be executable only by calling ExecuteScript("MyScript",OBJECT_SELF); For example, consider that you wish to integrate a feature script set into OSRS that has 14 scripts. Each of these scripts must be capable of being added into OSRS in the appropriate place by only adding the ExecuteScript() command in the appropriate event.
3. All submitted scripts must have script names that do not overwrite any other existing script within the OSRS, unless they are specifically an upgrade or update of that file. Authors that find themselves editing the functionality of OSRS-owned scripts should alert the developers upon the forum.
4. OSRS will make all generic features switchable via toggle (Boolean interpretation of const int i; so that module designers can disable or enable specific features in one central file, namely osrs inc.
5. All submitted scripts should have ample commenting. A feature submission should be commented so that others can improve upon it.
6. A feature submission should not contain any non-scripting custom content, such as music, graphics, hak paks, or conversations. OSRS focuses on building a general set of scripts for any module. Scripts enforce rules that a designer would like to enforce in his module.
7. The submission settings for a feature must execute in the module's OnModuleLoad event.
8. An OSRS package submission must not contain any non-scripting files. All scripts should assume to be operating upon NWN/SOU/HOTU combination and should only rely upon objects/resources in such an installation.
9. OSRS will only accept script submissions, consisting of standard scripts, conversation pre-conditional scripts, or include files that are used by one of these two. Standard scripts are those scripts that have a main() function. Conversation pre-conditional scripts are those scripts that have a StartingConditional() function.
10. Submitted scripts should handle all errors and digest them without crashing the module. Any external non-scripting material may be used in a particular implementation, but it must work properly without that particular implementation. This will allow OSRS to quickly disable/remove features that are troublesome.
11. OSRS requires that all feature submission settings to be switchable. OSRS will configure its system only through switches. All features must have at least one toggle: the ability to completely turn that feature on or off in a module. Using OSRS with all features toggled off should have the same functionality as a standard NWN/SOU/HOTU module created with the Toolset. Besides the flexibility this allows module designers, it also provides OSRS testers an easy way to verify the functionality of a single feature.
12. OSRS specifically disallows distribution as a hak pak. This code distributed format cannot have its source code updated.
13. This OSRS license is not specific to any hak pak. Some OSRS features may require hak paks to be installed, and they will note so in their requirements.

Naming conventions

A naming convention is a standardized way of providing names to scripts, functions, or variables, typically to help identify their purpose and usage. OSRS strives to follow the guidelines of the NWN Lexicon [1] as much as possible. Additional conventions unique to OSRS are detailed below.

Script naming rules

1. All submitted scripts must have script names that do not overwrite another existing script within OSRS, unless they are specifically an upgrade or update of that file. Authors that find themselves editing the functionality of OSRS-owned scripts should alert the developers in the forum.
2. All OSRS "management scripts" will have the prefix "osrs_". Submitted scripts with this prefix will not be accepted.
3. Following the prefix must be a code indicating the purpose of the script. For example, the OSRS management scripts are further organized as follows.

script purpose	prefix + code
module object scripts	osrs_mo_*
area object scripts	osrs_a_*
creature object scripts	osrs_c_*
door object scripts	osrs_d_*
encounter object scripts	osrs_e_*
item object scripts	osrs_i_*
merchant object scripts	osrs_me_*
placeable object scripts	osrs_p_*
trigger object scripts	osrs_tri_*
trap object scripts	osrs_tra_*

Variable naming conventions

The naming of variables in OSRS should follow a style based on Java conventions.

1. Variable names must be "camelCase" (with lowercase leading element).
2. Variable names must be prefixed with a "c" if the variable is a constant.

Core scripts

The core OSRS scripts consist of one event handler for each event (regardless of the type of object receiving the event) and three include files. The include files are

• osrs_inc, for OSRS use only,
• osrs_inc_user, for module-developer use only, and
• osrs_signatures, a single location for all developer signatures.

The core OSRS event handlers are listed in the following table.

script name event osrs_oacqi OnAcquireItem event osrs_oacti OnActivateItem event osrs_oatc OnAreaTransitionClick event osrs_ob OnBlocked event osrs_oce OnClientEnter event osrs_ocl OnClientLeave event osrs_ocli OnClick event osrs_oclo OnClose event osrs_ocon OnConversation event osrs_ocre OnCombatRoundEnd event osrs_ocsa OnCutsceneAbort event osrs_oda OnDamaged event osrs_ode OnDeath event osrs_odisa OnDisarm event osrs_odist OnDisturbed event osrs_oent OnEnter event osrs_oexh OnExhausted event osrs_oexi OnExit event osrs_ofto OnFailToOpen event osrs_oh OnHeartbeat event osrs_ol OnLock event

script name event osrs_oml OnModuleLoad event osrs_oo OnOpen event osrs_oos OnOpenStore event osrs_op OnPerception event osrs_opa OnPhysicalAttacked event osrs_opde OnPlayerDeath event osrs_opdy OnPlayerDying event osrs_opei OnPlayerEquipItem event osrs_oplu OnPlayerLevelUp event osrs_opresp OnPlayerRespawn event osrs_oprest OnPlayerRest event osrs_opuei OnPlayerUnEquipItem event osrs_or OnRested event osrs_os OnSpawn event osrs_osc OnStoreClosed event osrs_osca OnSpellCastAt event osrs_ott OnTrapTriggered event osrs_ou OnUsed event osrs_ouai OnUnAcquireItem event osrs_oud OnUserDefined event osrs_oul OnUnlock event

For a listing of which events are associated with which objects, see event: class event matrix.
Note: Placeables had an OnClick event added in patch 1.67, but this event has not yet been incorporated into osrs_ocli, the OSRS OnClick event handler.

The above table is ordered by script name to aid the detection of script naming conflicts. To aid the assigning of scripts to objects, the following pictorial guides have been prepared. (Click a guide to enlarge it.)

Guides to assigning OSRS event handlers

OSRS creature events

OSRS door events

OSRS encounter events

OSRS merchant events

OSRS module events

OSRS placeable events

OSRS trap events
(in addition to the base object's events)

OSRS trigger events