nwn2 howto plugin

7/24/2019 NWN2 HowTo Plugin

1/14

NWN2 Toolset HowTo Plugin CreationJ McMillan

Last Modified: Oct. 0! 200" 2:0# PM

NWN2 TOOL$%T HOWTO PL&'(N$The Neverwinter Nights 2toolset is an incredibly flexible system. In addition to its built-in tools italso includes a plugin interface that allows the toolset itself to be extended with new capabilities.

These plugins can be created by end-users with programming experience with Visual Studio with

the C# language. This language is ery different than the nwscript language used by the client.The plugins that are created can then be installed by other module builders to assist them in

creating their worlds.

T)*L%O+CONT%NT$

NWN2 Toolset HowTo Plugins...............................................................,

W-at are Plugins....................................................................................2

How to (nstall a Plugin.............................................................................2

W-/ )ut-or a Plugin.................................................................................

Creating 1our +irst Plugin........................................................................

)dding a Toolar for /ou Plugin...............................................................3

Toolset Pulic Classes..............................................................................4

NWN2Toolset Class.........................................................................................5

NWN2Toolset.NWN2.6ata Class....................................................................,0

NWN2Toolset.NWN2.(nstances..............................................................,,

NWN2Toolset.NWN2.6ata.T/7edCollections...........................................,,

NWN2Toolset.NWN2.Net6is7la/.............................................................,,

NWN2Toolset.NWN2.*lue7rints..............................................................,2

C-anging (te8 6ata +ro8 a Plugin.........................................................,2

Conclusion..............................................................................................,2

J McMillan Page , of ,Confidential


2/14



WH)T)9%PL&'(N$! plugin is a file that is loaded by the Neverwinter Nights 2toolset in order to add now

functionality to the toolset. The plugin does not add any capabilities to the client or to theresulting modules. It is used to assist the module creator in speeding up the deelopment

process. The plugin file is a dll that is normally written in Visual Studio and can be written in anymanaged language. "or this document we will assume the plugin is being written in C#.

HOWTO(N$T)LL)PL&'(N

! plugin must be installed before it can be used. If the plugin does not come with an installation

program that you must copy the plugin file this will normally end with the .dll file extension$ tothe directory %&eerwinter &ights ' Toolset (eta)&*&'Toolset)+lugins,. There should already a be

a few plugins installed there. If you installed the demo plugin proided with this document thedirectory should loo lie

/ou may hae other plugins in your directory. 0nce the new plugin is copied you must change the

settings in the toolset to allow the plugin to be loaded. 1un the toolset and change the options byselecting View Options. The following dialog will appear.

J McMillan Page 2 of ,Confidential


3/14



Change the !llow+lugins dropdown until it reads %2oad all plugins, and clic 03. This only needsto be done the first time that a plugin is installed. /ou will need to exit the toolset and rerun it for

the changes to tae effect. 0nce you are bac in the toolset there will be a new menu item in the

Plugins menu. In this tutorial we hae installed the 4emo plugin so to actiate the plugin you

must select the Plugins Demo Pluginmenu option. The plugin may display a dialog but in the

case of the 4emo plugin a new toolbar will appear displaying the new functions that hae been

added to the toolset. The new toolbar will loo lie

/ou can now perform the new actions by clicing on the toolbar buttons. If you no longer want to

use a plugin you can delete the plugin file from the +lugins directory.

If you simply want to use plugins and do not want to author a new plugin you can stop here. If

you are interested in writing your own plugins continue to the next section.

J McMillan Page # of ,Confidential


4/14



WH1)&THO9)PL&'(N0nce the plugin is loaded by the toolset it has access to the public classes and interfaces of the

toolset itself. The ability to reuse the same classes and data that the toolset uses is ery powerful.In addition to the classes the 5I elements of the toolset are also aailable. There are ery few

limits to the types of features that can be added to the toolset with plugins. ! plugin coulde be

used to add a new wi6ard for area or module creation7 global search and replace options7 andeen adding a scripting language lie 25! are possible.

3eep in mind that the plugin will hae no effect on client or serer itself. It can only assist in the

creation of modules or campaigns. If you wish to add database support for persistent worlds thennwscript in the client would be re8uired. /ou could use a plugin though to add database support

for placeables7 creatures7 etc. to the toolset.

C9%)T(N'1O&9+(9$TPL&'(N

The Neverwinter Nights 2toolset was written using managed code in Visual Studio. *hen thetoolset is run it loos in the +lugin directory for any .dll files and loads them as long as the !llow

+lugins option is set to !llow all plugins$. 0nce the .dll is loaded by the toolset it calls specific

methods in the .dll. This howto will assume that you are experienced with the Visual Studiodeelopment enironment as well as the C# language. The first step in creating a plugin is tostart a new pro9ect in Visual Studio to create a C# class library. /ou can download Visual Studio

:xpress for free from ;icrosoft at http


5/14



0nce the pro9ect has been created open up the pro9ect .cs file and loo for the pregeneratedcode.

namespaceTestPlugin

{ publicclassTestPlugin: INWN2Plugin { // Methods publicTestPlugin() {

}

"irst you need to add the following to the beginning of the file

usingSstem!usingSstem"#ollections"$ene%ic!usingSstem"Te&t!/'' NWN2Toolset"dll e&poses all the unctions e need to manupulate the tool*it"'/usingNWN2Toolset"Plugins!/'' Sandba% is the lib%a% thats used o% the toolba%"'' Windos also has a Toolba% ob+ect in Sstem"Windos",o%ms so ma*e su%e' ou c%eate the co%%ect ob+ect hen adding a toolba% to the tool*it"'/usingT-"Sand.a%!

/ou may need to browse into the &*&' directory to locate the &*&'Toolset.dll file. /ou will need

to add a few new methods into the class that will be called by the toolset during initiali6ation

p%iateMenu.uttonItemm0cMenuItem!

p%iateoid1andlePluginaunch(ob+ectsende%3 4ent5%gse) { // This code is e&ecuted hen the menu is selected

Sstem"Windos",o%ms"Message.o&"Sho(61ello Wo%ld76)! }

publicoidoad(INWN2Plugin1ostc1ost) { }

publicoidShutdon(INWN2Plugin1ostc1ost) { }

publicoidSta%tup(INWN2Plugin1ostc1ost) {

J McMillan Page of ,Confidential


6/14



m0cMenuItem 8 c1ost"$etMenu,o%Plugin(this)! m0cMenuItem"5ctiate 98 ne4ent1andle%(this"1andlePluginaunch)! }

publicoidnload(INWN2Plugin1ostc1ost) { }

publicMenu.uttonItemPluginMenuItem { get { %etu%nm0cMenuItem! } }

The 2oad and 5nload methods are called when the toolset is initially started and exited. TheStartup and Shutdown methods will be called when the +lugins menu item for your plugin is

selected.

/ou will also need to add a few properties to your close to identify the plugin to the toolset

// P%ope%ties publicst%ing-isplaName { get { %etu%n6-emo Plugin6! } }

publicst%ingMenuName { get { %etu%n6-emo Plugin6! } }

publicst%ingName { get { %etu%n6-emoPlugin6! } }

publicob+ectP%ee%ences { get { %etu%nnull! } set

J McMillan Page " of ,Confidential


7/14



{ } }

0nce you add these lines to your class7 you need to add references to the &*&' assemblies toyour pro9ect. This only needs to be done once. To do this use the +ro9ect -= !dd 1eference menu

item and select the (rowse tab. Then naigate to your folder where &*&' is located and enter&*&'Toolset.dll. 1epeat this process for the Sand(ar.dll and 0:IShared.dll files in the &*&'

folder. /ou should also use the .&:T tab to add the System.*indows."orms assembly. 0nce this iscompleted you can compile your new 422 and place it into the +lugins directory. /ou will now hae

a new menu item %4emo +lugin, from the 4isplay&ame property$ in the +lugins menu after yourestart the toolset. *hen the user selects the menu item the message %>ello *orld?, will be

displayed. Congratulations? /oue 9ust created your first plugin?

)66(N')TOOL*)9+O91O&PL&'(N

If you would lie to add a toolbar to the toolset 5I you will need to add a ariable to hold the

toolbar to your class

// ,ields p%iatePluginTestsmTests!

/ou can then update the Startup method to call the code to create a menu

publicoidSta%tup(INWN2Plugin1ostc1ost) { m0cMenuItem 8 c1ost"$etMenu,o%Plugin(this)!

m0cMenuItem"5ctiate 98 ne4ent1andle%(this"1andlePluginaunch)! // 5dd the olloing line o code to the end o the unction mTests 8 nePluginTests()! }

p%iateoid1andlePluginaunch(ob+ectsende%3 4ent5%gse) {

/'5dd the toolba%s'/ ist;PluginTests"Tool.a%-e< tool.a%s 8 mTests"$et5llTool.a%s()! o%(int+ 8 =! + ; tool.a%s"#ount! 99+) { o%(inti 8 =! i ;NWN2Toolset"NWN2ToolsetMain,o%m"5pp"#ont%ols"#ount! 99i) { i(NWN2Toolset"NWN2ToolsetMain,o%m"5pp"#ont%ols>i?"$etTpe()88 tpeo(Tool.a%#ontaine%)) { Tool.a%#ontaine%tbc 8(Tool.a%#ontaine%)NWN2Toolset"NWN2ToolsetMain,o%m"5pp"#ont%ols>i?! i(tbc"Name 88 tool.a%s>+?"NWNToolset-oc*Name) { tbc"#ont%ols"5dd(tool.a%s>+?"tool.a%)! b%ea*!

J McMillan Page 3 of ,Confidential


8/14



} } } } } /' ' This dictiona% ill hold all o ou% toolba%s" ' This a multiple toolba%s can be c%eated" '/ p%iate-ictiona%;st%ing3Tool.a%-e< 5llToolba%s!

p%iateenumTool.a%InitialPos { Top3 .ottom3 et3 @ight }!

publicst%uctTool.a%-e

{ publicTool.a%tool.a%! publicst%ingNWNToolset-oc*Name! }!

publicPluginTests() { 5llToolba%s 8 ne-ictiona%;st%ing3 Tool.a%-e


9/14



5llToolba%s>toolba%Name?"tool.a%"Items"5dd(buttonTo5dd)!

%etu%nt%ue! }

%etu%nalse! }

publicoid#%eate,o%est.utt#lic*ed(ob+ectsente%3 4ent5%gse) { } p%iateoid#%eateTool.a%(st%ingname3 Tool.a%InitialPosinitialPos) { Tool.a%temp 8 neTool.a%()! temp"Name 8 name! temp"Be%lo 8 Tool.a%Be%lo"1ide! temp"5llo1o%iContal-oc* 8 t%ue! temp"5llo@ightToet 8 t%ue! temp"5lloDe%tical-oc* 8 t%ue! temp"#losable 8 alse!

temp"Moable 8 t%ue! temp"Tea%able 8 t%ue! temp"-oc*ine 8 2!

Tool.a%-etbd 8 neTool.a%-e()! tbd"NWNToolset-oc*Name 8 $et-oc*Name,%omPos4num(initialPos)! tbd"tool.a% 8 temp!

5llToolba%s"5dd(name3 tbd)! }

There is 8uite a bit of code in the preious section. The code in the Startup method is called when

you select the menu item. It calls >andle+lugin2aunch that calls +luginTests. "inally7 the

Create"orest(uttCliced method will be called wheneer the %Create "orest, button in pressed inthe 5I.

TOOL$%TP&*L(CCL)$$%$

/our plugin will interact with the toolset ia the public classes that are exposed by the

&*&'Toolset.dll file. There are many classes that are aailable@ this section will describe thema9or classes that will commonly be accessed by a plugin. >ow you will access these classes will

be determined by the programming language C#7 V(.net7 25!$ that you are using.

There are many classes that are aailable in the &*&' toolset7 this guide will only describe a fewof the most important. It is recommended that you use a .&:T examination tool lie 2ut6

1oeders .&:T 1eflector$ to examine all of the classes that are aailable in all of the toolset files./ou can download the .&:T 1eflector from http


10/14



:ach of these classes will be described in more detail in the sections below.

&*&'Toolset Class

This class is used to set global preferences7 compile and bae modules7 and access information

about the currently open module or iew. ! few of the important members are

J McMillan Page ,0 of ,Confidential

NWN2Toolset.dll

This is assembly that contains the toolset classes

NWN2Toolset

>olds the main form7 application preferences and

high leel !+Is

NWN2Toolset.NWN2.6ata

4ata and methods for modules7 areas7

conersations7 etc.

NWN2Toolset.NWN2.(nstances

4ata for instances of creatures7 trees7encounters7 and placeables in modules areas

NWN2Toolset.NWN2.6ata.T/7edCollections

Classes to handle groups of ob9ects7 lie a groupof tree blueprints or a group of scripts

NWN2Toolset.NWN2.Net6is7la/

Classes to change texture and terrain on thecurrently displayed area

NWN2Toolset.NWN2.*lue7rints

;ethods for blueprints of creatures7 trees7encounters7 and placeables


11/14



NWN2ToolsetMain+or8 This is class for the main form of the toolset application. This

form will contain all of the windows7 toolbars7 menus for the toolset.

o )77 This is the current instance of &*&'Toolset;ain"orm. This should be

referenced to access the members of &*&'Toolset;ain"orm.

o Module This returns the &*&Aame;odule instance for the currently loaded

module. This should be used to modify the contents of a module.

o )reaContents 1eturns a &*&'!reaContentsView instance for the currently

displayed area. This can be used to modify terrain7 texture7 or tiles of an area.

o Controls ! collection of the controls owned by the main form such as toolbars.

o *ae This method will mae the currently open module.

NWN2Toolset'eneralPreferences 0ne of many the classes

&*&'ToolsetConersation+references7 &*&'ToolsetAraphics+references7 etc$ that handle

the View Options information.

&*&'Toolset.&*&'.4ata Class

This class contains methods to manipulate the information for the currently opened module. It

contains classes to handle areas7 scripts7 and conersations.

NWN2'a8eModule This is normally accessed ia &*&'Toolset.!pp.;odule. >olds all of

the information about the currently load module.

o )reas ! list of all of the areas in the module stored as a 4ictionary$.

o Con;ersations ! dictionary list of all of the conersations in the module.

o Creatures This along with 4oors7 Trees7 etc.$ hold the ;odule not Alobal$

blueprints for each of the types of instances.

o $cri7ts ! list of all of the scripts in the module.

o Na8e The name of the module.

o +ileNa8e The full pathname of the module if it has been saed


12/14



o Tiles

NWN2'a8e)reaTile6ata

NWN2TOOL$%T.NWN2.(N$T)NC%$

This class holds information the the indiidual instances of items that are placed into an area.

:ach of the types of instances has its own class. The classes are &*&'CreatureInstance7&*&'4oorInstance7 &*&':ncounterInstance7 &*&':nironmentInstance7 &*&'ItemInstance7

&*&'2ightInstance7 &*&'+laceableInstance7 &*&'TreeInstance7 &*&'SoundInstance7&*&'StaticCameraInstance7 &*&'StoreInstance7 &*&'TriggerInstance7 and

&*&'*aypointInstance. :ach of these instances allow direct access to the information for thatinstances such as Tint for creatures7 or Seed for trees$. The following methods are common to

the Instance classes.

Create+ro8*luePrint *hen this method is passed a blueprint as the parameter a new

instance will be created using the blueprints information.

'et6ifferences+ro8*luePrint 1eturns an array with the list of differences between the

instance and the passed in blueprint.

)rea The area ia &*&'Aame!rea$ this instance is in.

O


13/14



o *egin$/nc-roni=edO7eration This should be called before a group of changes

are made to one of the displayes

o %nd$/nc-roni=edO7eration This is the corresponding call that should be called

after a group of changes hae been made to a display window.

o TerrainModif/ This method can be used to modify the height of terrain in an

outside area.

NWN2TOOL$%T.NWN2.*L&%P9(NT$The blueprint collections are ery similar to the Instance collection with the same list of classes

with the (lueprint suffix replacing the Instance suffix. The module blueprints are located in the;odule To get a list of ;odule blueprints for trees you can reference

&*&'Toolset.&*&'Toolset;ain"orm.!pp.;odule.Trees. The common method of these classes is

*lue7rintLocation 1eturns a &*&'(lueprint2ocationType that indicates if the blueprint

is global7 module7 or campaign.

CH)N'(N'(T%M6)T)+9OM)PL&'(NThe following code demonstrates how you can access information that is in currently displayed

area and mae changes to items. In this example7 we will be changing the random seed alue ofall of the trees that are in the currently displayed area.

// This ill %et%iee %andom numbe%s o% us@andom%an 8 ne@andom()!

// This loops th%ough each o the t%ees in the cu%%entl actie a%ea beingdisplaedo%each(NWN2Toolset"NWN2"-ata"Instances"NWN2T%eeInstanceti inNWN2Toolset"NWN2ToolsetMain,o%m"5pp"5%ea#ontents"5%ea"T%ees){ // ti is the cu%%ent t%ee instance being editing and Seed is itEs seed alue // This ill set it do a %andom numbe% %om F to G=== ti"Seed 8 (uint)%an"Ne&t(G===)!}// This is %eHui%ed to %edispla the contents o the actie a%ea indoNWN2Toolset"NWN2ToolsetMain,o%m"5pp"5%ea#ontents"@e%esh()!// -ispla a simple message ith the numbe% o t%ees in the a%eaSstem"Windos",o%ms"Message.o&"Sho(NWN2Toolset"NWN2ToolsetMain,o%m"5pp"5%ea#onte

nts"5%ea"T%ees"#ount"ToSt%ing() 9 6 T%ees pdated"6)!

!s you can see from this example7 getting access to information in the currently actie area in

this case an outdoor area$ is 8uite easy. 3eep in mind that this code does not hae any of thenormal error checing is any area being displayed7 is a module loaded7 etc.$.

J McMillan Page ,# of ,Confidential


14/14



CONCL&$(ONThe Neverwinter Nights 2toolset has extremely powerful capabilities for building and creating

beautiful worlds and enironments. It can be extended by writing and using plugins to the toolset.The plugins can access much of the internal information about the modules and toolset 5I. It may

tae considerable programming experience and time to create your own plugin7 but the

improements to the toolset can sae time for all module deelopers.

J McMillan Page , of ,Confidential

nwn2 howto plugin

Documents