shdwcat / yui

YUI - A UI system for GMS2

YUI 0.6.3

A UI system for GameMaker by @shdwcat

Why YUI?

Writing UI code is annoying and tedious! Why write UI code when you can edit readable text files instead?

Notable features

• Live Reload while the game is running!
• Flexible and powerful Data Binding and Embedded Scripting system to get your game data into the UI
• Template system lets you design and re-use custom widgets
• UI Animation system - slide/fade/etc! Also supports color curves, animation sequences, and custom effects
• Theme system and widget styles
• Powerful Drag and Drop feature built in (no coding!)
• VS Code syntax highlighting extension: https://marketplace.visualstudio.com/items?itemName=shdwcat.yui-vs-code-support

Platform Support

YUI is confirmed to work on Windows, Mac, and Linux. YUI does not yet work on HTML5 as included file handling needs to be fixed (#72). As far as I know, YUI has not been tested on mobile or consoles, if you want to try it out, please do and let me know if it works! (see Discord link below).

Library Support

YUI has built-in optional support for the popular Scribble and Input libraries. These are NOT included with YUI by default but can be added for more features.

• Scribble 8.7.0 - Advanced Text Rendering

  YUI is designed to be compatible with Scribble 8.7.0 and future 8.x.x versions, and may be compatible with previous 8.x.x versions.

  When Scribble is included in your project, you can set scribble: true on a text element to access standard Scribble text formatting features.

  See the Scribble documentation for how to set up Scribble and what formatting features are available

• Input 6.1.5 - Mouse/Keyboard/Gamepad/Touch Support

  YUI is designed to be compatible with Input 6.1.5 and future 6.x.x versions, and may be compatible with previous 8.x.x versions.

  When Input is included in your project and YUI is configured to use it for navigation, the gamepad will be able to navigate the UI similar to the standard keyboard navigation support. (Touchpad support is untested currently!)

  Please see https://github.com/shdwcat/YUI/wiki/Input for how to configure YUI to use Input!

OK, where do I start?

You can either clone the Example Project (this repo) to play around with it, or import the latest package from the Releases page.

Please note that the Wiki is quite out of date (but may still be useful).

The Example Project

Contained in this repo is the YUI Example project. If you clone the repo locally you can run the project to get an idea of what YUI is capable of. The Example Project is still a work in progress, but make sure to check out the Inventory Screen for an example of how to quickly set up drag and drop!

Help!

If you need help with anything, please stop by the GameMaker Kitchen discord: https://discord.gg/8krYCqr

Dependencies

YUI has a number of dependencies, which are automatically included in the project.

• Inspectron - runtime instance debug overlays

Credit to @jujuadams:

• Gumshoe - file finder

And @offalynne:

• input-string - text input backend

Credits

Some icons made by Pixel perfect from www.flaticon.com

(Specifically the 'yui_error' icon)

yui's Issues

Support for element styles (similar to CSS classes)

The idea for Styles is to be able to declare a set of properties, similar to a fragment, that can then be merged into the values for an element by setting the styles property.

// in theme file:
styles:
  cancel:
    background: red
    content: Cancel
    size: { w: 60, h: 30 }
    
// in screen/widget etc:
type: button
styles: cancel // could also specify multiple styles as an array

In this example a cancel style is declared, and then a button is declared as using the cancel style. The properties from the style would then be applied to the button (in listed order of styles), with priority just below instance properties, but above widget/theme properties.

This way we can re-use a 'cancel button' set of properties without needing to make a cancel_button widget, and being able to support additional styles in parallel, rather than the tree of intersecting styles that would be required to achieve the same goal with the widget system.

Fix element cleanup logic to avoid event recursion limit

calling instance destroy in the cleanup event can hit a recursion limit if the tree is deeper than 30 (see the old fibonacci example).

Fixing this involves moving the logic to an instance function, and possibly needing to flatten the list and then clean up all items in one loop

Implement listbox widget

Should match the listbox type control as seen in WPF or HTML5's select

Script Access from YUI files should require whitelisting the available functions

Right now, YUI can execute any script, or any method on an object in the data context. In a released game this is obviously a huge security problem, so script access should require whitelisting, such that only the scripts allowed by the developer can be run.

Slider bar isn't clamped

Hello shwdcat, I was testing your slider and I lost the slider cursor, and now I can't find it anymore 😢
Please retrieve my slide cursor.

Sincerely, Zice

Runner_RvzaB7oM92.mp4

Add baked in support for UI sound effects

Currently you can trigger sound effects via click handlers, but there isn't a good way to access sound assets by name. It would also be nice if the support was baked in so that it would be easier to document and use.

xoffset and yoffset should work for all elements, not just border and panel

(as title says)

Pipe slot definitions through the render tree at construction to improve perf

Currently YuiTemplateRenderer sets up slot definitions in the update() call, and YuiRenderContext.resolveBinding has to evaluate them each frame. The slot definitions are static though, so they can be piped through when the render tree is constructed, removing the need for YuiTemplateRenderer and thus getting a performance gain whenever one is used.

Doing so will also obviate the need for fragments, as templates with no slots will no longer have a performance cost.

[Scribble] You cannot use "text formating" in a text.

Example:

root:
  type: panel
  layout: canvas
  elements:
        - type: text
            text: [scale, 1]Hola Mundo![/s]

Error show:

############################################################################################
ERROR in
action number 1
of Key Press Event for F5 Key
for object yui_document:

Variable Index [1] out of range [1]
 at gml_Script_anon___snap_from_yui_builder_gml_GlobalScript_snap_from_yui_14310___snap_from_yui_builder_gml_GlobalScript_snap_from_yui (line 355) -                     var _key = snap_from_yui_get_token_value;
############################################################################################
gml_Script_anon___snap_from_yui_builder_gml_GlobalScript_snap_from_yui_14310___snap_from_yui_builder_gml_GlobalScript_snap_from_yui (line 355)
gml_Script_anon___snap_from_yui_builder_gml_GlobalScript_snap_from_yui_14310___snap_from_yui_builder_gml_GlobalScript_snap_from_yui (line 439) -                     _array[@ array_length(_array)] = read();
gml_Script_anon___snap_from_yui_builder_gml_GlobalScript_snap_from_yui_14310___snap_from_yui_builder_gml_GlobalScript_snap_from_yui (line 372) -                         variable_struct_set(_struct, _key, read());
gml_Script_anon___snap_from_yui_builder_gml_GlobalScript_snap_from_yui_14310___snap_from_yui_builder_gml_GlobalScript_snap_from_yui (line 372) -                         variable_struct_set(_struct, _key, read());
gml_Script___snap_from_yui_builder (line 517) -     result = read();
gml_Script_snap_from_yui (line 41)
gml_Script_anon_YuiDocument_gml_GlobalScript_YuiDocument_489_YuiDocument_gml_GlobalScript_YuiDocument (line 37) -               var file_data = snap_from_yui(file_text);
gml_Script_YuiDocument (line 19) -        loadDocument();
gml_Script_anon_gml_Object_yui_document_Create_0_529_gml_Object_yui_document_Create_0 (line 32)
gml_Script_anon_gml_Object_yui_document_Create_0_816_gml_Object_yui_document_Create_0 (line 46) -        load();
gml_Object_yui_document_KeyPress_116 (line 3) - reload();

Implement system for easily adding YUI elements that draw for GM game objects

Currently in order to render YUI stuff at the position of a GM object in world space, you have to do advanced things like binding xoffset and yoffset to the x and y of the object, and using yui_world_to_gui_x/y to translate the coordinates. It would be much more ideal if there was a way to describe which game objects should draw YUI elements, as well as how to position the YUI content relative to the object (since often we'll want to align to the object bounding box in some way, similar to popup placement)

failed to run the example YUI

After downloading the zip file and setting the YUIExampleRoom1 to the default room and run it, there was an error:

ERROR in
action number 1
of Create Event
for object yui_document:

Unable to find a handler for exception Unable to find theme with name: default

at gml_Script_yui_resolve_theme(line 7)- throw
yui+error("Unable to find theme with name: " + theme_name);

Add support for gamepad navigation

Make animation section for Example Project

Implement layer draw order management

Currently YUI uses depth to control draw order and make sure the right elements draw on top of each other. But this makes it hard to implement features like shader and animation support, since it's extremely difficult to determine when a 'layer' is done drawing. Instead we should use a single GML layer to control draw order for things in the same 'YUI layer' (the base of a screen is one layer, windows and popups get their own layer, and users should be able to mark any element as the start of a new layer as well). Once draw order is managed via layers, we can use layer features for shaders and motion/animation/etc.

A few issues I've run into.

Can i fix this somehow?
If I try to close this window "buttons", the program crashes, no reaction to other windows if i click to close it.

Here's another one, if I scroll the slider past the center, I can't interact with it anymore until I scroll to the top of the page myself.

If you go into the inventory, put on any thing on hero, click on the back, enter the inventory again, then there is a very high chance that there is nothing more to work. But if I go back again and sing the therme, everything will be fixed.

Support setting sound effects for actions like click/hover/scrolling/etc

YUI needs support for configuring and playing sounds for common UI actions

Make a quick start guide for setting up a simple HUD screen

A HUD is a pretty basic thing that is a very common desire to make UI for, so it's a good candidate for a simple getting started guide

import should support importing all files from a folder

For example, currently you need to import each widget you want to use from the Widgets folder by name, but it would be nicer if you could just do:

import:
  - /YUI/Widgets

Streamline getting started -- make it so you can drop one object into a room to get started

Adding YUI to an existing game is currently a bit complicated (and not actually documented on this wiki). Ideally there should be something like a 'my_first_yui_screen' game object that you can drop into a room and have it render UI for you right away.

Additionally, figure out if there's some way to bootstrap the persistent global object like YuiCursorManager instead of requiring manual setup of those.

Current instructions for getting started for reference:

The steps for setting it up in your own game are (roughly):

1. Add the necessary persistent objects to your loading room

• YuiGlobals, YuiCursorManager (I think it's just those two, you could check the example project)

2. configure live reload (there's a folder labeled 'configure me!' with a gml file with instructions. (you should do this for the example project as well)
3. Create a .yui screen file (see the example screen folder for what this should look like) and put it in the YUI subfolder in /datafiles/
4. Put a yui_document game object into a room somewhere. Probably easiest to start with your loading room.
5. In the variables section, Set the yui_file variable to the path to the screen file relative to /datafiles/ (including the YUI subfolder).
6. Then you the need to either resize that object to the size of the UI you want, or check the draw_fullscreen box
7. Set the data_context variable of that yui_document to some instance (or instance variable pointing to a struct). This is essentially how you get game data into the UI. All the UI data binding stuff will be referring to data on that object, or available from it via variables.

Theoretically, at that point you run the game and the UI shows up. If you change any variable values on that data_context object, the UI will immediately update without you needing to do anything
Live reloading is explained on the wiki, but assuming it's set up correctly, you can just press F5 and it will reload the UI from disk. Right now it will crash if you fucked up somewhere, but I've got some stuff in Dev that in some cases will make it so that you can fix the problem and reload again

Unify centering/alignment behavior with `alignment` shared property

Currently:

• panel uses alignment
• image uses center
• text uses centered

They should all use alignment and support the same values

investigate making resources import per file instead of flattening into one list

Currently all imports get flattened into one master resources table per document. This means all resource names must be unique or there might be conflicts, and that resources used just for a specific file (such as a widget) pollute this global namespace.

Ideally resources should work more like WPF, where resources are scoped to the file that uses them.

YuiScript: Support for writing decimal values without leading 0 e.g. `.123`

Currently you can only write decimal numbers if they begin with a number:
12.3
0.5
It should also support:
.123

Add an in-game inspector system so that you can see YUI element properties while the game is running without breaking in the debugger

Add support for baking .yui files into the gml code to support non-desktop platforms

HTML5 etc can't use file_find_etc -- possible solution is to have the system load all the .yui files into their raw structs and then write out GML files with all the data in them in gml struct syntax. Then we need a way for Cabinet to be able to intercept 'file' requests and return the baked in data instead.

Update to latest Scribble LTS

Implement a system for easy to use UI animation

Currently animation can be done manually via @binding logic, but is tedious and likely prone to bugs. YUI should support simple easy to use animation logic, possibly using animation curves, sequences, etc.

Circular layout (like a item wheel)

Hello shwdcat, I'd like to make a weapon wheel for my game like in Zelda: Twilight Princess or GTA V. For this, a new circular component for layout would be handy!

Sincerely, Zice

Instance creation order is not maintained when using F5 to reload

mouse cursor layer handling depends on the order of instance creation when creating UI normally -- F5 reload seems to recreate the UI items sometimes not in the correct order, causing weird cursor layer issues. Fixing this probably means centrally registering creation order when initially created, and then handling F5 in one place and reloading each screen according to the order

Example project needs data_template example

Nothing in the example project uses data_template which makes it easy to accidentally introduce bugs that aren't caught until the new code is used in a game project

Add a scribble autotype/typist example to Example Project

Improve perf when binding canvas layout position

Hello, sliders cause a big performance drop. I think you should see how improve binding canvas layout position to take less perf

Sincerely, Zice

Black screen on HTML5 Method

Was curious if this was supported platform or not :)

It appears to have the error "undefined" for Inventory & welcome_screen rooms.

Best!,
DirtySock

Docs need a quick start page and a longer getting started guide

There's no info about how to get started actually adding YUI to a game. This needs to be documented so that people can actually use this thing...

Unable to find theme with name: default

Fix the line endings problem when downloading code from github

I've been informed of how to fix the problem, so we should finally be able to stop the bug reports about this :P

Rename current panel/layout 'stretch' behavior to CSS 'fit-content' and make 'stretch' match the equivalent WPF behavior

Currently alignment: stretch works more like https://developer.mozilla.org/en-US/docs/Web/CSS/fit-content. If a vertical list of items has horizontal alignment as 'stretch', each item will be sized to the maximum width of the items in the list. In WPF however, stretch means to fill the entire available width or height (and YUI 'stretch' was intended to match this behavior). The current behavior is very useful though, so it should be preserved under the name 'fit-content'.

make a proper YuiTemplateDefinition constructor for YUI templates

Currently templates largely exist as raw struct resources that get applied to a template element as it gets instantiated in yui_create_template_element. Some of the raw data gets modified on the first call per template, and stored in the template_def property one the resulting element, so that it can be re-used if that element is recreated. However this code is very messy and hard to debug when things go wrong.

Instead when a template is loaded from a resource, we should create a YuiTemplateDefinition that performs all the template initialization logic once, with a function to create the an element from the template definition, similar to the DCS model in my game project.

This would also allow templates to use another template as the root element, as currently the system assumes that the root element must be a core YUI element, and it's too difficult to modify the existing code to support this.

Example project needs example for game/UI interaction and click handling

Like #48 this is another system that YUI supports but nothing in the example project uses it, which makes it easy to accidentally create bugs in

Fix Tab's file system sandbox detecton to not write to My Documents

See https://gist.github.com/tabularelf/7556fb1cd47a5e39e78375088f8b24da

remove SNAP dependency

There should be a way to set the default theme to point at a different file

Currently the only way to change the default theme is to either edit the default theme file itself, or point each screen at a different theme. The former causes problems when updating to new versions, and the latter is tedious.

There should be some way to configure the default theme to point to a custom file instead of the YUI default theme.

border/panel's background and border_color should support dynamic binding

Example use case is the buttons for tabs in tab_panel -- it should be possible to make the background color change depending on which tab is selected. Currently these can be set statically using $slot values, but not changed via bindings

Visual logs in-game

Hello shwdcat, sometimes I make a mistake and a log appears in the console tab to tell me about it. However, I have a lot of logs, so I miss it and look for the mistake I think a visual log in game would help debugging like this picture.

Sincerely, Zice

Opening a popup should close other popups

Specifically, popups that aren't part of the ancestors of the new popup

Binding bug -- can't use plain `@` right before `then`

This will work correctly:
@ == $selected_item then $selected_bg_color else $item_bg_color
This will not:
$selected_item == @ then $selected_bg_color else $item_bg_color

In the latter case the scanner seems to be pulling the then into the binding path, resulting in it trying to evaluate a data binding with path then, which obviously doesn't work

Drag and drop hit detection should use rect from cursor to visual top-left instead of just cursor

Using only the cursor can be misleading when using drag and drop, default behavior should probably be to use the rect from the visual top left to the cursor position within the visual, and possibly allow options for using the full visual bbox as well as only the cursor x/y.

Fix yui_change_screen() to match 'document' naming pattern

screens were renamed to documents in a prior version, but yui_change_screen() did not get updated to match, and should be updated to reduce user confusion

Move element init logic into init() function to enable dynamic states

being able to redo the init logic would allow for things like 'states' where a button could be in a 'pressed' state and apply certain property values only in that state (by including the state props in the prop layer list for yui_apply_props)

Better keyboard focus navigation

The existing KB navigation is kind of okay, but can break down in more complex UIs (see TodoMVC example). Need to finish the focus scope logic, and also make the automatic behavior able to understand navigating back/forward in panels.

Layout example should actually show all the layouts