Quick Gui Script Tutorial
Introduction
Guis are not very hard to grasp once you've made a couple of level scripts. It is basically the same as any other programming except like in any language you have a specific format and syntax you must follow.
This tutorial is by no means a full blown "How To" book like my previous work. I really don't feel comfortable going all out on this subject because the knowledge in this area is very limited. That and I hate being proven wrong.
Limitations
So far those of us that have been fooling with guis have been running into a couple of limitations. I'll name what I can think of off the top of my head. Those of you who can think of some other things please add your comments.
Quite a few of us here have been at one time or another attempting to control multiple objects independantly through the use of a gui. At the moment, it is not 100% certain that it is or is not possible.
It seems that even though you can assign multiple targets to a gui, you cannot trigger them seperately. Basically this means until someone finds a solution all of your guis will be limited to controling what will appear as one single event. For instance, unlocking a door.
That event can be comprised of multiple functions occuring but keep in mind that they will all occur at once. In other words, you can open a door, turn on a light, and raise a platform at the same time but you can not trigger each event individually.
Assigning a Gui to a Surface
Become familiar with the material textures/common/entitygui. You can't apply a gui to anything without it.
I am assuming that you already know how to apply materials to a single surface although if you don't I suggest you get familiar with mapping first.
Next, you take that brush and turn it into a func_static.
One thing I am not certain of and maybe someone can check on it for me is if you can apply materials to the surfaces of models. In fact, I believe the keypad is applied to a model but I'm too lazy to confirm it.
If your interested... In Lightwave for example, try selecting a face and assigning a separate surface to it. Then rename that new surface to textures/common/entitygui.
A Couple of Console Commands
Your going to need to know a couple of console commands\cvars to test out your guis without making a special "testgui" map. I wish I knew this when I first started screwing around.
EDIT: This section has been replaced with the
GUI Command Reference (Wiki) in hopes of providing a more complete and accurate list.
Variable, Property, and Flag References
You may have noticed a couple of statements like this...
Code:
gui::player_ammo
Down::matcolor
gui::gui_parm1
...above and felt a little confused.
Well I suppose there is good reason to be confused. It's not a traditional way to referece variables. Basically I must address what window/object the variable I want to reference is located in. Here take a look at the syntax of a variable reference.
Code:
<Window or Object>::<Variable>
So if I want to find out how much ammo the player has and display it on my gui I can by referencing it. Here's an example. Let's say I have a window called Display and I want to send the ammo value to its text property. This would work.
Code:
set "Display::text" "gui::player_ammo";
Let's say that I want to retrieve the value of a custom key I had set in the editor. In this case well call the key gui_parm1. Let's also say I want to pass this value to the same text display as above. This would work.
Code:
set "Display::text" "gui::gui_parm1";
And one other use could be setting the value of a property for a transition. Here is the example used above for the command transition.
Code:
transition "Down::matcolor" "1 1 1 0.2" "1 1 1 0.9" "200";
Gui Scripting FormatTo explain this better here is the gui I created from scratch. It is a bare-bone gui script. It was what I was attempting to use to control multiple objects and failed at.
Don't worry I've stripped it of all the crap code it had that didn't work. It's really simple and should prove good enough.
Code:
windowDef Desktop {
rect 0, 0, 640, 480
backcolor 0, 0, 0, 1
windowDef Background {
rect 0, 0, 640, 480
background "rich/gui/bg"
matcolor 1, 1, 1, 0.5
}
windowDef Reflect {
rect 0 ,0 ,640 ,480
background "keypadglass"
matcolor 1, 1, 1, 0.2
noevents 1
}
windowDef Bglow {
rect 0, 0, 640, 480
background "guis/assets/cpuserver/bglow.tga"
visible 1
matcolor 0, 1, 0.8, 0.2
}
windowDef Up {
rect 265, 75, 110, 115
background "rich/gui/up"
matcolor 1, 1, 1, 0.2
visible 1
onMouseEnter {
transition "Up::matcolor" "1 1 1 0.2" "1 1 1 0.9" "200" ;
set "gui::gui_parm" "0";
}
onMouseExit {
transition "Up::matcolor" "1 1 1 0.9" "1 1 1 0.2" "200" ;
}
onAction {
set "cmd" "activate; play guisounds_click";
}
}
windowDef Down {
rect 265, 290, 110, 115
background "rich/gui/down"
matcolor 1, 1, 1, 0.2
visible 1
onMouseEnter {
transition "Down::matcolor" "1 1 1 0.2" "1 1 1 0.9" "200" ;
set "gui::gui_parm" "1";
}
onMouseExit {
transition "Down::matcolor" "1 1 1 0.9" "1 1 1 0.2" "200" ;
}
onAction {
set "cmd" "activate; play guisounds_click";
}
}
windowDef Left {
rect 102, 198, 150, 85
background "rich/gui/left"
matcolor 1, 1, 1, 0.2
visible 1
onMouseEnter {
transition "Left::matcolor" "1 1 1 0.2" "1 1 1 0.9" "200" ;
set "gui::gui_parm" "2";
}
onMouseExit {
transition "Left::matcolor" "1 1 1 0.9" "1 1 1 0.2" "200" ;
}
onAction {
set "cmd" "activate; play guisounds_click";
}
}
windowDef Right {
rect 388, 198, 150, 85
background "rich/gui/right"
matcolor 1, 1, 1, 0.2
visible 1
onMouseEnter {
transition "Right::matcolor" "1 1 1 0.2" "1 1 1 0.9" "200" ;
set "gui::gui_parm" "3";
}
onMouseExit {
transition "Right::matcolor" "1 1 1 0.9" "1 1 1 0.2" "200" ;
}
onAction {
set "cmd" "activate; play guisounds_click";
}
}
}
As you can see everything is contained in the main window "Desktop". Again we are talking about child parent relationships just like in scripting.
Also all the windows that act as buttons contain listeners that trigger specific events.
You may notice one difference in particular between my gui and some of the other guis in the game. My gui contains no time related animation section.
If you have no idea what I'm refering to it looks kinda like this.
Code:
windowDef Thing {
notime 1
onTime 0 {
set "Button1::noevents" "1" ;
set "Button2::noevents" "1" ;
set "Button3::noevents" "1" ;
set "Button4::noevents" "1" ;
set "Button5::noevents" "1" ;
transition "Button1::rect" "190 270 256 32" "190 450 256 32" "200" ;
transition "Button2::rect" "190 310 256 32" "190 450 256 32" "200" ;
transition "Button3::rect" "250 350 139 32" "250 450 139 32" "200" ;
transition "Button4::rect" "253 390 128 32" "253 450 128 32" "200" ;
transition "Button5::rect" "253 430 128 32" "253 450 128 32" "200" ;
}
onTime 0 {
transition "PopUp::matcolor" "1 1 1 0" "1 1 1 1" "100" ;
transition "PopUp::rect" "177 440 286 40" "177 271 286 209" "200" ;
}
}
"But why rich? I wanna do really cool animations."
Good. That's real good that you wanna create cool animations. Unfortunatley, I haven't gotten around to this part of gui scripting. It looks pretty simple and I could speculate on how it works but I have never actually played with it so I would just be running my mouth.
I personally think its more important to be sure my gui functions correctly before I throw a bunch of eyecandy out there.
You could easily get carried away with animations and such and then find out later when your coding the actions that there is a limitation that you didn't know about before that completely changes your design.
Anyway, if someone would like to cover this final topic or add something, please do. If not, I'll get around to it eventually. But currently, it's not even on my to do list.
Conclusion
Well, there you have it. That is guis in a nutshell. I didn't show you step by step or anything but if you're willing to dedicate some time to reading and experimenting this should get you on your feet.
If anyone has anything at all to add, correct, or ask go right ahead as I am sure this "excuse" for a tutorial has a couple boo boos.
I have messed with one kind of animation in relation to GUIs (had it mentioned briefly in a thread), which was animation of the alpha on the 'matcolor' for a channel. This effect is seen on a lot of things, such as the pulse/flicker of the empty message on the machine gun (yes that's a GUI).
How I did it was I created a table array in a material file (I haven't tried putting it elsewhere, that's where I found others though so I did the same), such as:
table mguiTable {.5, 1,.5, 1,.6, 1,.5, .8,.5, 1,.5, .6 }
Then on the alpha line of your matcolor definition you can refer to this table and reference it to time. The time is a counter in miliseconds (ex. time being 500 is .5 seconds). An example of a table being used in reference to the animation of the alpha channel of a gui element is here:
matcolor 1, 1, 1, pdflick2 [ time * .0025 ] / 4.5
The syntax for that is:
pdflick2 - this is the name of the array
[ value ] - this is the position in the array. 0 is the first, 1 is the second, etc.
So you can go through the series of values based on how time passes. This is obviously limited to looping single second animations though without the usage of other variables to keep track of how your GUI elements are moving/transitioning. Also, I believe there is another type of table called 'clamptable'. I have not messed with it that much yet, but I believe the primary difference is as follows:
table - An array of values, if the resultant operand in the tablename[value] is not an exactly whole number it samples in between the values in the table. For example, if you had your table with the values { 0, 1} and you called tablename [0.5] (due to your math in relation to time) it would return .5 as the value, even though that's not a value in the table, it blends between the values.
clamptable - Same thing as a table, except it does not have interpolation between the returned result and will only give you back the values within the table. More for 'snappy' type animation such as a muzzle flashes or turning something off, whereas table is more 'pulse' oriented in its animation implementation.
So that's the kind of animation i've messed with. Those same principles could be used for animation of other types of values within the GUI system, not just the alpha channel of matcolor.
rich_is_bored wrote:
You may have noticed a couple of statements like this...
Code:
gui::player_ammo
Down::matcolor
gui::gui_parm1
...above and felt a little confused.
Well I suppose there is good reason to be confused. It's not a traditional way to referece variables....
:: is used in c++ and is a standard and sometimes unavoidable part of the syntax. When you define class member functions is when you normally need it, and its the usage it is associated with the most. What it is actually for though is getting a variable from a specific 'scope' i.e. a class, or namespace. This is useful for recycling code, and doing some other things (like using static member functions for a window procedure, enforcing a singleton etc...).
One thing that stands out to me about this scripting language over the map one... is that the command syntax looks to me like this language is meant to be interpreted and never compiled. (ASM style syntax, no consistency with " , ;, obviously uses new-lines/whitespace etc...)
said i would never produce a script but i guess im going to anyway
ok here is the concept , it works like the outerdoor_open _multiclick.gui
in which 2 have made 2 gui panels
heres the interaction
1. you see gui 1 in game
2. click gui 1 and that makes gui 2 appear
3. slight delay
4. gui 1 reappears
5. you can click it again if you want
im trying to use the above .gui scripted file to make it work
ie..... guis/transfer/outerdoor_open _multiclick.gui
any advice on what to change to change the gui image
so i keep the attributes of that gui script but my custom gui appears instead of the stock image ingame?
which lines in that file contain the the code for what image is produced on the ingame gui
see the script is exactly waht i want it to do but the gui image is what i wanna change........thanks
gui monster spawning without scripts
http://www.doom3world.org/phpbb2/viewto ... highlight=