GUI Files Explained¶
Each GUI comprises several files on disk, such as the GUI scripts, material definition files, and texture images.
GUI files can be created with the GUI Editor, written by hand, or a combination of those:
- The GUI Editor allows users to define and design the contents and layout of the windows that compose a GUI. However, the work in the GUI Editor is focused mainly on static aspects like window position and size, texts, colors, borders, etc.
- Everything “dynamic” and all sorts of effects can, by their nature, not be added by means of the GUI Editor, but must be written as custom, hand-crafted script code that augments the script that is auto-generated by the GUI Editor each time the “static” part of the GUI is saved.
One key question addressed in this section is how we can combine hand-crafted script code and editor-edited script code, while keeping both separated so that they don’t overwrite each other.
In general, when you save a GUI in the GUI Editor, the editor creates or re-creates some of the files it is composed of, updates others, and leaves alone the rest. The result is normally exactly what you want and expect, but sometimes you may wish to or must hand-tune the details (such as the GUI scripts or material definitions) without and independently of the GUI Editor. In such cases, it is very helpful to understand the files that belong to a GUI.
This section explains the files that together form a GUI, how they relate to each other, and how hand-crafted and editor-created scripts can peacefully coexist.
One directory per GUI¶
Although not a technical requirement and not enforced by the Cafu GUI code (and in fact, at the time of this writing, not yet implemented by the example GUIs that ship with Cafu), it is highly recommended to save each GUI in a directory of its own. This
- explicitly groups all files that logically form and belong to the GUI, and
- makes packaging a complete GUI in a
my_GUI.ziparchive possible, so that the GUI can easily and safely be distributed, shipped and handled.
The name of the directory should match the file name of the GUI. That
is, if your GUI’s file names are
CallLift_main.cgui, it should be stored in a directory with the same
CallLift/ (or in a zip archive with the same base name
Note that when you are saving a new GUI that does not yet have a separate directory, you can use the “New Folder” button (or right-click context menu) of the “Save” dialog to create such new directories as required.
cgui GUI definition files¶
cgui files are the core files of the GUI: They contain the
definitions for the positions, sizes, colors, texts, effects,
animations, hierarchy and other properties of the windows that form the
cgui files are Lua scripts¶
The Cafu Engine and the GUI Editor load
cgui files as
Lua scripts, and as such they can be inspected
or edited in a text editor.
The GUI Editor is usually used to create and edit the static aspects of
GUI windows, automatically generating the related script code when
saving the file. Dynamic aspects like animations or other kinds of
effects typically require adding custom script code, so editing
files (usually the
_main.cgui file) is something that you’ll likely
want to do often.
Augmenting GUI Editor scripts with custom script code¶
For one GUI there is usually a pair of
cgui files, one suffixed
_init.cgui and one suffixed
_main.cgui. For example:
d:\Dev\Cafu\Games\DeathMatch\GUIs> dir Teleporter\*.cgui Teleporter_init.cgui Teleporter_main.cgui
_main.cgui file is for your hand-written GUI script code, if
any, and is never touched or overwritten by the GUI Editor (with one
exception, see below).
The GUI Editor also writes a secondary
cgui file whose name ends
_init.cgui. This file is written anew each time the GUI is
saved, and contains GUI window definitions whose script code was not
hand-crafted, but who were created or edited in the GUI Editor.
cgui files are linked as follows: When the Cafu code loads a
GUI, it opens the
_main.cgui file (
file contains a statement like
-- Include the GUI Editor generated file. dofile("Games/DeathMatch/GUIs/Teleporter/Teleporter_init.cgui"); -- Add your hand-written custom code below this line. -- ...
in order to include and process the secondary
_init.cgui along with
the main file.
The only exception when the GUI Editor touches the main
Teleporter_main.cmat file is when the file does not yet exist, or
doesn’t contain the
dofile() reference to the init file. In this
_main.cgui would not be loaded at all, and thus the GUI
Editor inserts the
dofile() line into the
In summary, the goal of keeping two separate
cgui files that are
linked as described above is to keep your hand-crafted GUI script code
and the GUI Editor edited window definitions cleanly separated, without
any danger of one overwriting the other:
- When you edit your GUI in the GUI Editor, you only load and save file
- All hand-written code enters file
- The connection between the two files is made by the
cmat material definition files¶
cmat files contain the material definitions for the graphical
elements of this GUI.
At the time of this writing, the materials for GUIs are still defined in the “global” material scripts for the MOD, but for the future we intend to have separate material scripts for each GUI that work analogous to cmat material definition files for models.