UI Subsystem - Grisgram/gml-raptor GitHub Wiki
With Release 3.0
of raptor, a complete rewrite of the UI took place.
All controls, windows and MessageBoxes have been rewritten and now offer functionality that you know from Windows Development (if you ever did that...)
First thing to know is, that there are two layers of controls available in raptor
.
There are the base controls, which reside in UI\controls
folder of raptor and are all prefixed with "Raptor" in their name (like RaptorLabel
, RaptorTextButton
,...).
⛔ You should not modify these controls!
The second layer, are "your" controls, which are located in the _gml_raptor_ui_
folder in the root of your project.
✅ These controls are here, to be adapted to your own needs.
They are all "empty" child object of the Raptor*
internal controls.
Change variables, sprites, behavior, add code, do whatever you need to do with these controls.
Why are there two layers?
With 3.0, raptor was split into several smaller packages. The raptor core
contains everything raptor, as it always has been. In addition to that, there are now some smaller packages available, that are safe from being changed through a raptor update. So far, when you tinkered with the internal controls of raptor, you were always at risk, when updating, that I might have changed something in the controls and maybe your work gets overwritten.
With the new system, you are safe. You can update raptor any time, but your controls will not be affected.
With that being said, let's take a look at what is contained in the raptor UI subsystem
:
- All controls are implemented to auto-resolve strings through the LG Localization subsystem and format text through Scribble
- All controls can be
docked
,aligned
,anchored
orpositioned freely
in their container - Available containers are
the desktop/game ui layer
, theWindow
control or the invisiblePanel
control - You add controls in one of these ways:
- Create your hierarchy/layout through the ControlTree in code (this is the new recommended way since 3.0)
- Add them to the "desktop" of your game by adding controls to the
UI_ROOT
panel, which is available globally in every room (Each room has its ownUI_ROOT
), declared in the RoomController - Place them freely in the Room Editor, as you always did
- Future Feature: Use the UI Designer tool (working on it, not yet released)
Also, new with release 3.0, there's theming and skins implemented in raptor. Basically, this is a set of predefined colors you want to use throughout your game's ui. All controls are set up to use the app theme through defined constants, which you set in the Game_Configuration
.
UI Themes and UI Skins tell you everything, you need to know about this feature.
The controls are built object-oriented (as far as GML allows this) and follow this hierarchy:
Control | Description |
---|---|
Base Controls | |
Label | The most basic UI element, just a scribble string (text ) |
Containers | |
Panel | An invisible container that helps you aligning your layout |
ScrollPanel | A Panel with scrollbars where you can assign any Content and it will scroll it, no matter, how big it is. This control uses the new function gpu_set_scissor() provided by GameMaker, makes the clipping area directly on the graphics card and is therefore blazing fast!
|
Window | A very powerful, movable, sizable dynamic window which can be used for every dialog |
WindowXButton | A special ImageButton , used by the Window object |
MessageBoxWindow | A special Window , used by the MessageBox Functions |
MessageBoxWindowXButton | A special WindowXButton , used by the MessageBoxWindow object |
Tooltips | |
Tooltip | Little info-tag when hovering the mouse over a control |
Clickable Controls | |
TextButton | A standard button, containing a scribble-string as caption (text ) |
ImageButton | A standard button, containing a scribble-string as caption (text ) and an image as icon (sprite_to_use ) |
Slider | A highly configurable value slider control |
Checkable Controls | |
CheckBox | A standard checkbox |
RadioButton | A standard radiobutton. You can have multiple radio groups in one container |
Input Controls | |
InputBox | A comfortable text input control with lots of features. This control offers so much functionality, that I spent it its own InputBox sub page |
Mouse Cursor | |
MouseCursor | A sprite-based mouse cursor replacement for the standard mouse cursor. Just drag one into your room in any layer. It works transparently and fully automated |
MouseCursorCompanion | An attachment-object for your MouseCursor
|
I have created some lightweight controls, which help a bit with common tasks. Nothing too special, but still things, you do over and over again, especially when you do game jams and create new games frequently.
They can be found in the _gml_raptor_ui_\helpers
folder of the project template and are ready-to-use, without any configuration needed.
Control | Description |
---|---|
GameVersionLabel | Child of Label which reads the version information from the game's version.json file and sets this as its text . This is the most easy way to display your version/build at the main screen |
CopyrightLabel | Also a child of Label , with text set to =legal/copyright , so it will display copyright information from the localization file |
FPSTracker | A simple control that measures the render time of frames and displays a text like 60 FPS
|
StoryTeller | A child of Label which utilizes scribble's Typist, to slowly write text, as if some character would be talking |
When you start the Example Project Demo, you see these objects in action.
Read on in UI Themes or UI Skins or head directly to Base Controls.