diff --git a/README.md b/README.md index 28b1ab4..73a95a3 100644 --- a/README.md +++ b/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. \ No newline at end of file +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(id, {}); +gui.set(id, {L"Click Me"}); +gui.set(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).