From 668377d839765b6f25347d2baf2023f82c5c2b7e Mon Sep 17 00:00:00 2001 From: Joel Gomes da Silva Date: Wed, 15 May 2024 22:54:53 -0300 Subject: [PATCH] doc: add basic usage to README --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/README.md b/README.md index 27d4008..234a8b7 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,81 @@ See the example scene on `addons/simple-gui-transitions/example` to see this plu - Enable the plugin on `Project > Project Settings > Plugins` - Reload your current project +## Basic Usage +### Node Configuration +After installing the plugin, enabling it on `Project > Project Settings > Plugins` +and reloading your project, you can instance the node `GuiTransition` in your scene. +See the properties in the next section to learn how to configure it properly, but pay attention to the required properties: + +- `Layout`: The main layout node. It will be hidden and shown accordingly. Should be the topmost node of the current GUI layout, usually the scene root. If you don't set the `Layout ID` property, this node's name will be assumed as the layout ID. **Always required!** +- `Controls`: An array of nodes that will be animated in sequence. **Required if `Group` is not set!** +- `Group`: A node with children controls to be animated in sequence. **Required if `Controls` is not set!** + +### Triggering Transitions +After setting up its properties, the layout should at least be shown with a transition at startup. +After that you can use code to trigger the transitions. For example: + +```gdscript +func _on_button_pressed() -> void: + GuiTransitions.hide("Hud") +``` + +This will hide the layout with the layout ID `Hud`. +Keep in mind that you can have multiple layouts with the same ID, so you can +add different transitions to specific parts of the interface, for example, +the health and mana bars in the top of the screen would slide upwards and the +equipment list in the bottom would slide downwards. In that example, you would +have two `GuiTransition` nodes in the scene with the same `Layout ID` (`Hud`) and +different `Controls`/`Group` and `Animation Enter`/`Animation Leave` properties. +This way, you can have different transitions for each part of the interface and +trigger all parts with a single command. + +You can change to another layout with the `go_to` method. +For example, you may want to hide the HUD and show the pause menu. +To achieve this, the HUD must be visible and the pause menu must be hidden. +The following code will hide the HUD and show the pause menu. + +```gdscript +func _on_button_pause_pressed() -> void: + GuiTransitions.go_to("Pause") +``` + +You can even pass a Callable as the second argument of the `go_to` method if you want to execute a function in between the transitions. +However, if you like a more explicit code, other common operation is waiting +for the layout to finish its transition and triggering the next layout afterwards. +This can be easily done with the following code: + +```gdscript +func _on_button_pause_pressed() -> void: + prints("Hud will now hide") + GuiTransitions.hide("Hud") + await GuiTransitions.hide_completed + prints("Hud hidden, will now show Pause") + GuiTransitions.show("Pause") +``` + +Another common operation is to not allow controls to be interacted when the +layout is transitioning. The plugin actually do not allow buttons and other +interactable nodes to be interacted during the transition, but only if the nodes +affected by the transition (the `Controls` or `Group`) are interactable, that is: +buttons and other interactable nodes. In the case you the transition is affecting +an container or any other node that is not interactable, the interaction will not +be blocked. In such cases, you may check if a transition is currently in progress +with the `in_transition` method: + +```gdscript +func _on_button_increase_strength_pressed() -> void: + if not GuiTransitions.in_transition(): + strength += 10 + GuiTransitions.go_to("Hud") +``` + +That way, you avoid the player clicking the button during the transition and +increasing the player's strength multiple times. + +Simple GUI Transitions is exactly that: simple to set up and use. +Check the detailed documentation below to learn more. + ## Global Settings The default transition settings can be set on `Project > Project Settings > GUI Transitions > Config` (you may need to enable `Advanced Settings` to see this section). Those settings will be applied on top of any `Default` property on the node `GuiTransition`. This is useful to increase or decrease the speed of transitions on the whole project, for example. See each property description below.