From 6b7b987940cdd6e28991957cec56571673b425ab Mon Sep 17 00:00:00 2001 From: Lorenzo Cogotti Date: Wed, 17 Aug 2022 13:35:30 +0200 Subject: [PATCH] [README] Improve project description and usage docs. --- README.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 96 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 03c83e2..ddf2ba1 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,106 @@ Yui - A Declarative UI library for LÖVE ======================================= -**Yui** - Yet another User Interface, is an attempt to ease the process of assembling trivial menu-like GUIs for your game using [LÖVE](https://love2d.org). +**Yui** - Yet another User Interface, is a library to create menu-like GUIs +for games using the [LÖVE](https://love2d.org) engine. ## Why is that? Because I'm spending so much time tweaking and customizing existing libraries, I might as well make my own. +## Features + +**Yui** fills the following gaps: + +* Immediate mode UIs tend to clutter LÖVE `update()` code a lot, using a declarative approach - that is: + describing how the UI should look upfront, and then letting the UI code `update()` and `draw()` itself accordingly, + makes for a cleaner code. +* Adapt to different sources of input easily (keyboard, mouse, touch, gamepad). +* Out of the box internationalization. +* Out of the box keyboard navigation across widgets. +* Simple layouts (place widget in columns or rows, or possibly build rows made of several columns - grids). +* Custom widgets support. +* Custom theme support. +* Custom input sources support. +* Sufficiently compact, straightforward and hackable code. + +**Yui** does have some downsides: + +* The declarative approach makes UIs harder to change drastically from frame to frame. + * **Yui** tries to ameliorate this, allowing widgets property tweening, it's still less powerful + compared to an all out immediate UI approach. +* Features come with a price, **Yui**'s code tries to be small and simple, but there are definitely smaller + (and less featureful) frameworks out there. + ## Dependencies **Yui** depends on: * [gear](https://git.doublefourteen.io/lua/gear) for general algorithms. * [moonspeak](https://git.doublefourteen.io/lua/moonspeak) for its localization functionality. +* ...and any of their dependencies. + +You may either download each of them manually and place them inside a `lib` subdirectory, or use +[crush](https://git.doublefourteen.io/lua/crush) to do the work for you. + +1. Clone this repository. + +```sh +git clone https://git.doublefourteen.io/lua/yui +``` + +2. Move to repository root directory: + +```sh +cd yui +``` + +3. Resolve dependencies using **crush**. + +```sh +lua crush.lua +``` + +You should now see a `lib` subdirectory containing the necessary dependencies. + +## Integrating yui in my project using crush + +1. Download the latest [crush.lua](https://git.doublefourteen.io/lua/crush/src/branch/master/crush.lua) file and + place it in your project's root directory. + +2. Create a `.lovedeps` text file in your project's root with the following dependency entry: + +```lua +{ + yui = "https://git.doublefourteen.io/lua/yui", + + -- ...more dependencies, if necessary... +} +``` + +3. **Yui** can now be downloaded directly by `crush` to the project's `lib` directory, + along with any other dependency: + +```sh +lua crush.lua +``` + +4. You may now use `yui` in your project by `require()`-ing it. + +```lua +local yui = require 'lib.yui' +``` + +5. Any project depending on yours may now fetch your project's dependencies (including `yui`) + automatically using `crush`, following the above procedure. + +## Documentation + +...Ouch. + +Documentation and examples are underway, however the source code is (IMHO) sufficiently +straightforward and disciplined to have sufficient overview of the functionality. ## Acknowledgement @@ -27,3 +114,11 @@ Widgets offered by **yui** are also inspired by **SUIT**. See [ACKNOWLEDGEMENT](README.ACKNOWLEDGEMENT) for full SUIT license information and copyright notice. + +## Similar projects + +* [SUIT](https://github.com/vrld/SUIT) an excellent, simple and flexible framework for immediate UIs. + +## License + +Zlib, see [LICENSE](LICENSE) for details.