parent
4d456139a5
commit
f40613d538
@ -1,3 +1,116 @@ |
||||
# lel-guecs |
||||
# LEL & GUECS |
||||
|
||||
A GUI library for games that's so small you won't even know its there. |
||||
This project is two small components that make up a minimalist GUI library for game development. |
||||
The purpose is to provide _only_ a simple layout engine and an ECS (Entity Component System) |
||||
structure for you put your existing graphical elements into. It's currently working for [SFML](https://www.sfml-dev.org/) but should be easy to retarget or recreate. You can also use only LEL or GUECS depending on your needs. |
||||
|
||||
LEL stands for _Layout Expression Language_ and is a layout engine that uses a simple "wiki style" |
||||
language for specifying a GUI's layout grid. Rather than use nested containers or similar tree-like |
||||
code structures, a LEL layout is just a string that looks like this: |
||||
|
||||
``` |
||||
[col1_row1|col2_row1] |
||||
[col1_row2|col2_row2|cheese_doodles] |
||||
``` |
||||
|
||||
The LEL parser will read this, and based on the dimensions of its space, determine the size of each |
||||
cell here. In this case it will create 4 cells, dividing the space into 4 quadrants. You can then |
||||
access these cells by their names `"col1_row1"` and place your own GUI elements there. The LEL |
||||
language can create ragged rows, spans, and most anything you need for a layout (to a point). |
||||
|
||||
You'll also notice that you can name these cells almost anything. The last row has `cheese_doodles` |
||||
rather than a column/row identifier. |
||||
|
||||
GUECS (Graphical User Entity Component System) is a _very_ simple ECS that lets you quickly |
||||
build your GUI inside a LEL layout. It works like most ECS systems whereby there are no classes |
||||
like `Button` or `Input` but instead you use components to create these. For example, a button is |
||||
simply: |
||||
|
||||
```cpp |
||||
gui.set<guecs::Rectangle>(id, {}); |
||||
gui.set<guecs::Label>(id, {L"Click Me"}); |
||||
gui.set<guecs::Clickable>(id, { |
||||
[](auto, auto){ handle_click(); } |
||||
}); |
||||
``` |
||||
|
||||
This creates a rectangle with a label that when clicked call the `handle_click()` function. This |
||||
makes it very easy for you to target your own graphics libraries since you only need to write your |
||||
own components and toss them into the `guecs::UI` class like this. |
||||
|
||||
## What is it NOT? |
||||
|
||||
LEL does _not_ try to create deeply nested complex layouts. It can create reasonably complex _two |
||||
dimensional_ layouts, but if you need very complex nested layouts then its best to create multiple |
||||
components with their own LEL expressions. |
||||
|
||||
LEL also doesn't try to do automatic rebalancing and recalculating of its layout. Since every game |
||||
framework (and every game?) starts off with fixed size screens it doesn't make sense to create a |
||||
layout engine that can handle the equivalent of a web browser HTML/CSS engine. If you change |
||||
the dimensions of your screen, then simply re-initialize the LEL layouts. You most likely have to |
||||
do this anyway in your game engine. |
||||
|
||||
That being said, LEL's engine is reasonably fast so recalculating the layout won't be expensive. |
||||
Just don't expect it to rebalance some douchebag swinging a window corner resize around at 200 FPS. |
||||
|
||||
GUECS also doesn't include many ready-made components. It has basic building blocks for creating |
||||
your own components, but it's assumed that you're probably interested in creating your own stylized |
||||
UI components to match your game's design and your game engine's functionality. Many times game |
||||
developers end up creating all of their own UI elements so just do that but let GUECS help you keep |
||||
it all organized. |
||||
|
||||
## Building |
||||
|
||||
First, you'll need to install [meson](https://mesonbuild.com/) to run the build. One _MASSIVE_ |
||||
warning is that `meson` will run each dependency's build, which will require you to have |
||||
dependencies installed in some OS (like Linux), but then my build will _completely ignore your broke |
||||
ass hacked up bullshit packages_. I'm serious, nothing on your computer is trusted and I download |
||||
everything. If you build against your versions of the packages then you're doing it wrong (I'm |
||||
looking at you Fedora and Debian). |
||||
|
||||
Easiest way to try the build is with this: |
||||
|
||||
```shell |
||||
git clone https://git.learnjsthehardway.com/learn-code-the-hard-way/lel-guecs.git |
||||
cd lel-guecs |
||||
make reset |
||||
make run |
||||
``` |
||||
|
||||
That should kick off the build attempt, and then you'll be told what's missing for the build to |
||||
continue, _BUT_ this is platform dependent as I said before. For example, on Windows it just builds |
||||
by downloading everything, OSX already has most things, and Linux is...well...Linux. |
||||
|
||||
## Using LEL |
||||
|
||||
Coming soon.. |
||||
|
||||
## Using GUECS |
||||
|
||||
Coming soon.. |
||||
|
||||
## Making Your Own |
||||
|
||||
I believe that these two systems are simple enough that anyone can recreate them in their preferred |
||||
language for their preferred system. I'll provide a guide here that explains how to do this, and |
||||
encourage you to create your own rather than use mine. The key things to realize are: |
||||
|
||||
1. It's easier to describe an irregular 2D grid than it is to mangle a tree of objects withing |
||||
objects within trees within objects. |
||||
2. It's easier to process a 2D grid, and easier to target its elements by name rather than trolling |
||||
through a tree of objects within trees within objects. |
||||
3. It's easier to construct the controls you need through an ECS style set of primitives than it is |
||||
to use an existing GUI component...but really only in video game development. In a desktop app |
||||
it's probably better to use that OS's stock components. |
||||
4. Something like LEL or GEUCS is fairly easy to understand and implement and does _not_ require |
||||
insane knowledge of dark corners of C++. Maybe just like...slightly dim corners. |
||||
|
||||
Give it a shot and soon I'll have a guide on how to do it. |
||||
|
||||
## Contact Me |
||||
|
||||
You can email me at help@learncodethehardway.com and I also stream my development of this (and other |
||||
fun stuff) two times a day at 10AM and 10PM EST (Miami/NYC) time. Feel free to stop by and talk to |
||||
me about it and have me fix things you find. It's even better if you shoot me a bug report by email |
||||
then come by and ask me about the email. That way you can send me copy-paste error outputs or |
||||
possible patches (if you have them). |
||||
|
Loading…
Reference in new issue