tcharles
/
wiki
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Updated nwn-2-gui-scripting.md

This commit is contained in:
Guest 2018-12-17 13:47:44 +00:00 committed by Wiki
parent f146c3c060
commit f35716745f
1 changed files with 13 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
nwn-2-gui-scripting.md
View File

@ -1,8 +1,6 @@
<!-- TITLE: Nwn 2 Gui Scripting -->
<!-- SUBTITLE: A quick summary of Nwn 2 Gui Scripting -->
GUI Scripting
# Resources
- [oeiprogrammer](https://oeiprogrammer.blogspot.fr)
@ -13,11 +11,11 @@ GUI Scripting
The GUI are written in a non standard form of XML.
- The first line must be something like `<?xml version="1.0" encoding="utf-8"?>`
- Attributes values can be delimited by `'`, `"` or can end with a space
+ This does not work: `OnLeftClick=UIObject_Misc_ExecuteServerScript("gui_myscript","Hello World")` because OnLeftClick value has no delimiter and will end after `Hello`
- Attributes values can be delimited by `'`, `"` or if not delemited ends with a space
+ Example: this does not work: `OnLeftClick=UIObject_Misc_ExecuteServerScript("gui_myscript","Hello World")` because OnLeftClick value has no delimiter and will end after `Hello`
- Auto-closing tags are accepted `<UIText />`
- If you repeat an attribute twice, the GUI will not load
- The `UIScene` element is never closed
- If you repeat an attribute twice inside the same XML tag, the GUI will not load
- The `UIScene` tag must never be closed
# Rules
@ -32,22 +30,24 @@ The XML file name must not exceed 32 characters (TODO: with or without extension
## Variables
The GUI file can store client-side variables that can be either local (only accessible through the current UI) or global (all UI share the same variables). They are identified by an integer index, and always store a string value.
The GUI file can store client-side variables that can be either local (limited to the current UI) or global (shared across all UIs of a player). They are identified by an integer index, and always store a string value.
Examples: `local:0`, `local:1337`, `global:42`, ...
## Events
Events are special attributes that can trigger [callbacks](#callbacks) when specific actions are executed by the player (ex: clicking a button) or the client's engine (ex: when a frame is rendered).
## Functions
## Callbacks
Functions are special attribute values that execute specific actions either on the client-side (setting local gui variables, changing gui appearance) or on the server-side (executing scripts).
Callbacks are special attribute values for event attributes, that can execute specific actions either on the client-side (setting local gui variables, changing gui appearance) or on the server-side (executing scripts).
It is better to put functions inside double quotes: `OnEvent="Callback('arg0','spaced arg',42)"`. This way it is compatible with XML standards and the function arguments values can contain spaces. Otherwise the UI won't load because the space will be treated as the end delimiter for the attribute value.
_TODO_: callback parameter parsing & delimitation (ie what happens if `UIObject_Misc_ExecuteServerScript("A,B","C",D,'E,F','G',H)`)
> _TODO_: callback parameter parsing & delimitation (ie what happens if `UIObject_Misc_ExecuteServerScript("A,B","C",D,'E,F','G',H)`)
You can use multiple functions on a single event by appending 0, 1, ... to the event name, ie `OnEvent0="DoThis()" OnEvent1="ThenDoThat()"`. Note: if you don't number events correctly, the GUI will not load.
You can execute multiple callbacks on a single event by appending 0, 1, ... to the event name: `OnEvent0="DoThis()" OnEvent1="ThenDoThat()"`. **If event numbers are not ordered correctly, the GUI will not load**.
The most useful callback is certainly `UIObject_Misc_ExecuteServerScript` that allows you to execute nwscript for any event from any UI element: `OnEvent="UIObject_Misc_ExecuteServerScript('gui_yourscript','AnyArgumentList',local:25)"`
The most useful callback is certainly `UIObject_Misc_ExecuteServerScript` that allows you to execute a server-side nwscript for any event from any UI element: `OnEvent="UIObject_Misc_ExecuteServerScript('gui_yourscript','AnyArgumentList',local:25)"`. Note: If a player is able to customize any GUI, he can execute arbitrary code on the server, and can be problematic for online servers.
@ -58,7 +58,7 @@ The most useful callback is certainly `UIObject_Misc_ExecuteServerScript` that a
+ Executing console commands `DebugMode 1` and `Guidebug`
+ Running [Skywing's client extension](https://neverwintervault.org/project/nwn2/other/nwn2-client-extension) and executing the in-chat command `/guidebug`.
- When an attribute appears twice on the same element, the UI fails to load.
- Often NWN2 GUI files start with `<?xml version="1.0" encoding="utf-8">`. This can safely be replaced by `<?xml version="1.0" encoding="utf-8"?>`.
- Often NWN2 GUI files start with `<?xml version="1.0" encoding="utf-8">`. This can be replaced by `<?xml version="1.0" encoding="utf-8"?>` which generally fix syntaxic coloring.
- Any standard-compliant XML parser will fail at parsing NWN2 UI files. You can find a custom XML parser implementation for nwn2 [here](https://github.com/CromFr/NWN2GuiViewer/blob/master/source/nwnxml.d). Warning: written in the D language.