First cut at the README.
This commit is contained in:
Zed A. Shaw
parent
4d456139a5
commit
f40613d538
1 changed files with 115 additions and 2 deletions
117
README.md
117
README.md
|
|
@ -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…
Add table
Add a link
Reference in a new issue