Scripting Update

Here's a list many of the scripting changes made in 1.06 so far. Most of them come from the 1.67 and 1.68 updates of NWN1.

ActionRest() - The bIgnoreNoRestFlag wasn't actually doing anything. It will now force rest even if the area is flagged NoRest or there are monsters nearby. If the character is still in combat, it will not force rest.

CreateItemOnObject() - Added new string parameter to provide the newly created object a new tag.

EffectHeal() now works on doors and placeables.

GetAbilityScore() now takes a 'nBaseAttribute' parameter to allow querying just the base attribute.

OnClick event for placeables that fires whether or not the player can actually path to them.

SpeakConversationOneLiner() now takes a parameter to determine if the spoken line should have whisper, talk, or shout volume.

Added:
CreateTrapAtLocation()
CreateTrapOnObject()
GetAreaSize()
GetInfiniteFlag()
GetKeyRequiredFeedback()
GetPickpocketableFlag()
GetPlaceableLastClickedBy()
GetTrapActive() - (Now works on doors and placeables too)
GetTrapRecoverable()
SetFortitudeSavingThrow()
SetReflexSavingThrow()
SetWillSavingThrow()
SetHardness
SetInfiniteFlag()
SetKeyRequiredFeedback()
SetLockKeyRequired()
SetLockKeyTag()
SetLockLockable()
SetLockLockDC()
SetLockUnlockDC()
SetModuleXPScale()
SetPickpocketableFlag()
SetTrapDetectable()
SetTrapDetectDC()
SetTrapDisarmable()
SetTrapDisarmDC()
SetTrapKeyTag()
SetTrapOneShot()
SetTrapRecoverable()
SetUseableFlag()


I also added a couple console commands to help with GUI debugging
openuiscreen []
closeuiscreen
unloaduiscreen

Also added a console command:
guidebug [MOUSEINPUT] [MOUSEOVER] [CALLBACKS]

This brings up an extra 'chat' window and will provide engine-level debugging info about mouse-overs, mouseinput, or callback execution. This feature isn't really finished as of this post, but I hope to spend some more time polishing it up for 1.06.

There are some new toolset features and bug fixes. The bug with seams showing up between tiles has been fixed as well as issues with Specular lighting not looking right. There is also now 5-level terrain undo for grass, water, and terrain adjustment and some improvements to some of the brushes.

There's some other things as well, but this is a pretty good sampling of the new things that will be in 1.06.

1.06 Progress

The 1.05 beta was posted today. One tweak that I intend to have made before 1.05 final is to remove the 'tabs = 5 spaces' change in the script editor. While some people do want some option like that, I think it needs to be implemented as something that can be turned on/off/adjusted, so for now, it's best to leave it out and re-implement it correctly in 1.06.

As far as 1.06 goes, I've spent a lot of time this week integrating a lot of the NWN1 1.67 changes, especially the script functions. I won't go into details now, but I will once I'm done. But in summary, most of the script functions that have been missing from NWN1's later patches should be in 1.06.

GDC

Warning, incoming period of silence. :)
I'll be at GDC this week, so probably won't have any updates until next week.

UIObject_Input_ActionTargetScript

This callback will one of the most powerful new tools when it comes to creating custom actions in the game.

UIObject_Input_ActionTargetScript(), new in 1.06, will let you make 'GUI actions' similar to the 'actions' that are created when you click on a spell or feat button to cast it, or on a button in the DM Choser that then has you select a target to do the action to.

Once the user clicks on a valid target, a bunch of data will be sent to the server along with a request to execute a script associated with the click.

Anyway, enough summary, here's the details:

UIObject_Input_ActionTargetScript("sValidTargetTypes",nValidCursor,nInvalidCursor,nSpellTargetIndex,bUseHostile,"sScriptName", script parameter list...)

sValidTargetTypes
This parameter is a string that will list the types of objects that will be valid to click on. If you enter a "", that means all targets are valid for this action. Otherwise, you can enter a list, seperated by commas or any other deliminator you want to use. The valid target names are:
self
creature
ground
item
door
placeable
trigger

For example: "creature,placeable" would mean that valid targets would include clicking on placeables and clicking on creatures.

nValidCursor
This is an integer constant to point to one of the cursors that the engine understands. You can only really use the cursors compiled into the game's executable. I will make a list of those constants at the end of this post. This is the cursor that you want to use when the cursor is over a valid target.

nInvalidCursor
Just like the nValidCursor parameter, except this is the cursor you want displayed when the mouse is over an invalid target. For example, if my valid targets were creatures and placeables, but the mouse was over open ground, this is the cursor that would be shown.

nSpellTargetIndex
This is a reference into the spelltarget.2da to indicate that you want to use one of the spell targeting projected textures like the ones used when targeting Area of Effect spells. If you do not want an AoE texture around the cursor, just enter -1 for this parameter.

bIsHostile
This tells the engine if you want to use the Hostile Texture column from spelltarget.2da or not. If you entered -1 for nSpellTargetIndex, then this parameter doesn't mean anything. You must enter either "true" or "false", even if you entered -1 for nSpellTargetIndex.

sScriptName
The name of the script you want to follow. This follows the same restrictions that UIObject_Misc_ExecuteServerScript() usese, in that the script name must start with 'gui_', or else the server will reject the request.

Parameter List
This is an unlimited list of parameters just like ExecuteServerScript() supports. However, there are a few extra parameters that this function can support:
target.object - This will replace the parameter with the OBJECT_ID of the object that the user clicked on.
target.x - This will replace the parameter with the X value of the position that the user clicked on as a float. If the user clicked on a specific object, instead of open ground, then this X will be the position of that object as far as the client knows. Since the client could be a few milliseconds out of synch with the server, the server may consider this object at a slightly different position than the client does.
target.y - Same as X, except for the Y value of the position vector.
target.z - Same as X, except for the Z value of the position vector.

For example, if I wanted to create a DM Action button that deleted whatever placeable the DM targetted as well as all placeables within 15 yards of the target, I would create a UIButton with the following callback:
OnLeftClick=UIObject_Input_ActionTargetScript("placeable",51,53,17,"true","gui_eraseplaceables","target:object")

The number 51 would be for the CURSOR_KILL cursor, the number 53 would be for the CURSOR_NOKILL cursor, the number 17 would be for row 17 in spelltarget.2da whcih is a large circle with a 30 yard width (so 15 yard radius), and the "true" is because I want it to use the hostile texture out of that 2DA. I want to use the clicked on placeable as my starting point, so I go ahead and pass that along as a parameter as well. It will be passed into gui_eraseplaceables as either a string or an int, depending on what parameter I have that script expecting.

Anyway, the list of cursor constants is:

#define MOUSECURSOR_DEFAULT 1
#define MOUSECURSOR_DEFAULT_DOWN 2
#define MOUSECURSOR_WALK 3
#define MOUSECURSOR_WALK_DOWN 4
#define MOUSECURSOR_NOWALK 5
#define MOUSECURSOR_NOWALK_DOWN 6
#define MOUSECURSOR_ATTACK 7
#define MOUSECURSOR_ATTACK_DOWN 8
#define MOUSECURSOR_NOATTACK 9
#define MOUSECURSOR_NOATTACK_DOWN 10
#define MOUSECURSOR_TALK 11
#define MOUSECURSOR_TALK_DOWN 12
#define MOUSECURSOR_NOTALK 13
#define MOUSECURSOR_NOTALK_DOWN 14
#define MOUSECURSOR_FOLLOW 15
#define MOUSECURSOR_FOLLOW_DOWN 16
#define MOUSECURSOR_EXAMINE 17
#define MOUSECURSOR_EXAMINE_DOWN 18
#define MOUSECURSOR_NOEXAMINE 19
#define MOUSECURSOR_NOEXAMINE_DOWN 20
#define MOUSECURSOR_TRANSITION 21
#define MOUSECURSOR_TRANSITION_DOWN 22
#define MOUSECURSOR_DOOR 23
#define MOUSECURSOR_DOOR_DOWN 24
#define MOUSECURSOR_USE 25
#define MOUSECURSOR_USE_DOWN 26
#define MOUSECURSOR_NOUSE 27
#define MOUSECURSOR_NOUSE_DOWN 28
#define MOUSECURSOR_MAGIC 29
#define MOUSECURSOR_MAGIC_DOWN 30
#define MOUSECURSOR_NOMAGIC 31
#define MOUSECURSOR_NOMAGIC_DOWN 32
#define MOUSECURSOR_DISARM 33
#define MOUSECURSOR_DISARM_DOWN 34
#define MOUSECURSOR_NODISARM 35
#define MOUSECURSOR_NODISARM_DOWN 36
#define MOUSECURSOR_ACTION 37
#define MOUSECURSOR_ACTION_DOWN 38
#define MOUSECURSOR_NOACTION 39
#define MOUSECURSOR_NOACTION_DOWN 40
#define MOUSECURSOR_LOCK 41
#define MOUSECURSOR_LOCK_DOWN 42
#define MOUSECURSOR_NOLOCK 43
#define MOUSECURSOR_NOLOCK_DOWN 44
#define MOUSECURSOR_PUSHPIN 45
#define MOUSECURSOR_PUSHPIN_DOWN 46
#define MOUSECURSOR_CREATE 47
#define MOUSECURSOR_CREATE_DOWN 48
#define MOUSECURSOR_NOCREATE 49
#define MOUSECURSOR_NOCREATE_DOWN 50
#define MOUSECURSOR_KILL 51
#define MOUSECURSOR_KILL_DOWN 52
#define MOUSECURSOR_NOKILL 53
#define MOUSECURSOR_NOKILL_DOWN 54
#define MOUSECURSOR_HEAL 55
#define MOUSECURSOR_HEAL_DOWN 56
#define MOUSECURSOR_NOHEAL 57
#define MOUSECURSOR_NOHEAL_DOWN 58
#define MOUSECURSOR_RUNARROW 59
#define MOUSECURSOR_WALKARROW 75
#define MOUSECURSOR_PICKUP 91
#define MOUSECURSOR_PICKUP_DOWN 92
#define MOUSECURSOR_CHATBOX_SIZING 99
#define MOUSECURSOR_NODEFAULT 125
#define MOUSECURSOR_NODEFAULT_DOWN 126
#define MOUSECURSOR_MAP 128
#define MOUSECURSOR_MAP_DOWN 127
#define MOUSECURSOR_NOMAP 130
#define MOUSECURSOR_NOMAP_DOWN 129
#define MOUSECURSOR_WAIT_DOWN 131
#define MOUSECURSOR_WAIT 132

IntToObject

This is just a quick note to mention that I've added:
object IntToObject( int nInt );

and

int ObjectToInt( object oObj );

scripting functions for 1.06.

UIObject_Misc_ExtractData

Sorry for the delay in posting, but if you're into custom UI work, this information will have been worth the wait. :)

A new callback in 1.06 is:
UIObject_Misc_ExtractData( sourceobject, datatype, index, destinationvar )

This callback can be used to extract the data imbedded by the engine within UI Objects. First I'll go over the parameters, then I'll give some examples.

sourceobject
This parameter is used to define which UI Object we are extracting data from. It accepts the following options:

selected:listboxname - By replacing 'listboxname' with the name of the listbox you're interested in, you can tell this callback to use the selected row within the list box as the source of the data.

self: - By using 'self:', you are telling the callback to use the object that invoked the callback as the source from which to extract the data.

context:uiobject - By using context:uiobject:', you are telling the callback to use the UI Object that invoked the context menu. This obviously only means anything if the callback is being called from a context menu node. If called from anywhere else, the callback will do nothing.

objectname - If you enter any string besides the above 3 options, the callback will search for a UIObject within the same scene as the object executing this callback that has that name.

datatype
The datatype tells the callback which data type it should be extracting from the UIObject. Note that regardless of what the original data type is, the data type that gets stored in the GUI Variable at the end will always be a string.

The data type values are:
bool -'true' or 'false' are the strings that will get stored in the GUI variable
int
float
string
strref
objectid

Again, it's important to remember that no matter what the originating data type is, the result will be stored as a string variable within the GUI variable specified.

index
This is the index of the data to extract. If the index is invalid for the UIObject, a default value will get stored in the GUI variable (Either "" or "0" or "false" depending on what the originating data type was).

destinationvar
This can be a local:# or global:#. The type of the stored data will always be a string.

Example 1
Now for some real examples that will work.

The grid icons in the inventory grid have the following data imbedded in them:
OBJECT_ID(0) = The object currently displayed in that icon
OBJECT_ID(1) = The object that was dispalyed in that icon on the previous frame
int(0) = The stacksize for that object on the previous update frame
int(1) = Indicates if the item is identified or not
int(2) = Indicates if the item is usable or not
int(3) = Indicates if the item is ghosted or not

It would be possible for me to change the inventory screen to drop items if I double right click on them.

I would edit the 'InvPrototypeButton' inside of inventory.xml and add:

OnRightDoubleClick0=UIObject_Misc_ExtractData("self:","objectid",0,local:3)
OnRightDoubleClick1=UIObject_Misc_ExecuteServerScript("gui_dropitem",local:3)

When I right double click that item, the first callback will extract the Object ID of the item and place it in local:3 as a string that looks like: "32144" or whatever the object ID is.

Then the 2nd callback would execute, asking the server to fire off the "gui_dropitem" script, and it would pass the 32144 value in as a parameter to the script (Either as a string "32144" or an integer 32144, depending on what the parameter type the script is expecting).

Now I will be adding an IntToObject() script funciton that will make it possible to take that int parameter and turn it into an object parameter. At that point, you could use the DropItem action and have the player drop that object.

Note that in this example, I would've had to remove the OnRightClick call to the context menu for the item button or it would end up blocking the double right click (Due to the context menu popping up and blocking the second click).

Example 2
This example is a lot more complicated, I'll try to explain it clearly. :)

The spell buttons in the game usually have the following pieces of data:
int(0) = The spell ID that the button represents
int(1) = The multi-class index that can cast that spell
int(2) = Not used anymore, so nothing.
int(3) = The meta magic feat, if any
int(4) = Whether or not this is a spontanously cast spell
int(5) = Whether or not this is a domain spell
int(6) = Whether or not this is a cheat-command spell cast

The values for int(3), the meta magic feat, are:
1 = Empower
2 = Extend
4 = Maximize
8 = Quicken
16 = Silent
32 = Still
64 = Persistent
128 = Permanent

The warlock invocations are also meta-magic feats, as follows (Note, I'm not sure how many of these are actually in the game, I'm just going down the list of constants in the code):
256 = Draining Blast
512 = Eldritch Spear
1024 = Frightful Blast
2048 = Hideous Blow
4096 = Beshadowed Blast
8192 = Brimstone Blast
16384 = Eldritch Chain
32768 = Hellrime Blast
65536 = Bewitching Blast
13102 = Eldritch Cone
262144 = Noxious Blast
524288 = Vitrioloic Blast
1048576 = Eldritch Doom
2097152 = Utterdark Blast

Let's say I want to make my own custom Examine Spell command for the spells_known.xml listing of spells.

First off, let's add our own custom radial menu (Another new feature in 1.06).

In spells_known.xml, I would go to the SPELLPANE_PROTO pane and add a
OnRightClick=UIObject_OnRadial_DisplayCustomRadial("root-customspell")

root-customspell will be the name of a new root node that I would then add to the contextmenu.xml

For now, that root node will only have 1 sub node called: node-spellexamine

node-spellexamine will be the name of a new radial node that I would make with the following callbacks:
OnLeftClickExpanded0=UIObject_Misc_ExtractData("context:uiobject","int",0,local:5)
OnLeftClickExpanded1=UIObject_Misc_ExecuteServerScript("gui_spellexamine",local:5)
OnLeftClickCollapsed0=UIObject_Misc_ExtractData("context:uiobject","int",0,local:5)
OnLeftClickCollapsed1=UIObject_Misc_ExecuteServerScript("gui_spellexamine",local:5)

Now when I go into the game and bring up the Spells Known screen and right click on the spell icon for a spell in the list, I will get a context menu with 1 item called 'Examine'. Clicking on that will first call:
UIObject_Misc_ExtractData()
which will extract the spell ID from int(0) on the button I brought the context menu up on and place that ID in local:5

Then it will fire
UIObject_Misc_ExecuteServerScript()
and pass along the spell ID (As stored in local:5) as the parameter to the script: gui_spellexamine

From there I can do whatever I want with that data. :)

To recap, the new features mentioned in this article are:
UIObject_Misc_ExtractData()

and

UIObject_OnRadial_DisplayCustomRadial()

Feel free to ask any time you would like me to provide a detailed list of what data is imbedded in a given UI Object. Some you'll probably be able to figure out on your own via trial and error, but I'll be happy to look into any specific UI Object if you need.

Couple new GUI script functions for 1.06

1.06 will have a number of new script functions that will give improved control over custom GUIs.

Two of the new script functions are:

SetGUIProgressBarPosition();

This script function will let you set the position of a progress bar (Between 0.0 for empty and 1.0 for full).

The other new function is:

SetGUITexture();

This script function will let you set the texture for a UIIcon, a UIFrame's fill texture, or a Button's Base Frame's fill texture.

Both script functions require the UIScene to be scriptloadable like all the other GUI related scripting functions.

New UI Callback Parameters

In 1.06, callbacks can take 2 new 'variable' parameters in addition to global:# and local:#.

The first new parameter type is
listboxrow:listboxname

This will insert the row # that is currently selected in the listbox indicated by listboxname

For example, if I had a callback that looked like:

OnLeftClick=UIObject_Misc_ExecuteServerScript("myguiscript",listboxrow:mylb)

On the same UIScene I have a listbox called 'mylb' where I have selected the 3rd row.

When the OnLeftClick callback above gets executed, the 1 parameter that gets sent to that script will be an integer with the value of 2. (The first row in the LB would send a value of 0).


The second new parameter type also deals with ListBoxes:
listboxtext:listboxname[.textfieldname]

This will insert the text contained by that row. If the listbox rows are buttons or text fields, then the textfieldname parameter above is not necessary. If instead they are complex UI Panes, then the textfieldname will be used to specify which object within the pane contains the text we want.

For example, if I had a callback that looked like:
OnLeftClick=UIObject_Misc_ExecuteServerScript("myguiscript",listboxtext:mylb.mytext)

In the same UIScene, I have a Listbox named 'mylb'. The rows of that lb are complex UIPanes that contain a text field in them called 'mytext'.

When that callback executes, the engine will look at 'mylb', find the currently selected row, then look for the object named 'mytext' within that row and insert the text within that object as a parameter to the script on the server.

Now obviously the real power of these new variable parameters will be when coupled with the ability for scripts to populate a gui listbox. That functionality isn't in yet, but is something else I intend to have in for 1.06.


There are other new 'variable' parameter syntaxes that will be coming along with 1.06 that I'll post about once I have actually implemented them. :)

UIButton_OnUpdate_ControlSelected

This callback takes a single parameter. It's only purpose is to enable or disable a button based on whether or not the user has selected a row in a List Box.

The single parameter is:
sListBoxName = The name of the list box we want to check for selection.

If the user has a row selected in the listbox named in the parameter, then the UIButton will be set to Enabled.

If the user does not have a row selected in the listbox named in the parameter, then the UIButton will be disabled.

UIObject_Misc_StoreObjectData

The only valid parameter to this callback is a local or global GUI variable index.
localguivars are expressed as local:#, where # is the index for the variable.

globalguivars are expressed as global:#, where # is the index for the variable.

This callback takes the engine-level data in a UIObject and stores it in a global or local gui variable. The engine-level data will vary from UIObject to UIObject. It is also impossible to specify which data item you want to set the GUI variable to, if the UIObject has multiple items of data.

This is a really old callback and is of limited use to custom GUIs at this time. My intent is to write a new callback that accomplishes what this callback does, but that takes more parameters in order to more accurately specify what data you are interested in from the UIObject.

UIObject_Tooltip_DisplayTooltipString

UIObject_Tooltip_DisplayTooltipString takes up to 9 parameters, but only the first four parameters are required.

Parameter list:
Message = The literal string to display in the tooltip

XLoc = The X origin for where the tooltip should appear. This can be a pixel location, or you can use the following two strings to make it relative: MOUSE_X will place the X origin of the tooltip near where the mouse is. OBJECT_X will place the tooltip next to the UIObject that is being moused over, if any. At first, it will try to place the tooltip to the right side of the UIObject. But if there is not enough screen space to fit the tooltip there, it will place it on the left side of the UIObject.

YLoc = The Y origin for where the tooltip should appear. This can be a pixel location, or you can use the following two strings to make it relative: MOUSE_Y will place the Y origin of the tooltip near where the mouse is. OBJECT_Y will place the tooltip next to the UIObject that is being moused over, if any. At first, it will try to place the tooltip on top of the UIObject. But if there is not enough screen space to fit the tooltip there, it will place it on the bottom of the UIObject.

Screen Tag = The Screen Tag for the XML file to be used for the tooltip

XAlignment = This parameter can be used to quickly position a tooltip relative to the full-screen space. The valid arguments are: ALIGN_NONE(default), ALIGN_CENTER, ALIGN_LEFT, ALIGN_RIGHT

YAlignment = This parameter can be used to quickly position a tooltip relative to the full-screen space. The valid arguments are: ALIGN_NONE(default), ALIGN_CENTER, ALIGN_TOP, ALIGN_BOTTOM

XPadding = This is used along with XAlign to quickly position the tooltip. It controls how far in the tooltip should be pushed from the left or right border of the screen space. For example, setting XAlignment to ALIGN_RIGHT and XPadding to 10 will result in the tooltip appearing on the right side of the screen, with a space of 10 pixels between the right edge of the tooltip scene and the edge of the screen.

YPadding = This is used along with YAlign to quickly position the tooltip. It controls how far in the tootip should be pushed from the top or bottom border of the screen space. For example, setting YAlignment to ALIGN_BOTTOM and YPadding to 10 will result in the tooltip appearing on the bottom of the screen with a space of 10 pixels between the bottom edge of the tooltip scene and the edge of the screen.

TextAlignment = How the text should be aligned in the tooltip. The options are: ALIGN_NONE(default), ALIGN_CENTER, ALIGN_LEFT, ALIGN_RIGHT, ALIGN_TOP, ALIGN_BOTTOM

Multiple Callbacks Per Event

In 1.06, it will be possible to set up multiple GUI callbacks on a single UI event in XML. The syntax will be to use the event name and append a number to it. The engine will read in the callbacks until it fails to find the next sequential number.

For example, I could set up a UI Button to with the following callbacks:

OnUpdate=UIObject_OnUpdate_DisableIfLocalVarEquals(local:3,"true")
OnLeftClick=UIObject_Input_ScreenOpen("SCREEN_OPTIONS","false")
OnLeftClick0=UIObject_Input_SetLocalVarString(local:3,"true")

When I click that button, it would open the Options screen, then set the local var to "true". On its next update, it would become disabled because of the OnUpdate check.

Note that the callback without a number will be handled before the 0'th callback.
So OnLeftClick will be handled before OnLeftClick0.

Also note that the callback without the number is not required but is mostly just supported for backwards compatibility.

For example, it would be valid to have the following callbacks:

OnLeftClick0=
OnLeftClick1=
OnLeftClick2=

That will work fine, executing 0, then 1, then 2.

It is also valid to have:
OnLeftClick=
OnLeftClick0=
OnLeftClick1=
OnLeftClick2=

This will execute them in order.

It is not valid to start with any other number besides 0 however.

OnLeftClick1=
OnLeftClick2=
OnLeftClick3=

will result in no callbacks being loaded for that event for that UIObject.

Sometimes the engine assigns callbacks to UIObjects internally. The engine will only ever override the first callback, so if you are having a problem with the engine overriding your callback for some UI Object, you might need to insert a dummy callback first, before the callbacks you actually want to execute. This doesn't happen too often though, so I doubt this will be an issue for very many.

Note at this time, the only event that doesn't support multiple callbacks is OnTooltip, due to how the engine has to handle this event internally. I may or may not be able to fix OnTooltip by the time 1.06 comes out.

Special Screens

Taking a break from writing about the UI Elements for a moment, though there are still some of those that I will cover in future posts.

Most XML files are loaded as default UI Scene, which implies no special behaviors. There are, however, several XML files that will get special handling in code and most conform to specific rules in order to even be loaded. All of these scenes are distinguished by their identifying name in the INI file (Or the screen tag given to them when being loaded via script). The actual XML file name doesn't matter.

Note that when I list them below, if a name ends with a * mark, that means that only the text up to the * mark is required and that the name may be unique after that mark.

The following are special GUI screens that are loaded differently than most XML files:

SCREEN_FADE = The full screen 'fade' effect. It gets loaded like a normal XML file at first. After loaded, the first UIIcon object found (The one highest up in the file) becomes the engine's 'Fading' icon. The rest of the contents of the file will behave normally. In our default SCREEN_FADE, we include just the full screen icon. But there may be other things one would want to include on the fade, such as custom images, etc.

SCREEN_QUICKCHAT = The NWN1 style dialog box. First it is loaded like a normal XML file, then the following ui objects are searched for in order for the engine to use them:
npclistbox - Listbox of NPC spoken text
npctext - Text field for NPC spoken text (Contained by npclistbox generally)
replieslistbox - Listbox of Player Reply options
skipdialogbutton - Button for skipping through the NPC spoken nodes
speakername - Text field for containing the speaker's name
portrait - UIPortrait object
All but the speakername and portrait fields are necessary or the window will not be loaded.

SCREEN_CUTSCENE = The fill screen cutscene view with the black bars on the top and bottom. This window is loaded like any other, then the following objects are searched for by the engine:
topbar - UIFrame for the top black bar
bottombar - UIFrame for the bottom black bar
FULLSCREEN_IMAGE - UIIcon used for full screen images.
toplistbox - Listbox to contain the text shown on top
toplistboxtext - Textfield contained by toplistbox
bottomlistbox - Listbox to contain the text shown on the bottom. Spoken by NPCs
bottomlistboxtext - Text field contained by bottomlistbox
replieslistbox - Listbox to contain the replies available to a player.
skipdialogbutton - Fullscreen button for clicking through the dialog
Failure to locate any of the above objects will result in the screen not loading.

SCREEN_CONTEXTMENU = The rightclick menu system. Technically, this gets loaded like any other XML file. I'll make another post later about the syntax and format of the contextmenu.xml file.

SCREEN_MINIMAP = The in-game minimap GUI. I don't know a lot about how the Minimap works. If further documentation is requested for it, I can research it further later.

SCREEN_AREAMAP = The in-game area map that can be brought up. I don't know a lot about how the Area Map works. If further documentation is requested for it, I can research it further later.

SCREEN_MESSAGEBOX_SPLITSTACK* = Scene used for splitting stacks of items in inventory. The only gui element required is 'inputbox'.

SCREEN_MESSAGEBOX_SPLITSTACKSTORE* = Scene used for splitting stacks of items for stores. It's actually loaded identically to the SCREEN_MESSAGEBOX_SPLITSTACK and only requires the 'inputbox' object to exist. I'm not sure why it got made into a seperate entry.

SCREEN_MESSAGEBOX* = This is used for the generic message box popups. I'll probably have to write up more on them another time as they can be used effectively by scripts as well. The required elements for these are:
messagetext = Text field that contains the message.
okbutton = Button that will execute the OK callback
cancelbutton = Button that will execute the Cancel callback
messageboxlb = Listbox for containing the message text in case the text gets long.
MSGBOX_BACKGROUND = Frame used for the background, this one is optional.

SCREEN_STRINGINPUT_MESSAGEBOX* = Message boxes that prompt for user string input. They are identical to normal Message boxes, except that they also require a 'inputbox' text field.

SCREEN_MESSAGE* = Chat boxes, pretty much. Note that currently the engine only supports loading the hard coded ones in ingamegui.ini. I hope to change this to be a lot more flexible down the line. The required elements are:
messagelistbox - Listbox containing the scrollback text. If it is not found, the engine searches for messagelistbox2 instead. If neither is found, the screen is not loaded.
inputbox - Text field used for user input.
IMEREadingWindow - Used for IME support.
IMEReadingWindowBG - Used for IME support.
IMEComposeWindow - Used for IME support.
IMEComposeWindow - Used for IME support.
IMECandidateWindow - Used for IME support.
IMECandidateWindowBG - Used for IME support.
INPUT_CONTAINER - Used by the engine for easily hiding/unhiding the input related objects.

SCREEN_HOTBAR, SCREEN_HOTBAR_2, SCREEN_HOTBAR_V1, SCREEN_HOTBAR_V2 = All the hotbars built into the game. There are no required or special UI elements needed to load these.

If a Screen Tag doesn't match to any of the above screens, then a normal UI Scene gets created with all the default behaviors associated with it.

UIObject - hideoverride

In 1.05 there is a new attribute that all UI Objects handle called hideoverride. If true, this attribute sets a UI Object hidden and keeps it that way until a script says otherwise via the SetGuiObjectHidden() script function.

This can be used to keep an item hidden that the GUI may try to make visible regardless what a script tries to do, such as a row in a list box.

As a result, objects that are set hidden via SetGuiObjectHidden() will STAY hidden no matter what, unless SetGuiObjectHidden() is later used to make it visible.

For example, if I add a new icon to a screen and set it hideoverride=true in the XML, it will remain hidden on that screen no matter what the GUI might try to do with it until I call SetGuiObjectHidden() with a false parameter to make it visible again, at which point the GUI once again has control over making that object hidden or unhidden.

UIText

UIText is the GUI object used for containing and rendering text. It is one of the more complicated UI Objects to work with.

UIText takes the following attributes:

fontfamily
This defines which font should be used via a string argument. The fonts are defined in fontfamily.xml. The 'name' attribute for the different UIFontFamily elements in fontfamily.xml is how they are identified here. If this attribute is not set, then the text field will use the 'Default' font family defined in fontfamily.xml.

nextcontrol
Which control should have focus if the user hits tab while editing this UIText field. It only really makes sense to put UIText field names as the arguments to this attribute, as focus doesn't have any significant meaning for any other type of UIObject. Note that the nextcontrol must be in the same UIScene as this text field.

prevcontrol
Which control should have focus if the user hits shift+tab while editing this UIText field. It only really makes sense to put UIText field names as the arguments to this attribute, as focus doesn't have any significant meaning for any other type of UIObject. Note that the prevcontrol must be in the same UIScene as this text field.

filter
This attribute can be used to limit what text the user can enter into this text field when editing it. By default, any input character is valid. It takes strings as its arguments. The following strings are handled:
alpha - Only letters can be entered in this field.
numeric - Only numbers can be entered in this field.
alphanumeric - Only letters and numbers can be entered in this field.
signed_numeric - Only numbers in this field, except the '-' character, which may only be entered at the front of the string.

maxnumber
This number limits the max number that a user can enter when editing this text field. It only means anything if the text field's filter is set to numeric or signed_numeric.

allowspace
If this attribute is false, then any space characters will not be allowed in this field, including tabs or newlines. It defaults to false.

allowpunc
This attribute only means anything if the filter type is set to alpha or alphanumeric. It allows graphical punctuation characters to be entered in the text field. If no filter type is specified, then this attribute doesn't do anything. It defaults to false, so must be set to true if the intent is to allow users to enter punctuation style characters into this text field.

password
Defaults to false. If set to true, then the characters in this string will be replaced with * marks when this text field gets rendered.

sanitized
Defaults to false. If this attribute is set to true, then any string entered in this text field will be run through the built in swear-filter.

style
This is a modifier to the font that is being used. It takes a string or number as its argument. The following arguments are supported:
normal - Or style 1. This is defined by the UIFontNormal element in fontfamily.xml
bold - Or style 2. This is defined by the UIFontBold element in fontfamily.xml
italic - Or style 3. This is defined by the UIFontItalic element in fontfamily.xml
bolditalic - Or style 4. This is defined by the UIFontBoldItalic element in fontfamily.xml

indent
This is the number of pixels to indent the first line of any text. It defaults to 0.

hangingindent
This is the number of pixels to indent all lines besides the first line in a multi-line text field. It defaults to 0.

align
This is how the text should be aligned in the text field. The following string arguments are handled: left, right, center. Defaults to left.

hilite
Defaults to false. If set true, then the text in this text field will hilight when moused over.

valign
This is how the text should be aligned vertically within the text field. The following string arguments are handled: top, bottom, middle. Defaults to top.

poscenter
This attribute is defunct and no longer does anything.

sizetofit
Defaults to false. If set to true, then the text field will extend its height downward as far as possible in order to contain the length of text within it. This is an old attribute and should be replaced by just setting the height of the text field to DYNAMIC.

buttonoverlay
This only means anything if the text field is a child element of a UIButton element. If left to the default of false, then this text field will become the normal text field that shows up in buttons. If set to true, it becomes Overlay Text. At this time, Overlay Text can only be manipulated by the engine.

editable
Defaults to false. If set to true, then the user can edit the text within this text field by clicking it to place their cursor and typing like normal.

selectable
This attribute does nothing at this time.

maxlines
The max number of lines this text field can contain. Setting this attribute to '1' will keep the engine from trying to break the text into multiple lines. Text that will not fit into the text field after the maximum number of lines has been reached will not get rendered. If not defined, the engine will try to wrap a string and fit it into the space available no matter what, which can sometimes result in no text at all appearing due to spacing errors.

multiline
This attribute toggles whether or not a user can hit enter to start a new line of text within a editable text field. It requires that allowspaces be also set to true or else it will seem to do nothing. It defaults to false. When false, the OnReturn callback will get called when the user hits enter, instead of a new line being inserted.

returnrestricted
This attribute can be a bit confusing. It defaults to false and only means anything when used with multiline=true. What happens is that if this attribute is set to 'true', the text field will accept multiple lines of input and wrap them automatically, but if the user hits their return key, the OnReturn callback gets called instead of inserting a newline. An example of this behavior can be found in the chat input box.

uppercase
Defaults to false. If true, all text rendered in this text field will be rendered in uppercase.

maxlength
This limits the number of characters that can be typed into a text field by the user. Once the user has entered the max limit of characters, no additional characters can be input. If no maxlength is set, the user can keep typing indefinitely.

color
A color to blend with all of the characters within the text field. This can sometimes conflict with the use of the color tags in text fields.

highlightcolor
This attribute defines the color that should be blended with the text when doing a mouse-over style highlight.

selectioncolor
This attribute does nothing at this time.

highlightonmouseover
This is just a clone of the hilite attribute mentioned above.

text
This is for hard coding the text that should show up in this text field. Overrides strref.

strref
This is for coding which string ref should show up in the text field. It is overridden by text.

OnReturn
This callback gets executed when the user hits Enter while the cursor is in this text field. Note that if the text field is set with multiline=true and restrictedreturn=false, then this callback will not get executed.

OnLostFocus
This callback is executed when the cursor is taken out of the text field due to the user clicking elsewhere.

UIFrame

UI Frame is used for borders and backgrounds for other UI Objects. UIFrames are imbedded in buttons and a few of the container style UI Objects that will be discussed later.

The following attributes are handled by UIFrame:

The following is a list of the texture pieces that make up a frame. They take a texture name as an argument. The texture pieces are:
topleft, topright, top, left, right, bottom, bottomleft, bottomright, fill.

The next set of attributes are methods of mirroring one piece to other pieces. This mirroring happens at render time.

mhtop
Stands for MirrorHorizontalTop. Defaults to false. If true, the Top Left Corner will be mirrored to the Top Right Corner. If combined with mvright, then the Top Left Corner will be mirrored to the Right Bottom Corner.

mhbottom
Stands for MirrorHorizontalBottom. Defaults to false. If true AND mvright is true, then the Top Left Corner will get mirrored to the Bottom Right Corner. If true AND mvright is false, then the Bottom Left Corner will get mirrored to the Bottom Right Corner.

mvleft
Stands for MirrorVerticalLeft. Defaults to false. If true, the Top Left Corner will get mirrored to the Bottom Left Corner. If true AND mhbottom is true, the Top Left Corner will get mirrored to the Bottom Right Corner.


mvright
Stands for MirrorVerticalRight. Defaults to false. If true AND mhtop is true, the Top Left Corner will get mirrored to the Bottom Right Corner. If true AND mhbottom is false, the Top Right Corner will get mirrored to the Bottom Right Corner.

mhside
Stands for MirrorHorizontalSide. Defaults to false. If true, the Left Side will get mirrored to the Right Side.

mvside
Stands for MirrorVeritcalSide. Defaults to false. If true, the Top Side will very mirrored to the Bottom Side.

maside
Stands for MirrorAllSides. Defaults to false. If true, the Left Side will get mirrored to the Top Side, Right Side, and Bottom Side.

The remaining attributes supported by UIFrame follow:
fillstyle
This tells the engine to fill in the center space of the frame with the fill texture using different algorithms. This attribute takes the following string arguments:
center - Center the 'fill' texture.
stretch - Stretch the 'fill' texture to take up the full center.
tile - Repeat the 'fill' texture to fill up the center.

border
This is the thickness of the border pieces in pixels. Note that it defaults to 0. If no border thickness is set, then all the textures besides 'fill' won't show up when the UIFrame gets rendered.

color
This takes color strings to define the color that should be blended with the frame textures.

Note that if a UIFrame doesn't have a height or width defined by its attributes, it automatically inherits the height and width of whatever object contains it.

UIButton

UIButton is the generic, clickable object one expects to find on any PC game interface. It also acts as a 'restricted' container of sorts, as it can contain specific UI objects within it.

A button is made up of several child objects contained in a single pane. These pieces can be defined explicitly or left up to the engine to define.

The child objects that a UIButton can contain are:
Up to 1 UIText field. If a UIText object is not defined as a child object in the XML, the engine will create one automatically when creating the UIButton.

Up to 11 UIFrames. A UIFrame contained within a button must have a state attribute that only applies when specifically contained within a button. The following arguments are valid for the state attribute:
up
down
disabled
focused
hilited
hifocus
header
hiheader
downheader
base
These states can mean different things depending on the context of the button, so I'll just make some notes about a few of them. 'header', 'hiheader', and 'downheader' are the states for a button that is to be the header of a UICollapsable object, which will be explained further in a later article. 'base' is useful for when using state frames that leave some of the 'base' button visible, such as hotbar button icons.

An unlimited number of UIIcons that will be added to the 'overlay' list for that button. Overlays are extra icons that can be made visible by the engine that stay with the button. At this time, there is no way to manipulate these overlays via script.

UIButton supports the following attributes:

style
This is a 'style' name from the stylesheet.xml file that this button should adopt for its default parameters. At this time there is not support for custom styles.

repeatcallback
If this attribute is set to true, the OnLeftClick callback will get executed every frame as long as the left mouse button is held down on it. On the first update the OnLeftClick will execute on the mousedown. There will then be a 0.5 second pause, then after that the OnLeftClick callback will be executed every frame until the left mouse button is released.

OnSelected
This callback is applicable to radio buttons and toggle boxes. If the button is a toggle box, this callback is executed when the toggle box is activated. If the button is a radio button, this callback is executed when the button becomes the selected radio button.

OnUnselected
This callback is applicable to radio buttons and toggle boxes. If the button is a toggle box, this callback is executed when the toggle box is de-activated. If the button is a radio button, this callback is executed if thi sbutton was the selected radio button, but now another radio button has been selected.

groupid
This is a group number for radio buttons. Group IDs are global for the entire XML file that contains the button. That is to say, there can only be one group of radio buttons with the group id of '1', or '2', etc. All buttons that share the same group id form a 'set' of radio buttons. Only one button in that set can be selected at a time, all the rest are non-selected. Selecting any one button in the set will unselect the previously selected radio button.

groupmemberid
This gives the UI Button a unique within a set of radio buttons. There should only be one button with a specific groupmemberid in a set of buttons. Ideally these IDs should start with 1 and increment from there, but that is not completely necessary.

buttontype
This attribute accepts only 'radio' or 'check' as arguments, defining the button as a radio button or checkbox style button.

color
This attribute accepts color strings. These colors will blend with any other colors found in the textures of the button. So setting this to grey, for example, will make a grey-scale style icon for the button.

disabledcolor
This attribute accepts color strings. This will be the blending color for when the button is put into a disabled state.

disabledtextcolor
This attribute accepts color strings. This color will change the color of any text contained in the button's text field if the button is put into a disabled state.

strref
This is a STRREF that represents the string that should appear in the button.

text
This is hard coded text that should appear in the button. It overrides the strref attribute if it is present.

UIPane

UIPane is the generic 'container' for other UI Objects. Panes can't be rendered, but they can contain 'child' objects which can be renderable objects.

Every scene has a 'rootpane', which is automatically defined by the engine when a new UIScene is loaded from a XML file.

Child objects within a pane will be positioned with their x,y origin relative to the origin of the UI Pane that contains the child. UIPanes can also simulate buttons with the tupple attribute, so many of the attributes for UIPane are similar to those found under UIButton.

The following attributes are supported by UI Pane:

MouseDownSFX
Sound effect to be played when the Pane is clicked on. This only means anything if the Pane is a tupple style pane.

MouseUpSFX
Similar to a button up sound effect, this only means anything if the Pane is a tupple style pane.

MouseDragSFX
Sound effect for dragging a tupple style UI Pane object.

MouseDropSFX
Sound effect when releasing a dragged tupple style UI Pane object.

tupple
Setting this attribute to true makes the entire UI Pane behave like a button rather than just a container. This makes it possible to design more complicated buttons than normal, default UIButton tag allows for such as having a defined layout or multiple icons within the same button, etc. Once a Pane becomes a tupple, it can be clicked on, gain focus, lose focus, become enabled, become disabled, etc., just like a normal button. Note that it is still possible to place buttons within a tupple style pane that should work fine. So you could have a listbox row that is a tupple style pane that also has a toggle button on every row, for example.

OnLeftClick
The callback to be executed when a tupple style UI Pane is left clicked on.

OnLeftDoubleClick
The callback to be executed when a tupple style UI Pane is double left clicked on.

OnRightClick
The callback to be executed when a tupple style UI Pane is right clicked on.

OnRightDoubleClick
The callback to be executed when a tupple style UI pane is double right clicked on.

UIScene

The UIScene tag at the top of the XML files defines certain global parameters about the entire GUI window being defined in the file.

A scene doesn't have anything to render by default, but rather contains items that will get rendered. So a file that defines a UIScene and nothing else will not appear as anything in the game.

Some of the attributes for UIScene overlap with those of UIObject, even though UIScene does not inherit from UIObject, so this attributes will be repeated here.

The following attriibutes are supported by the UIScene tag:

OnCreate
This callback gets executed when the scene is loaded from the XML file. This is not necessarily a one time thing, as it is possible for scenes to get unloaded from memory and then reloaded from the file the next time they are needed. Additional detail about this will be included later in this article.

priority
This determines where scenes fall in the render order, in terms of which scenes should cover up other scenes.
The valid arguments to this attribute in order of highest priority to lowest are:
SCENE_TOOLTIP - Appears on top of any other GUI
SCENE_GLOBAL - Used for messageboxes generally.
SCENE_FE_FULLSCREEN - Pre-game full screen GUIs
SCENE_INGAME_FULLSCREEN - Full screen GUIs within the game.
SCENE_INGAME_SYSTEM - Escape menu and options screens.
SCENE_SCRIPT - GUIs brought up by script
SCENE_NWN1_DIALOG - The NWN1 style dialog box
SCENE_INGAME_MENU - The popup player menu
SCENE_INGAME - Most of the windows in-game
SCENE_INGAME_TARGET - The target box

OnDestroy
This callback gets executed when the scene is unloaded from memory.

OnAdd
This callback gets executed any time the scene is made visible.

OnRemove
This callback gets executed any time the scene is closed. Note that scenes can be closed and yet remain in memory. This in fact the default behavior. See idleexpiretime below for more information.

OnBackout
This callback gets executed when the user hits their Esc key and this scene is going to be closed as a result. If the backoutkey attribute is not true, then this callback will do nothing.

OnUpdate
This is the callback to execute every frame.

OnUnhandledMouseClick
This callback gets executed if a user clicks on the scene, but none of the contents of the scene did anything with the user's click.

updaterate
The time between updates, in seconds. If no value is specified, the scene will get an update every frame.

draggable
This determines if the entire scene is draggable. This is different from dragging a single UI Object within a scene as it moves the entire window. The default setting is false.

dragregion_x
dragregion_y
dragregion_width
dragregion_height
These 4 attributes are used to define the space on the scene that can be used to drag the scene. The numbers are in pixels. If a drag region is defined using these 4 attributes, the user can only drag the scene by clicking and dragging in the defined location. If no drag region is defined, the user can drag the scene by clicking anywhere on the scene where the click will not be used by a child object of the scene.

dragresizable
Determines if this scene can be resized by dragging the edges of it. This is used in the chat window for resizing, for example. The default setting is false.

dragresizeborder
This attribute defines the size, in pixels, of the border of the scene that can be clicked on in order to resize the window.

capturemouseclicks
If set to false, then mouse clicks should pass right through the background of this scene. Useful for semi-transparent overlays and other situations where it is expected that the user be able to click through the UI Object. The default setting is true.

capturemousevents
This is pretty much a redundant attribute. It does the exact same thing as capturemouseclicks.

fullscreen
This attribute can be true or false. By default it is false. It controls what happens to this scene when the resolution of the game changes. Scenes that have this attribute set to 'true' will not have their origins moved but their dimenions will be adjusted to the new resolution. Scenes that have this attribute set to 'false' will not be resized when the resolution changes but their origin will change to stay roughly in the same part of the screen that the window appeared in before.

width
Width of the scene in pixels. The argument 'SCREEN_WIDTH' can also be used to make this scene always match the width of the full screen.

height
Height of the scene in pixels. The argument 'SCREEN_HEIGHT' can also be used to make this scene always match the height of the full screen.

x
The x origin for the window. The following string arguments are also valid: ALIGN_CENTER, ALIGN_LEFT, ALIGN_RIGHT. Defaults to 0.

y
The y origin for the window. The following string arguments are also valid: ALIGN_CENTER, ALIGN_TOP, ALIGN_BOTTOM. Defaults to 0.

expiretime
This is the amount of time in seconds a scene should be up before it is automatically removed from view and unloaded from memory. If 0 or not set, then the scene will never be automatically removed from view.

idleexpiretime
This is the amount of time in seconds a scene should not be visible before it should be unloaded from memory. This can be used to unload scenes that were shown once that will not be needed again anytime soon. The next time the scene is requested, it will be loaded from disk. This makes it possible to sometimes do quick testing of GUI changes by setting a short idleexpiretime, closing the window, then reopening it to see what it looks like with the new changes on disk.

autolayout
This attribute is only of interest in message-box style GUI screens. If enabled, the engine will attempt to automatically position the text, the 'okay', and the 'cancel' button in a classic message box layout. If left false, then the engine will not attempt to arrange any of the contents of the messagebox when the message box is requested. It is false by default.

modal
If set to true, then this UI scene will block access to the game or any underlying GUI screens until the window is closed. It is false by default. Note that scripts that bring up GUIs can override this parameter based on the parameters passed in to the script function.

fadein
The time in seconds this scene should take to fade in completely when opened.

fadeout
The time in seconds this scene should take to fade out completely when closed.

minwidth
This attribute is defunct and no longer does anything.

minheight
This attribute is defunct and no longer does anything.

scriptloadable
In order for a server script to have any control over this GUI at all, this attribute must exist in the UIScene tag and must be set to true. It is false by default. If false, than all script functions that attempt to manipulate a user's GUI will fail.

backoutkey
If this attribute is set true, then use of the backout key ('Esc' key by default) will cause this window to close. The backout key follows a defined set of logic for determining what to do when it is used. First it closes any open 'windows' in the reverse order that they were opened (Most recent window opened is closed first). If there are no windows to close, it clears the player's target. If the player has nothing targetted, it brings up the in-game options screen.

Long Posts and post summaries

On other blogs, I've seen that authors will write a summary or intro to the post and then there will be a link the reader can click to go to the full length article. Given that some of my technical posts are going to be very long, I'd like to do the same thing here. But I've read some of the guides on blogger as well as other various websites about how to do that and the instructions are real head scratchers, telling me to look for tags that don't exist to insert code.

Considering the guides tend to be really old, all I can imagine is that they are out of date and that some new approach is required to accomplish what I'm looking to do. If anyone has any advice or information about implementing that feature for this blog, I'd love to hear about it.

An example of what I'm talking can be seen on this blog here:
http://afkgamer.com

If you flip through a few pages of posts, you'll find longer posts where he sets up the post, and then there's a 'Read the rest' link or whatever to follow in order to read the rest of the lengthy post.