NWN open source

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, 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 objectivesEdit

OSRS follows the following philosophy.

  1. OSRS will respect the NWN EULA.
  2. Open source button
    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 goalsEdit

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 conventionsEdit

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 rulesEdit

  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 conventionsEdit

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 scriptsEdit

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

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.)

Community content is available under CC-BY-SA unless otherwise noted.