UI Configuration
Developer note
PG_Engine currently uses a yaml schema to configure a UI. I am aware this implementation is far from ideal but an XML loader has not yet been developed for this library whereas one for yaml exists.
The last of the configurations is that of the UI. In this part of the configuration we will only be handling the layout, not the functionality (which should be done through scripts). Note that the public API of the built in UI is heavily influenced by pygame_gui and thus requires use of pygame-ce over a standard pygame installation when using this library. Out of the box, this library provides a UI implementation using pygame-gui.
ui:
loader: PygameGuiUILoader
config: config/ui.yml
registry: PygameGuiRegistry
Note
scripts cannot be attached to UI elements, though a dummy gameobject with a BROADCAST scope can work as standin for capturing and handling UI events.
Although reading through what UI library you decide to use will be much more valuable than just trying things in this UI i would still like to point out a few things that do not involve specific implementations of one or another library though i will be using pygame_gui for this example.
start_button:
classpath: pygame_gui.elements.UIButton
size:
- 100
- 20
offset:
- 0
- 0
anchors:
centerx: centerx
centery: centery
args:
text: A button
parent: default
To start of there are 3 required parameters, classpath, size and offset. Classpath here being by far the most important one, this parameter tells your program where to import a UI element from and is the same as the fully qualified import you would use in a python module (i.e. import pygame_gui.elements.UIButton). Size and offset here are are used to construct the rectangle where the UI element will be placed.
Note
The design decision was made to keep them split over a single rect parameter to accomodate standardized sizes from a reference file without interfering too much with tiling of multiple similar elements.
Next are anchors and args, anchors are, in this case, a specific implementation of pygame_gui and might not have any meaning if another library is being used, They are provided as a part of the public API but may certainly be omitted or left empty (more information at pygame_gui layout_guide). Args as well is a parameter that may be left empty or omitted and, like most other configurations in this library defining args are used to pass extra arguments to the configured class in keyword form.
Warning
when defining anchors relative to another element pygame_gui expects that element to already exist as an instance of one of it’s classes.
The last parameter is parent, like the above mentioned two it is also not required but is used to hierarchically structure UI elements. It simply takes the name of another UI element and will be considered a direct child inside of that element.
Note
PygameGuiUILoader will automatically create pygame_gui.core.UIContainer instances for each scene covering the ui manager’s screen space.
Warning
UI elements without parent will not be managed by scene switching or UI hierarchies.
If you prefer to not use any gui elements (or otherwise have no gui library installed) PG_Engine still requires defining a UI manager and UI Loader. if none are available a DummyUILoader and DummyUIManager are provided to function as placeholders.
If you are following this tutorial the following changes are required to disable it’s use.
ui:
# loader: PygameGuiUILoader
loader: DummyUILoader
config: config/ui.yml
# registry: PygameGuiRegistry
scenes:
- default
- main_scene
debug_mode: false
fps: 60
singleton_instances:
- !classinit CollisionSystem
- !classinit EventSystem
- !classinit BaseSystemController
- !classinit Camera2D
- !classinit BaseRenderer
# - !classinit PygameGuiUIManager
- !classinit DummyUIManager
- !classinit
type: GameObjectBuilder
args:
builder_class: !classget GameObject
builder_kw:
transform_class: !classget TransformComponent2D
- !classinit
type: SceneBuilder
args:
builder_class: !classget Scene
- !classinit BaseGame