Formspec replacement proposal

For people working on the C++ code.
TeTpaAka
Member
 
Posts: 138
Joined: Sat Dec 28, 2013 21:54

Formspec replacement proposal

by TeTpaAka » Sun May 27, 2018 13:33

Hello community,

Since there are multiple issues with our current formspec system (see https://github.com/minetest/minetest/issues/6527), I propose a different layouting scheme for a new one. To test my proposals, I modified the current formspec renderer. This, however, comes with multiple limitations:
  • I completely removed any interactivity (for now). Buttons show interaction, but no response is send to the server.
  • This won't compile for Android since I left the Android code in place but removed code it depended on.
  • There will probably be some issues if you try to display an old and a new formspec at the same time.
  • The formspec strings can get pretty long, especially autogenerated float values take up far more space than necessary. A binary format would be preferable.

Concept:
  • We work in normalised coordinates. This means, positions are in the range [0,1] and are relative to a parent object.
  • Everything you see is a rect. Every rect can have multiple appearance changing modifiers (like background color/image...) and up to one behaviour changing modifiers (like button, inventory...)
  • Every rect can have multiple child rects. Coordinates of the child rect are relative to it's parent.

Lua API:
To facilitate creating forms I created a small mod (see below) which offers an object oriented interface to formspecs. To create the initial window, you would call:
Code: Select all
local window = formatter.create()

This creates a window with transparent background that spans the whole screen. Since most menus will only need a smaller area on the screen, you can change it's size and position relative to the screen:
Code: Select all
window:set_size(.5, .5)
window:set_pos(.25, .25)

The aspect ratio of this window is still dependend on the aspect ratio of the screen. This will most likely mess with your menu design. To compensate, the function:
Code: Select all
window:set_aspect(16,9)

will force a specific aspect ratio. To fit the aspect ratio, the renderer shortens one of the sides until the ratio is as specified.
To actually see anything, you have to either set a background color or an image to the window:
Code: Select all
window:set_background_color("#FFFFFF") -- currently only strings are accepted
window:set_image("modname_texturename.png")

If you set a background image, you probably want to align your interface to the background. To facilitate this, you can set the window into a pseudo absolute mode. Internally, the formspec is still specified by relative coordinates. The Lua API transforms pixel sizes to relative offsets.
Code: Select all
window:set_absolute_size(width, height)

Now we can add interface elements to the form:
Code: Select all
window:inventory(spec)
window:button(spec)
window:image(spec)
window:label(spec)

Spec is the specification of the new element it is a table with the following format:
Code: Select all
spec = {
    x = 0, -- position relative to the parent
    y = 0,
    width = 1, -- size relative to the parent
    height = 1,
    image = "modname_texturename.png", -- image spec (image only)
    text = "your text", -- text to display on the element (button and label only)
    name = "b1", -- id of the button (button only)
    location = "current_player", -- inventory location (inventory only)
    list = "main", -- inventory list (inventory only)
    columns = 8, -- number of inventory columns (inventory only)
    rows = 4 -- number of inventory rows (inventory only)
}

I will probably remove spec.name and replace it with a callback once I actually react to button presses.
To display the formspec you would have to call:
Code: Select all
minetest.show_formspec_new(name, "formname", window:generate())

I will probably create a function that autogenerates a unique formname and processes answers of the client and calls appropriate callbacks.

Formspec format
  • general Element (Image/Label ...)
    Code: Select all
    {
        rect = { "x0" : 0, "y0" : 0, "x1" : 1, "y1" : 1 },
        bgcolor = "#FFFFFF",
        image = "modname_texture.png",
        aspect = {"x" : 16, "y" : 9 },
        text = "some text",
        children = [{ ... }, ... ],
        style = { "style_name" : "style_value" }
    }

    Create a new rectangle spanning from (x0, y0) to (x1, y1) in relation to it's parent.

    Styles:
    • text_align, specifies the alignment of the text can be one of: center, top, topright, right, bottomright, bottom, bottomleft, left, topleft
    Currently, text is drawn with a fixed color (white). I will make the text color available as style if I continue working on this.
    The text is automaticly word wrapped. Enabling this will become an option later on.
    Also, text clashes with the basic design principles of this new formspec. It doesn't scale with the rest of the gui and may get outside of the rect. Suggestions on how to fix this are welcome.
  • Inventory
    Code: Select all
    {
        ... see above
        "type" = "inventory",
        "columns" = 1,
        "rows" = 1,
        "location" = "current_player",
        "list" = "main"
    }

    converts the parent rect into an inventory.
    The inventory completely fills the rect and touches the border at all four sides. Inventory slots are square and have a padding of at least 2/13 inventory slots in x-direction and 1/4 inventory slot in y-direction.
    The old formspec drew a one pixel border on the outside of every slot. Since this clashes with my design, the border is now drawn on the inside and the image is scaled down appropriately.
    Styles:
    • inventory_background_color, specifies the color of the slot background
    • inventory_border_color, specifies the color of the slot border
    • inventory_border_width, specifies the width of the slot border
  • Button
    Code: Select all
    {
        ... see above
        "type" : "button",
        "id" : "unique identifier"
    }

    converts the parent rect into a button.
    The button background is draw according to it's style. Background images and colors are ignored for now (this will probably change).
    The id will be set in the answer when the button ist pressed (not implemented yet).
    Styles:
    • button_standard, set it to a texture to change the default appearance of the button
    • button_hover, set it to a texture to change the appearance of the button when the cursor is inside it's rect
    • button_pressed, set it to a texture to change the appearance of the button when it get's pressed
[/list]
Links:
Lua API: https://github.com/TeTpaAka/formatter
Core modifications: https://github.com/TeTpaAka/minetest/tree/formspec

By issueing the chatcommand "/testform" you can see an example gui I created.
Image
The example gui uses images from https://opengameart.org/content/ui-pack-rpg-extension.

TODO:
  • Add
    Code: Select all
    input[name]
    element for text input.
  • port the field sending methods from the old formspec
  • split the gui elements into their own file
  • split the parsing into it's own file
  • add error and sanity checks to core and Lua API
  • Add more elements like checkboxes, dropdowns, radiobuttons, ...
  • Add scrollable rects
Last edited by TeTpaAka on Sun Jun 03, 2018 17:36, edited 2 times in total.
 

User avatar
rubenwardy
Moderator
 
Posts: 5317
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Formspec replacement proposal

by rubenwardy » Mon May 28, 2018 13:56

I'd rather JSON was used as the serialisation format as it will handle children much better
Core Developer | Donate | My Twitter | Mods | Mods 4 Android | Node Box Editor | Minetest Modding Book

Hello profile reader

LgiOxMFYXOqtqVqMPhbw1Bn3oNRvEC7j
 

TeTpaAka
Member
 
Posts: 138
Joined: Sat Dec 28, 2013 21:54

Re: Formspec replacement proposal

by TeTpaAka » Mon May 28, 2018 15:48

rubenwardy wrote:I'd rather JSON was used as the serialisation format as it will handle children much better

I'm not fixed on the serialisation format. I just used the existing one because it was easier to start with a working format and modifying it to my needs than to incorporate a new one. I can switch to JSON though later on. Switching the underlying format should be rather easy.
 

User avatar
v-rob
Member
 
Posts: 500
Joined: Thu Mar 24, 2016 03:19

Re: Formspec replacement proposal

by v-rob » Mon May 28, 2018 23:24

First off, I'd like to say that it's awesome that someone has actually tried to do something about this issue with formspecs. To my knowledge, nothing like this has happened before. I have some questions about this, though.

    1) I'm not quite sure how the positioning of the formspec windows works. From what I gather, setting the position to 0.5, 0.5 will center the window on the screen, correct? And setting the size to 0.5, 0.5 would make it half the size of the screen?

    2) Shouldn't there be a default aspect ratio? It would make all formspecs that don't define one work properly in all resolutions.

    3) In the inventory element in test.lua, it shows width, height, rows, and columns. But why is width and height necessary when rows and columns are already defined? Wouldn't that make inventory slots bigger or smaller?

    4) Is it possible to show images on inventory slots?

    5) Are you planning on making images for when you hover over buttons and such?

    6) Will there be default images for everything in minetest\textures\base\pack? I think this would make formspecs better because people wouldn't define their own images for everything and texture packs could change things easier.

    7) How is interaction planned? Will interaction be in a different function like the current formspecs, or will the function be part of the element specification?

    8) Can a child element have another child element?
I'm really glad that someone's trying to do something about formspecs, and I'm sorry for all the questions.
 

TeTpaAka
Member
 
Posts: 138
Joined: Sat Dec 28, 2013 21:54

Re: Formspec replacement proposal

by TeTpaAka » Tue May 29, 2018 11:00

v-rob wrote:First off, I'd like to say that it's awesome that someone has actually tried to do something about this issue with formspecs. To my knowledge, nothing like this has happened before. I have some questions about this, though.
    1) I'm not quite sure how the positioning of the formspec windows works. From what I gather, setting the position to 0.5, 0.5 will center the window on the screen, correct? And setting the size to 0.5, 0.5 would make it half the size of the screen?

Positions are relative to the top left corner of the screen. So, for a window with size(0.5, 0.5) setting the position to (0.25, 0.25) would center it. I probably should add a convenience function to the API that does these calculations, like
Code: Select all
window:center()
or something like that.
v-rob wrote:
2) Shouldn't there be a default aspect ratio? It would make all formspecs that don't define one work properly in all resolutions.


That does seem like a good idea. I will think about it. Probably (1, 1) would be suitable.
v-rob wrote:3) In the inventory element in test.lua, it shows width, height, rows, and columns. But why is width and height necessary when rows and columns are already defined? Wouldn't that make inventory slots bigger or smaller?


First part: I changed the layouting scheme from the previous formspec definitions. Now, it no longer treats inventory slots as (sort of, it wasn't even consistent with that) basis. This way, the inventory is always scaled to the full size of the rect. So:
Second part: Yes, it does make the inventory slots bigger/smaller.
It also adds appropriate padding around them to keep them square. I will probably add a style option to make them stretch fo fit instead of padding them, if the modder wants.
v-rob wrote:4) Is it possible to show images on inventory slots?


You can overlay an Image over the inventory, if this is what you mean. Form elements are drawn in order they are defined in the formspec string.
v-rob wrote:5) Are you planning on making images for when you hover over buttons and such?


You can already define images for hovering over buttons and for clicking them. If you suggest more, I can add more different style options.
v-rob wrote:6) Will there be default images for everything in minetest\textures\base\pack? I think this would make formspecs better because people wouldn't define their own images for everything and texture packs could change things easier.


I currently don't have plans for that, sorry. Maybe later.
v-rob wrote:7) How is interaction planned? Will interaction be in a different function like the current formspecs, or will the function be part of the element specification?


Internally I will probably use something similar to the way formspecs report events to mods right now. But I will provide callbacks to the user, that get called when an event occured. e.g:
local button = window:button({
x = ...,
y = ...,
width = ...,
height = ...,
text = "...",
callback = function(playername)
end
})

v-rob wrote:8) Can a child element have another child element?

Yes. But there are some issues in the Lua API currently with buttons and formspecs I will resolve later. For images it works without a problem.
v-rob wrote:I'm really glad that someone's trying to do something about formspecs, and I'm sorry for all the questions.

Don't hesitate to ask. This is in a very early state of development and suggestions are always welcome. I might not incorporate all of them, but I will explain why I don't.
 

User avatar
v-rob
Member
 
Posts: 500
Joined: Thu Mar 24, 2016 03:19

Re: Formspec replacement proposal

by v-rob » Tue May 29, 2018 23:44

Wow. From what I can see, this is exactly the kind of formspecs I've been wanting. Keep up the good work!
 

User avatar
texmex
Member
 
Posts: 800
Joined: Mon Jul 11, 2016 21:08
GitHub: tacotexmex
In-game: texmex

Re: Formspec replacement proposal

by texmex » Wed May 30, 2018 18:46

I just want to add my support to this project as it seems to have the potential to overcome major formspec issues. Kudos to tetpaaka for taking on this project when no-one else seems to be willing. :)
 

TeTpaAka
Member
 
Posts: 138
Joined: Sat Dec 28, 2013 21:54

Re: Formspec replacement proposal

by TeTpaAka » Sun Jun 03, 2018 17:37

I switched the formspec format to a JSON based format.
 

User avatar
v-rob
Member
 
Posts: 500
Joined: Thu Mar 24, 2016 03:19

Re: Formspec replacement proposal

by v-rob » Mon Jun 04, 2018 23:50

So, why haven't any developers commented on this? The only one who has said anything is rubenwardy. That's one way to make someone discouraged really fast. Seriously, it's a very important issue, and yet no one seems to care very much except for myself and a few others.
 

User avatar
rubenwardy
Moderator
 
Posts: 5317
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Formspec replacement proposal

by rubenwardy » Mon Jun 04, 2018 23:56

Contradiction there - "no devs have commented" "rubenwardy has" :P
Core Developer | Donate | My Twitter | Mods | Mods 4 Android | Node Box Editor | Minetest Modding Book

Hello profile reader

LgiOxMFYXOqtqVqMPhbw1Bn3oNRvEC7j
 

User avatar
v-rob
Member
 
Posts: 500
Joined: Thu Mar 24, 2016 03:19

Re: Formspec replacement proposal

by v-rob » Tue Jun 05, 2018 00:04

rubenwardy wrote:Contradiction there - "no devs have commented" "rubenwardy has" :P


Besides you. But my question remains unanswered.
 

User avatar
rubenwardy
Moderator
 
Posts: 5317
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Formspec replacement proposal

by rubenwardy » Tue Jun 05, 2018 00:07

Devs have real lives and may not check the forums. They also may not have looked into it enough to respond
Core Developer | Donate | My Twitter | Mods | Mods 4 Android | Node Box Editor | Minetest Modding Book

Hello profile reader

LgiOxMFYXOqtqVqMPhbw1Bn3oNRvEC7j
 

TeTpaAka
Member
 
Posts: 138
Joined: Sat Dec 28, 2013 21:54

Re: Formspec replacement proposal

by TeTpaAka » Tue Jun 05, 2018 07:41

I knew that posting it on the forum wouldn't attrackt dev attention. If I wanted to propose it to the development team, I would have opened a pull request on github. But this feature is not yet in a state I'm comfortable with presenting to the dev team. I will draw attention to it once I consider it ready for further discussions.
 

User avatar
csirolli
Member
 
Posts: 107
Joined: Mon Jan 15, 2018 21:46
Location: Florida, USA
GitHub: ChristianSirolli
IRC: CSirolli
In-game: CSirolli

Re: Formspec replacement proposal

by csirolli » Tue Jun 05, 2018 16:25

This is pretty cool. I wish there was some way I could help.
Jesus is the only Way to heaven, the only saving Truth, and the only Life that is worth living.
 


Return to Partly official engine development



Who is online

Users browsing this forum: No registered users and 1 guest