[UI] [Addon SDK] : missing Editor/Runtime Hierarchy methods to create full UI Systems

[OverboyDev]

Reviewed guidelines

• [X] I have read and understand the suggestion guidelines

Checked for duplicate suggestions

• [X] I checked for existing similar suggestions

Summary

Add new Editor/Runtime scenegraph methods to the Addon SDK to let 3rd party devs create full UI solutions for the community

The main idea with those new Editor API would be that Behaviors of an instance would be able to access and set the position/angle/scale of their parent and children. (but also any other info available via the editor API)

Also Behaviors would be able to listen for some Events that happen on their own object instance or parent/child instances such as OnChildAdded/OnChildRemoved/OnDestroyed/OnAngleChange

Possible workarounds or alternatives

No way to create UI systems working in editor to have a preview of the final result (while it's what gamedev expect from a UI system) No UI system provided in C3 besides HTML/CSS method that most C3 users don't want to deal with Very very hard to create UI systems that supports all Plugins (Sprite/9Patch/TiledBG/Text) with Eventsheets as Multi-plugin family support doesn't exist (and even if it would work, it would be runtime-only).

By implementing the methods listed below, 3rd party devs like me or skymen would be able to develop UI systems for the whole C3 community (as Scirra said they don't have time to develop UI features in Construct editor)

---

Proposed solution

Here are the most important things that should be added :

Note : The point is that a behavior instance of an object should be able to easily listen for all listed "events" (basically all methods starting with "On" such as OnChildAdded()/OnTransformChanged()) of its own Object instance or the parent/childrent Object instances

RUNTIME API :

WorldInfo Class :

• OnChildAdded(childWorldInfo)
• OnChildRemoved(childWorldInfo) : also triggered when Child is Destroyed
• OverrideHierarchyParams(params) : explained below in the Editor API part
• OnTransformChanged() : when the position/size/angle of the instance changes
• OnPositionChanged()
• OnSizeChanged() : useful in case an horizontal/vertical/grid autolayouting parent changes is size, children must be repositionned accordingly
• OnAngleChanged() : what if an autolayouting hierarchy is rotated

EDITOR API : Would be very important so everything works directly in Editor even if the system is based on Behaviors : Autolayouting updates when Children are added/Properties are changed, the whole UI Hierarchy would move when parent is moved etc...

IWorldInstanceBase or IWorldInstance :

• OnChildAdded(childIWorldInstance)
• OnChildRemoved(childIWorldInstance) : also triggered when Child is Destroyed
• Destroy() : destroys the instance
• OnDestroyed()
• GetChildren()
• GetAllChildren()
• GetParent()
• AddChild(args)
• RemoveFromParent()
• OverrideHierarchyParams(params) : Very important : add the ability to set (override) Hierarchy params, useful as autolayouting mostly needs children to have TransformX, TransformY and TransformAngle set to true but would not work as expected if children had TransformWidth/TransformHeight set to true. Allowing Behavior to override those params automatically would avoid the C3 users to change all parameters for every single UI Hierarchy object they have everytime (+ it's very hard to realize the issue is coming from wrong Hierarchy parameters even as the creator of the UI Solution, so it would be just impossible to grasp for end users)
• MoveParentInstead(boolean) = true/false : if this instance is selected it instead move the first parent with MoveParentInstead set to false (which is the default) OR the top parent of the Hierarchy (can be itself).
  1. So if the parent of the instance is also set to MoveParentInstead = true, but the grandparent of the instance is set to MoveParentInstead = false, it will act as if it the grandparent was the selected moving instance
  2. If the selected instance has no parent AND MoveParentInstead = true, then it would just work as usual (as if it was set to false), you can just move the instance freely in the editor.
  3. If an instance has MoveParentInstead=true and all its parents have MoveParentInstead=true, then it just works as if the top parent was set to false
  4. All of this means there is no way to completely lock an instance in editor via this boolean, it will always move either the instance object itself or one of its parent, no matter the configuration
  5. This MoveParentInsted(bool) is useful to use on children of some UI Hierarchies, only parents can be moved and children are automatically moved accordingly) : we don't want the user to be able to move grid item children of a grid layouting parent individually.

[OLD] LockUserMovement(boolean) = true/false : prevents the user to move this instance, useful to make sure the user only move the parent instance responsible for the autolayouting features of some UI Hierarchies (example : we don't want user to be able to to move grid elements individually as their grid layouting parent should just automatically set their position). Edit : I realized MoveParentInstead(boolean) would probably be better to solve this problem

• OnTransformChanged() : when the position/size/angle of the instance changes
• OnPositionChanged()
• OnSizeChanged() : useful in case an horizontal/vertical/grid autolayouting parent changes is size, children must be repositionned accordingly
• OnAngleChanged() : what if an autolayouting hierarchy is rotated

EVENT LISTENERS for both the new Runtime and Editor API

Important : there should be one way or an other for a Behavior of that world instance to listen for those OnChildAdded/OnChildRemoved/OnDestroyed/OnTransformChanged events => we should be able to add EventListeners for those

Maybe all those events should be fired from the runtime (at runtime) or from the project (at edit-time), as it's working with "oninstancecreated" ? Not sure what would be the most consistent and useable way of doing it, as long as it's easy for behavior to listen for this it's fine.

---

Why is this idea important?

Better UI has been one of the most requested thing in C3 since forever, most user don't want to deal with CSS/HTML and all their quircks every time they need a UI element in their game, UI is one of the main thing a game engine should allow us to do

Most of the UI system made in Game-engines are hierarchy-based and work that way : parent UI objects have properties that acts on their UI children and everything happens live directly in the editor, this is the industry-standard.

Ressources about AutoLayouting in other Game Engines : Godot Containers : https://docs.godotengine.org/en/stable/tutorials/ui/gui_containers.html Unity Autolayouting : https://docs.unity3d.com/Packages/com.unity.ugui@1.0/manual/comp-UIAutoLayout.html I especially recommend reading the Godot Container documentation as it's considered as the best UI system made in a popular Game engine and the documentation is very clear and concise.

Additional remarks

Without even speaking about UI, every single addition listed above would be useful for countless usecases

[AshleyScirra]

I would prefer to focus on HTML/CSS for UIs. The new HTML layers feature in the latest betas should make it a lot more viable to use for that. Otherwise we could end up spending months or years reinventing the wheel and coming up with new ways to do things that are already possible with HTML/CSS. So why not use that? What is actually insufficient about it? If there are issues can they be solved another way?

Further a major complication with this proposal is how it interacts with undo. This alone is extremely complicated. For example your proposal includes a method to destroy an instance. How does that work with undo? If the answer is "don't create undo points", this can crash the editor, as the user can now do things like:

1. Change the position of an instance (with undo point).
2. Destroy an instance via SDK method (without undo point).
3. User presses undo; step 1 is undone rather than step 2. This alters the position of a destroyed instance, which is not normally possible, and would probably crash the editor.

This does not just affect 'Destroy': there are many kinds of alterations that if not included in the undo system essentially cause the editor state to be corrupted when pressing undo, causing crashes.

To solve this the proposal would likely need to include a full SDK-side undo system, including transactions for multiple actions in one undo point. That would then need to be correctly used by addons, as if it got anything wrong, the editor crashes. When the editor crashes, people usually blame us and we end up having to spend time on support for that as well, so either we need to figure out a way to make sure it's impossible for addons to crash the editor in the undo system (complicated and unclear if it's feasible), or it could end up have long-running maintenance and reputational implications for us.

If you are determined not to use HTML/CSS and implement a third-party system, perhaps a more feasible approach would be to use some external tool for the UI editing and manipulation operations, and just import the results to Construct. There's an existing custom importer API in the SDK, originally designed for Spriter, but it might be a better direction to go in. IIRC the custom importer API only has the capability to create new things, and not change or destroy them, so it avoids the undo problem.

[OverboyDev]

The whole point of this suggestion is that you let anyone create their own Hierarchy-based system as you prefer to push HTML/CSS, this way no need for Scirra to create a Hierarchy-based UI system themself.

Every single method listed in this suggestion would open up a lot of possibilities for Addondev.

I think Destroy() should keep undo support to not overcomplicate stuff for nothing I still removed Destroy() from the suggestion, even if keeping the undo point would be perfectly fine Now that the Destroy() is removed, there isn't undo point problem anymore.

Any chance to at least get the obviously missing Hierarchy Methods in a reasonnable timeframe ? Some of them already exists in the engine and it's a matter of exposing existing secret SDK function to the Editor API by creating a function.

Stuff like GetChildren(), GetAllChildren(), GetParent() would already be game-changer and i bet this is not a "Major Project"

There is no valid reason to prevent us to access child/parent instances

[OverboyDev]

I would prefer to focus on HTML/CSS for UIs. The new HTML layers feature in the latest betas should make it a lot more viable to use for that. Otherwise we could end up spending months or years reinventing the wheel and coming up with new ways to do things that are already possible with HTML/CSS. So why not use that? What is actually insufficient about it? If there are issues can they be solved another way?

I'm sorry but i don't understand why you're still asking after the countless topics and dicussions there were (on forums/twitter/old suggestion platorms/release-note comments) about it over the past 2 years. This suggestion already explain everything here (and i also reexplained this extensively again yesterday in this post after you asked for it : https://github.com/Scirra/Construct-bugs/issues/7735#issuecomment-1893734439.)

• >> There is no way to create UI in the editor that works at edit-time << (as opposed to Unity/Godot/Unreal and many other gamedev softwares )
• Worse that that HTML/CSS doesn't even allow any preview of the result in editor (while at least using Objects you currently also don't have auto-layouting in editor but you can have a clue of how it looks - and live-preview in editor would be fixed with this suggestion)
• HTML/CSS doesn't synergise as well with all existing features like 9Path/TiledBG/Sprite/Spritefonts/Text, while a behavior-based UI system would. It's more intuitive to use vanilla World Plugins and all their existing ACE to create UI, rather than using a totally different paradigm.
• Most people don't want to go through the pain of dealing with HTML/CSS for every tiny UI element they'll need in their game, most C3 users aren't webdev (in fact most of them are non-coders) and only use eventsheets and 3rd party addons.
• Hierarchy-based UI system is the industry standart, this is how it works in all major game engines such as Godot and Unity, people are used to it, thousands of released indie games are using it, newcomers and kids are already familiar with it after seeing any Youtube devlog showcasing UI.
• Exposing existing Methods to the Editor SDK isn't "reinventing the wheel", as opposed to develop endless feature for HTML/CSS-based UI that are all major projects workarounding browser limitations

Also again : every single method listed above would be useful to create Editor Tool (not only related to UI) It gives the power to create many different things, not just Grid/Vertical/Horizontal auto-layouting but also premade UI elements such as Slider-bar, Radial Menus and even non-UI-related Editor Tools.

The whole point of this suggestion is to avoid you to create UI systems, so please just give us the Methodes API (which for the most part already exist somewhere in the engine) so skymen, me or any other addondev can create and release them for the community.