Formspec replacement proposal

For people working on the C++ code.
TeTpaAka
Member
 
Posts: 140
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: 5471
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
 

TeTpaAka
Member
 
Posts: 140
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: 553
Joined: Thu Mar 24, 2016 03:19
GitHub: v-rob

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: 140
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: 553
Joined: Thu Mar 24, 2016 03:19
GitHub: v-rob

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: 976
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: 140
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: 553
Joined: Thu Mar 24, 2016 03:19
GitHub: v-rob

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: 5471
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
 

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

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: 5471
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
 

TeTpaAka
Member
 
Posts: 140
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: 129
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.
 

Sokomine
Member
 
Posts: 3616
Joined: Sun Sep 09, 2012 17:31
GitHub: Sokomine

Re: Formspec replacement proposal

by Sokomine » Sun Jun 24, 2018 21:26

TeTpaAka wrote: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.

In general, your approach looks very promising. However, the main issue I have with formspecs is with adding texts. A solution for that problem would be very welcome.
A list of my mods can be found here.
 

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

Re: Formspec replacement proposal

by TeTpaAka » Thu Jun 28, 2018 21:28

Sokomine wrote:
TeTpaAka wrote: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.

In general, your approach looks very promising. However, the main issue I have with formspecs is with adding texts. A solution for that problem would be very welcome.


Text is hard. The current approach is to let the modder define an area where text should be and try to fill as much of it as possible with the default font. This takes design elements out of the modders hand but should result in text that should be readable (at least, if it is readable now).

Other approaches would be to either let the modder define the fontsize relative to the screensize or define the whole UI in units based on the fontsize. The second approach would clash with my basic design and the first, while possible, probably wouldn't result in good readable text for the player.

Any suggestions on how to do it better are always welcome.
 

User avatar
GamingAssociation39
Member
 
Posts: 735
Joined: Mon Apr 25, 2016 16:09
Location: Maryland, USA
GitHub: Gerold55
IRC: Gerold55
In-game: Gerold55

Re: Formspec replacement proposal

by GamingAssociation39 » Fri Jul 13, 2018 22:29

Code: Select all
local window = formatter.create()
#html = formatter.create() --same effect as in actual html when called website will be created
#banner
   image=
   text=
   text_style = { "style_name" : "style_value" }
#header = get_label
   scale=
   align=
   text=
   text_style = { "style_name" : "style_value" }
#navigation =
   item-link=
   item-icon=
#paragraph = get_paragraph
   wraparound=
   text=
   text_style = { "style_name" : "style_value" }
#footer = get_foot
   title=
   sub-title=
   home-page=
   
   
=====================================================
   
Proposed functions for the new formspecs:

window:text(spec)
window:set_text_color
window:set_text_size


My proposal for some additional things and the API for my laptop mod's web browser MineBrowse.
Jesus Is Lord and Savior!!!
 

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

Re: Formspec replacement proposal

by rubenwardy » Fri Jul 13, 2018 22:34

Would it be possible to design this in such a way that you could reuse components between the HUD and GUI windows? Ideally they should be exactly the same, just different roots and layoutters
 

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

Re: Formspec replacement proposal

by TeTpaAka » Fri Jul 13, 2018 22:59

GamingAssociation39 wrote:
Code: Select all
local window = formatter.create()
#html = formatter.create() --same effect as in actual html when called website will be created
#banner
   image=
   text=
   text_style = { "style_name" : "style_value" }
#header = get_label
   scale=
   align=
   text=
   text_style = { "style_name" : "style_value" }
#navigation =
   item-link=
   item-icon=
#paragraph = get_paragraph
   wraparound=
   text=
   text_style = { "style_name" : "style_value" }
#footer = get_foot
   title=
   sub-title=
   home-page=
   
   
=====================================================
   
Proposed functions for the new formspecs:

window:text(spec)
window:set_text_color
window:set_text_size


My proposal for some additional things and the API for my laptop mod's web browser MineBrowse.


If I understand you correctly, you want the ability to have colored text, right?
That should be possible, since chat messages can be annotated with color information. I will look into it later.
The font size on the other hand could be slightly harder. I could add the ability to set the font size directly, but that would potentially make text unreadable on high resolution screens. This is not likely to come in the near future. I can think about it later, when the rest of the design works.

rubenwardy wrote:Would it be possible to design this in such a way that you could reuse components between the HUD and GUI windows? Ideally they should be exactly the same, just different roots and layoutters

Ideally, the HUD would not be hidden when the GUI gets shown. That way, you could add p.e. buttons or usable inventory slots to the HUD.
I thought about doing this after I finished the Formspecs (at least the basics). This would probably require a replacement of the current HUD, too.
 

User avatar
GamingAssociation39
Member
 
Posts: 735
Joined: Mon Apr 25, 2016 16:09
Location: Maryland, USA
GitHub: Gerold55
IRC: Gerold55
In-game: Gerold55

Re: Formspec replacement proposal

by GamingAssociation39 » Sat Jul 14, 2018 14:50

TeTpaAka wrote:
GamingAssociation39 wrote:
Code: Select all
local window = formatter.create()
#html = formatter.create() --same effect as in actual html when called website will be created
#banner
   image=
   text=
   text_style = { "style_name" : "style_value" }
#header = get_label
   scale=
   align=
   text=
   text_style = { "style_name" : "style_value" }
#navigation =
   item-link=
   item-icon=
#paragraph = get_paragraph
   wraparound=
   text=
   text_style = { "style_name" : "style_value" }
#footer = get_foot
   title=
   sub-title=
   home-page=
   
   
=====================================================
   
Proposed functions for the new formspecs:

window:text(spec)
window:set_text_color
window:set_text_size


My proposal for some additional things and the API for my laptop mod's web browser MineBrowse.


If I understand you correctly, you want the ability to have colored text, right?
That should be possible, since chat messages can be annotated with color information. I will look into it later.
The font size on the other hand could be slightly harder. I could add the ability to set the font size directly, but that would potentially make text unreadable on high resolution screens. This is not likely to come in the near future. I can think about it later, when the rest of the design works.


So that's somewhat what I was talking about because I want to implement a way to properly create a website for my mod in MT and can't do so effectively without images as the title and such.
Jesus Is Lord and Savior!!!
 


Return to Partly official engine development



Who is online

Users browsing this forum: No registered users and 0 guests