lel-guecs/README.md

# LEL & GUECS

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).