diff --git a/docs/src/assets/images/getting-started/game_stub-character-1-create-button.png b/docs/src/assets/images/getting-started/game_stub-character-1-create-button.png index c2ab794e3..0c6902c77 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-character-1-create-button.png and b/docs/src/assets/images/getting-started/game_stub-character-1-create-button.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-character-10-set_dialog_position.png b/docs/src/assets/images/getting-started/game_stub-character-10-set_dialog_position.png index b878aee09..58a7df521 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-character-10-set_dialog_position.png and b/docs/src/assets/images/getting-started/game_stub-character-10-set_dialog_position.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-character-3-editor.png b/docs/src/assets/images/getting-started/game_stub-character-3-editor.png index 1bb5b30eb..772ffe5b7 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-character-3-editor.png and b/docs/src/assets/images/getting-started/game_stub-character-3-editor.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-character-6-set_texture.png b/docs/src/assets/images/getting-started/game_stub-character-6-set_texture.png index b6cdad460..fc5f75d19 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-character-6-set_texture.png and b/docs/src/assets/images/getting-started/game_stub-character-6-set_texture.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-character-8-set_feet_center.png b/docs/src/assets/images/getting-started/game_stub-character-8-set_feet_center.png index 5cb195726..b1ffe54b1 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-character-8-set_feet_center.png and b/docs/src/assets/images/getting-started/game_stub-character-8-set_feet_center.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-dialog-25-add_character_to_room.png b/docs/src/assets/images/getting-started/game_stub-dialog-25-add_character_to_room.png index e02474050..9dc23f330 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-dialog-25-add_character_to_room.png and b/docs/src/assets/images/getting-started/game_stub-dialog-25-add_character_to_room.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-dialog-27-create_button.png b/docs/src/assets/images/getting-started/game_stub-dialog-27-create_button.png index db42e8ec9..3553b51b9 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-dialog-27-create_button.png and b/docs/src/assets/images/getting-started/game_stub-dialog-27-create_button.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-dialog-30-dialog_run.png b/docs/src/assets/images/getting-started/game_stub-dialog-30-dialog_run.png index 44df65eb7..54387ddb5 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-dialog-30-dialog_run.png and b/docs/src/assets/images/getting-started/game_stub-dialog-30-dialog_run.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-32-filesystem.png b/docs/src/assets/images/getting-started/game_stub-guis-32-filesystem.png new file mode 100644 index 000000000..e63a39204 Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-32-filesystem.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-34-gui-scene.png b/docs/src/assets/images/getting-started/game_stub-guis-34-gui-scene.png new file mode 100644 index 000000000..621057651 Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-34-gui-scene.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-control_layout.png b/docs/src/assets/images/getting-started/game_stub-guis-35-control_layout.png new file mode 100644 index 000000000..3f2e5389e Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-control_layout.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons.png b/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons.png new file mode 100644 index 000000000..7f1b099bd Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons_atlas.png b/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons_atlas.png new file mode 100644 index 000000000..2cf679358 Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons_atlas.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons_source.png b/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons_source.png new file mode 100644 index 000000000..9630ad2cc Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-texture_buttons_source.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor-example.png b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor-example.png new file mode 100644 index 000000000..0ee1939fb Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor-example.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor-example_2.png b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor-example_2.png new file mode 100644 index 000000000..0901bedb1 Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor-example_2.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor.png b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor.png new file mode 100644 index 000000000..d77f37154 Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-editor.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-guis-35-theme-overrides.png b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-overrides.png new file mode 100644 index 000000000..4956e9a39 Binary files /dev/null and b/docs/src/assets/images/getting-started/game_stub-guis-35-theme-overrides.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-inv_item-23-create_button.png b/docs/src/assets/images/getting-started/game_stub-inv_item-23-create_button.png index bb611e68e..47e4635cc 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-inv_item-23-create_button.png and b/docs/src/assets/images/getting-started/game_stub-inv_item-23-create_button.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-inv_item-24-set_texture.png b/docs/src/assets/images/getting-started/game_stub-inv_item-24-set_texture.png index 7b73aae8e..1b4683113 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-inv_item-24-set_texture.png and b/docs/src/assets/images/getting-started/game_stub-inv_item-24-set_texture.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-1-create_button.png b/docs/src/assets/images/getting-started/game_stub-room-1-create_button.png index 13a0a5a58..25a652747 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-1-create_button.png and b/docs/src/assets/images/getting-started/game_stub-room-1-create_button.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-10-hs_create_button.png b/docs/src/assets/images/getting-started/game_stub-room-10-hs_create_button.png index f7d1587a0..818c37f44 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-10-hs_create_button.png and b/docs/src/assets/images/getting-started/game_stub-room-10-hs_create_button.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-11-hs_scene_tree.png b/docs/src/assets/images/getting-started/game_stub-room-11-hs_scene_tree.png index d96baab21..b4938b381 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-11-hs_scene_tree.png and b/docs/src/assets/images/getting-started/game_stub-room-11-hs_scene_tree.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-12-hs_draw_polygon.png b/docs/src/assets/images/getting-started/game_stub-room-12-hs_draw_polygon.png index 0f5372942..c15588f06 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-12-hs_draw_polygon.png and b/docs/src/assets/images/getting-started/game_stub-room-12-hs_draw_polygon.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-13-hs_interaction.png b/docs/src/assets/images/getting-started/game_stub-room-13-hs_interaction.png index f742423a7..dd0a74bb3 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-13-hs_interaction.png and b/docs/src/assets/images/getting-started/game_stub-room-13-hs_interaction.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-18-prop_scene.png b/docs/src/assets/images/getting-started/game_stub-room-18-prop_scene.png index 49a3da3e8..873edb904 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-18-prop_scene.png and b/docs/src/assets/images/getting-started/game_stub-room-18-prop_scene.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-19-prop_set_texture.png b/docs/src/assets/images/getting-started/game_stub-room-19-prop_set_texture.png index 882fe7c9e..f727a0e54 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-19-prop_set_texture.png and b/docs/src/assets/images/getting-started/game_stub-room-19-prop_set_texture.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-4-prop_create_button_.png b/docs/src/assets/images/getting-started/game_stub-room-4-prop_create_button_.png index 729b5c5c3..ae8a69315 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-4-prop_create_button_.png and b/docs/src/assets/images/getting-started/game_stub-room-4-prop_create_button_.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-7-wa_create_button.png b/docs/src/assets/images/getting-started/game_stub-room-7-wa_create_button.png index 080d7d652..4d6a675dd 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-7-wa_create_button.png and b/docs/src/assets/images/getting-started/game_stub-room-7-wa_create_button.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-8-wa_scene_tree.png b/docs/src/assets/images/getting-started/game_stub-room-8-wa_scene_tree.png index 64b4f7565..7f2539608 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-8-wa_scene_tree.png and b/docs/src/assets/images/getting-started/game_stub-room-8-wa_scene_tree.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-room-9-wa_bake_polygon.png b/docs/src/assets/images/getting-started/game_stub-room-9-wa_bake_polygon.png index 3d5efa308..4176fcf97 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-room-9-wa_bake_polygon.png and b/docs/src/assets/images/getting-started/game_stub-room-9-wa_bake_polygon.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-setup_dock_button.png b/docs/src/assets/images/getting-started/game_stub-setup_dock_button.png index 7a4a3b94b..318e804e3 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-setup_dock_button.png and b/docs/src/assets/images/getting-started/game_stub-setup_dock_button.png differ diff --git a/docs/src/assets/images/getting-started/game_stub-setup_popup.png b/docs/src/assets/images/getting-started/game_stub-setup_popup.png index 76b2726aa..41939069a 100644 Binary files a/docs/src/assets/images/getting-started/game_stub-setup_popup.png and b/docs/src/assets/images/getting-started/game_stub-setup_popup.png differ diff --git a/docs/src/getting-started/creating-a-game-stub/conclusions.md b/docs/src/getting-started/creating-a-game-stub/conclusions.md index 2e6a00fbc..ef7907793 100644 --- a/docs/src/getting-started/creating-a-game-stub/conclusions.md +++ b/docs/src/getting-started/creating-a-game-stub/conclusions.md @@ -1,5 +1,5 @@ --- -weight: 1570 +weight: 1580 --- ## Conclusions diff --git a/docs/src/getting-started/creating-a-game-stub/create-characters.md b/docs/src/getting-started/creating-a-game-stub/create-characters.md index 5632ba289..ede4f7d20 100644 --- a/docs/src/getting-started/creating-a-game-stub/create-characters.md +++ b/docs/src/getting-started/creating-a-game-stub/create-characters.md @@ -60,21 +60,26 @@ Fixing this is as simple as selecting the **Sprite2D** node in the character sce In the case of floating characters (ghosts, fairies, anti-gravity-powered mad scientists, etc), you should leave some vertical space between the scene's center and your character. Try to envision the scene line as the "floor" and decide how high above the floor the character should float. -The last thing to do is to position the place where the dialog text will be shown for the talking character. Popochiu can be customized to show dialog lines in many different positions or fashions, but its default is to show the dialogue lines somewhere above the character's head. Since the engine doesn't know how high your sprite is (see "Under the hood" note below), that's for you to decide. +The last thing to do is to position the place where the dialog text will be shown for the talking character. Popochiu can be customized to show dialog lines in many different positions or fashions. +The GUI template we selected shows the dialog lines as a caption at the bottom of the screen, but other ones show the dialogue lines somewhere above the character's head. We are going to see how to position the text for those interfaces that use the _over head_ dialogues style. -Just select the **DialogPos** node in the scene tree (_11_). A small cross will be highlighted in the scene's origin. Drag it somewhere above the character's head (or wherever makes sense to you). +Since the engine doesn't know how high your sprite is (see "Under the hood" note below), that's for you to decide. + +For this, select the character's rood node in the scene tree, and you will see a small purple square at the scene's origin. Drag it somewhere above the character's head (or wherever makes sense to you). As you see the square is labeled and connects to the element it refers to. + +If you see no square, make sure the **Dialogue Position Gizmo** is visible by checking the state of the button in the toolbar (_11_). ![Correct Character's text position](../../assets/images/getting-started/game_stub-character-10-set_dialog_position.png "Position the dialogue where it's more convenient") -This may require a bit of experimentation, but for now, this will do. +Finding the best positioning for the "voice" of each character may require a bit of trial and error, but for now, this will do. !!! info "Under the hood" - You may be wondering how exactly the text is positioned in relation to the **DialogPos** node. Here is an explanation of how Popochiu decides how your text is rendered. + You may be wondering how exactly the text is positioned in relation to the **Dialog Position** gizmo. Here is an explanation of how Popochiu decides how your text is rendered. - 1. The baseline of the text will always match the vertical position of **DialogPos**, so the text will be rendered vertically **right above** that point. - 2. The dialog line length is calculated and the text is centered on the horizontal position of **DialogPos**, so the text will be rendered horizontally **around** that point. + 1. The baseline of the text will always match the vertical position identified by the gizmo, so the text will be rendered vertically **right above** that point. + 2. The dialog line length is calculated and the text is centered on the horizontal position of gizmo, so the text will be rendered horizontally **around** that point. 3. If the text spans multiple lines, Popochiu will expand it **towards the top**, so that it doesn't cover your character (this means if you want your text under the character for some reason, multiple lines will cover your character). - 4. If the character is near the window or screen border, the text will be repositioned so that it will be entirely visible, so you don't have to worry about it becoming unreadable. This is true both for horizontal and vertical coordinates. + 4. If the character is near the window or screen border, the text will be repositioned so that it will be entirely visible, so you don't have to worry about it becoming unreadable. This is true both for horizontal and vertical coordinates. Of course, long texts may overlap the character sprint in that case, but it's for good. ### Add another character diff --git a/docs/src/getting-started/creating-a-game-stub/create-the-first-room.md b/docs/src/getting-started/creating-a-game-stub/create-the-first-room.md index 38add7fda..3fdec9dd0 100644 --- a/docs/src/getting-started/creating-a-game-stub/create-the-first-room.md +++ b/docs/src/getting-started/creating-a-game-stub/create-the-first-room.md @@ -81,9 +81,9 @@ In the Room tab of Popochiu dock, click the **Create walkable area** button (_16 In the popup window, just name your new walkable area "_Floor_" (or whatever you find descriptive enough). Click **OK** and a new element will be added to the scene. -![A new walkable area in the scene tree](../../assets/images/getting-started/game_stub-room-8-wa_scene_tree.png "Select the Perimeter node to edit the area shape") +![A new walkable area in the scene tree](../../assets/images/getting-started/game_stub-room-8-wa_scene_tree.png "Click the Edit Polygon button to edit the area shape") -Selecting the **Perimeter** node in the scene tree (_17_) to highlight a squared polygon in the center of the scene. Now you have to adjust the vertices of that polygon (_18_) to whatever makes sense. +Click the **Edit Polygon** button in the toolbar (_17_) to highlight a squared polygon in the center of the scene. Now you have to adjust the vertices of that polygon (_18_) to whatever makes sense. !!! tip To adjust the polygon, just click and drag the vertice handles around. @@ -91,12 +91,14 @@ Selecting the **Perimeter** node in the scene tree (_17_) to highlight a squared When you have adjusted your walkable area, it should look something like this: -![The polygon for the floor is over](../../assets/images/getting-started/game_stub-room-9-wa_bake_polygon.png "Click 'Bake NavigationPolygon' to complete the walkable area") +![The polygon for the floor is over](../../assets/images/getting-started/game_stub-room-9-wa_bake_polygon.png "Click "Edit Polygon" again to complete the walkable area") + +Click the **Edit Polygon** button again (_19_)to stop editing the perimeter of the floor. Save the project and run your game. Your character should now be able to move around the room, without leaving the area you defined. !!! note - If you aren't new to Godot, you may think we forgot to mention the **Bake** NavigationPolygon** button in the toolbar (_19_). That's not the case, Popochiu bakes the polygon for you. + If you aren't new to Godot, you may think we forgot to mention the **Bake NavigationPolygon** button in the toolbar (_19_). That's not the case, Popochiu bakes the polygon for you. !!! tip You usually don't want your walkable area to cover the entire floor that you painted, or your character will be able to stand on the very border of it, too near the wall, creating a terrible effect. @@ -139,8 +141,8 @@ Let's draw a shape around the window on the wall: No need to be too precise or polished, rough edges won't be perceivable while playing your game. You just need to avoid, if possible, overlapping with other hotspots (see "_Baseline_" below, to understand how polygon overlapping works). -Another important property of the hotspot is the "_Walk to point", which is the coordinates that the character will reach when you click over the hotspot. -You can set these coordinates interactively by clicking and dragging the "_Walk To point_" gizmo wherever you want in the room. You will see that the property with the same name in the inspector will update to reflect the coordinates. +Another important property of the hotspot is the "_Walk to point_", which is the coordinates that the character will reach when you click over the hotspot. +You can set these coordinates interactively by clicking and dragging the **Walk To point** gizmo wherever you want in the room. You will see that the property with the same name in the inspector will update to reflect the coordinates. For our example room, we'll set the following coordinates for the `Window` hotspot: @@ -156,7 +158,7 @@ The last property that you want to set is the _Baseline_. The baseline is simply That's not the case at all. If you don't set your baseline the right way, the polygon-delimited area of the hotspot may remain clickable even when the character is in front of it; or the other way around, a hotspot that should always be in front of the scene, may be covered by your character, making it unreachable. So, **always** set your baseline. -Our window is in the back of the room and the main character has no way to be placed behind it, so just click the baseline gizmo handler (the square in the middle of the line) and drag it at the very top so that the baseline is "as high as the scene" (or more). The character has no way to walk so high. +Our window is in the back of the room and the main character has no way to be placed behind it, so just click the **Baseline** gizmo handler (the square in the middle of the line) and drag it at the very top so that the baseline is "as high as the scene" (or more). The character has no way to walk so high. !!! info You can set the baseline even to negative values. This is what Popochiu automatically does when you name your prop `Background` or `bg`, to make sure your background is always at the very back of the scene. Keep this in mind too, if you change the baseline of other elements programmatically (via a script). diff --git a/docs/src/getting-started/creating-a-game-stub/customize-the-game-ui.md b/docs/src/getting-started/creating-a-game-stub/customize-the-game-ui.md new file mode 100644 index 000000000..0ac8f087d --- /dev/null +++ b/docs/src/getting-started/creating-a-game-stub/customize-the-game-ui.md @@ -0,0 +1,224 @@ +--- +weight: 1570 +title: Customize the Game UI +--- + +## Customize the Game UI + +!!! warning "Disclaimer" + GUIs are an important part of the player's experience and, among the many aspects that all adventure games have in common, it's the one that tends to get more customization and personal touches. + + The variety in the GUIs panorama makes them a complex topic, one that requires **dedicated effort** and some **solid Godot-related skills** to give good results. + + We will eventually provide a complete guide for custom GUIs that will cover every aspect, but this is out of the scope of this tutorial, at the moment. + + +Is that a wrap? Not yet! We are missing one very important bit: the User Interface for your game (GUI). + +When you think about an adventure game, the first thing that comes to your mind are the elements of the story: interesting characters, challenging puzzles, the visual style... those are the things that every adventure game, from the seminal _King's Quest_ to the last _Syberia_ act, have in common. + +But what differentiates your experience as a player beyond the game content, is how you interact with the game. + +For this last chapter of our _Getting Started_ guide, we are going to explain the basic concepts and anatomy of a Popochiu game's interface and show you how to customize the appearance of one of the predefined GUIs. + +!!! note + As we noted back in the [Game Setup](/getting-started/game-setup) chapter, Popochiu provides different GUIs you can use in your game, and more will be added in the future. + The concepts we'll explore in the upcoming paragraphs apply to every current and future GUIs, but - per the considerations above - applying them to different GUIs may be non-straightforward and require a bit of fiddling and understanding. Be ready to roll your sleeves and don't forget to [ask for help in our community](getting-started/getting-help). + + +### Anatomy of a GUI in Popochiu + +When you setup a new game, Popochiu creates a directory named `gui` under your `game` folder (_32_). + +The content of this directory is a _configured copycat_ of a template that contains the base GUI, which sits in the `addons/popochiu/objects/graphic_inerface` and **must be left untouched**! + + +![The GUI folder structure](../../assets/images/getting-started/game_stub-guis-32-filesystem.png) + +Everything you need to configure your GUI is in the `game/gui` directory. + +The most important files (_33_) are: + +1. `gui.gd`: this script contains the wiring logic for the interface. Usually the bulk of it is made by functions to process signals triggered by the UI element. +2. `gui.tscn`: this scene holds all the interface elements and it's initialized by the engine when the game starts. The elements in the scene are put on a dedicated layer to make them accessible. +3. `gui_commands.gd` script: this very important file holds the declaration of the GUI **commands**, a concept that Popochiu implements to make processing events coming from the GUI easier in the game scripts. + +!!! info "A brief about Commands" + This tutorial won't go deep into the topic of Commands. Also, the _2-Click Context Sensitive_ interface is very light on Commands implementation because of its very nature. + **Feel free to jump this info box if you just want to customize the interface appearence.** + + A quick way to understand commands is this: think of the Lucas 9-Verbs interface, the Sierra SCI interface, and the "Sam & Max" or "Broken Sword" icon-based interfaces. All are very **different in shape**, but they have in common that **you can select an action to perform** when you interact with a game object. + For example, you can _Pick up_ an item; you can _Examine_ or _Talk to_ a character; _Use_, _Push_ or _Give_ an object; _Walk_ around and so on. + + Commands are just this, **a set of valid actions** that are exposed by your interface, that can be attempted on every clickable game object (inventory items, props, characters, hotspots). + + Unlike almost every single Adventure Game Engines out there, Popochiu makes no assumption on those _valid actions_ but instead, gives you a framework to: + + * **Register** the Commands you need (you decide which ones) + * **Activate** them by your GUI elements (you decide the wiring) + * **Trigger** them by clicking on a game object + * **Process** different logic in your game scripts, depending on the triggered command + + Granted, this requires a bit of work when you design the interface, but the lack of assumptions won't make you jump through hoops because of design choices made by the wrong people: _us_! + +## The GUI scene + +If you open the `gui.tscn` file (_34_), you will see the _SimpleClick_ GUI's scene, that's made like this: + +![The GUI scene in the editor](../../assets/images/getting-started/game_stub-guis-34-gui-scene.png) + +As mentioned, a single scene contains all of the GUI elements. You can see them arranged in the scene editor (_35_), and how they are organized in the scene tree (_36_). + +### GUI Elements overview + +The scene file, as well as the command and script ones, will differ quite a lot between different scene templates. + +There is nothing that's inherently mandatory in every single interface, and this is both good and bad news. Good, in that you can go wild with every interface idea you can dream of - no constraints. Bad in that there are little rules to follow when creating custom GUIs. + +All the provided interfaces though, share some common and usually necessary elements: + +* The **Cursor** node is there to hold the animations used by the actual mouse pointer. + + !!! warning + At the time of writing, this is NOT the actual cursor that will be shown by the engine. Popochiu will just rob this node of its animations but will ignore all the other properties. For example, changing the size or modulation of this node, won't affect the cursor at all. + We plan to change this in the future, for convenience. + +* The **DialogCaption** is the element that will show what the characters say in the game. This node has its scene, that provides a configurable set of variations, like "above the head" text, to text panel, with or without a character portrait, to caption text displayed at a fixed position. +* The **DialogMenu** is the panel on which you select the dialog lines. This can be changed to an icon bar (as in "Sam & Max Hit the Road") or any other stuff, but it's pretty common in its basic form (scrollable list of phrases). +* The **Popups**: conveniently grouped under their control parent, are those "in game" windows used to save and load games, configuring settings, maybe displaying the inventory, and otherwise showing messages to the user. + +Other elements are specific to this interface, like the **InventoryBar** and **SettingsBar**, that in the _SimpleClick_ interface, appear on top of the screen when hovered with the cursor. + +In more graphically "explicit" (and cluttered) interfaces, like Sierra and 9 Verbs, you can find more elements, arranged in different order. For example the verbs panel and the inventory grid are pretty complex elements in the 9-Verbs UI, while the inventory appears in a grid overlay in the Sierra one. + +!!! info "Under the hood" + To guarantee a strong degree of decoupling, the GUI elements are wired to the rest of the game with signals. The logic to process those signals is in the `gui.gd` script of every interface. + + We are not going to detail this now, but those who are skilled in programming (or who feel more adventurous) should feel free to take a look. + +### How to visually customize your GUI + +Now that we have a broad idea of how a GUI is organized, it should be easy to recognize the various elements in the running game. + +Customizing them requires a bit of exploration though. Because of the way Godot manage the visual style of controls, there is nothing like a "single source of truth" for how an element appears. + +The good news anyway is that Popochiu does it's best to reason in a "cascading" way, setting the standard with a base theme and overriding only what's necessary in the single elements. + +!!! tip + We tried to be as clear as possible. If you get lost in this section, you may want to go learning some bits of Godot that will make everything easier to follow: + + * [Themes](https://docs.godotengine.org/en/stable/tutorials/ui/gui_skinning.html#basics-of-themes) + * [Theme Editor](https://docs.godotengine.org/en/stable/tutorials/ui/gui_using_theme_editor.html) + * [Size and anchors](https://docs.godotengine.org/en/stable/tutorials/ui/size_and_anchors.html) + + We strongly suggest you take the time to learn about Godot theming and skinning concepts, as well as gain confidence with the theme editor to make the most out of this tutorial. + +#### The GUI styling cascade + +##### 1. Theme + +If you try our the various GUIs that Popochiu provides out of the box, you will notice that they share a common style: transparent black panels, a single font for every button and label, some custom control like check buttons, sliders, etc. + +These features are all defined in a base theme, that Popochiu makes available to you at `game/gui/resources/gui_theme.tres`. Double-click it in the file system (_37_) tab to open the Godot theme editor (_38_): + +![Base GUI theme editor](../../assets/images/getting-started/game_stub-guis-35-theme-editor.png) + +From here, you can set a large number of properties for each Control node. For example, let's change the color of the panels to a bright, translucent red. + +!!! info + If you're new to Godot GUIs, when we mention _Control nodes_, we mean all nodes that inherit from the _Control_ node-types. These node types are all dedicated to implementing your game user interfaces. Popochiu leverages these node types, not reinventing the wheel, and extends them to create convenient variants. + +![Select PanelContainer node type](../../assets/images/getting-started/game_stub-guis-35-theme-editor-example.png) + + +The **Type** dropdown contains every node type for which this theme specify a style. What's not mentioned here is simply rendered with the default Godot theme. You can see the list of custom controls is pretty short. Not much is needed for an adventure game, usually! + +Select **PanelContainer** node type (_39_), to see the theme rules that apply to that node. + +![Edit the style settings](../../assets/images/getting-started/game_stub-guis-35-theme-editor-example_2.png) + +Each node has the same set of tabs in the property areas. Some will apply and some will not, depending on the node type (for example, setting a font for an element which renders no text won't be possible). +We are going to open the **Style** tab and we'll find out that a custom style is applied to the **panel** property already (_40_). The value is of type _StyleBoxFlat_, an object that represents a (you don't say?!) flat-colored area. + +As every other Godot resource, clicking it opens the inspector. You can find the **BG Color** property right on top of it. Change it to a bright red and see what happens in your GUI scene. + +You can test your game too, if you want to lose some diopters. + +!!! warning + Don't forget to **Save** your theme, by clicking the button at the top right of the Theme Editor! + +##### 2. Theme overrides + +The base theme sets a standard for colors, fonts, margins and alignments, but GUI elements has this tendency to be _very contextual_. They may need some touches to their look depending on where they appear. + +For example, some buttons may need a bit more margin around their content, or maybe they need to be rendered without their translucent black background in a specific position. + +For that, the best option is resorting to **Theme Overrides**. These are settings that apply not to a node types, but only to a specific node in a scene. + +One example is the **HoverText** scene in the _SimpleClick_ GUI. Open the scene and you will see that the **Label** node therein (_42_) gets rendered with a nice text outline (_43_), which is nowhere to be found in the `gui_theme.tres`. + +![Theme overrides](../../assets/images/getting-started/game_stub-guis-35-theme-overrides.png) + +This is needed because that element may be rendered anywhere on the screen, sometimes over the mouse pointer, to represent hotspot, props or character names, so the white label can get unreadable on a bright scene background. Putting a high-contrast (black) outline will make it always stand out enough. + +Since this property is very specific to this node, we set it as a theme override (_44_). Godot highlights the properties sets that are subject to a change. Go and see yourself how we set up that specific outline. + +Remember to do this when you have an element that should not behave as the standard ones. + +##### 3. Controls layout + +Each Control node has a very convenient set of properties under the **Layout** category in the inspector. + +![Control layout](../../assets/images/getting-started/game_stub-guis-35-control_layout.png) + +While a theme sets the visual aspect of controls, it's on the layout of each single control that you define its behavior in relation to the surrounding elements. + +Do you want a button to shrink to the minimum possible size and align to the center-left of its container? Do you want to set a minimum size for the button so that if the context gets cluttered, it won't become unreadable? Or maybe you want it stuck in a specific position on the screen? That's where you define such behaviors. + +Make sure you review the official documentation to fully understand how to use these properties. + +##### 4. Textures and atlases + +Some elements, like the mouse cursor, or some menu buttons, are rendered as images. The most evident example in the _SimpleClick_ GUI is the **SettingsBar** element. + +Open the scene and you will see that each button (_47_) is a _TextureButton_ node (_48_). + +![Texture buttons](../../assets/images/getting-started/game_stub-guis-35-texture_buttons.png) + +!!! note + In this very case, the nodes are of type _PopochiuSettingsBarButton_ because we needed all of them to have a couple very specific properties, but you can see in the inspector that they are _TextureButtons_ too. + +As you can see, the textures applied to the _Normal_, _Pressed_ and _Hovered_ states for the buttons are of type _AtlasTextures_. That's because the icons PNG are saved as a tileset, with each state of a specific color: + +![A texture button source example](../../assets/images/getting-started/game_stub-guis-35-texture_buttons_source.png) + +An _AtlasTexture_ allows you to specify a specific region (_50_) of this source file, so you hold all the same icons state together and your file system stays tidy: + +![The atlas setting for a button](../../assets/images/getting-started/game_stub-guis-35-texture_buttons_atlas.png) + + +You are not forced to use an Atlas or anything else than a simple texture for your elements. +Actually, if you don't like the standard button icons, and want to change or recolor them, you just have to edit the source PNG files. + +Unless you change the size of the single tiles, you will see the updated icons as soon as you save them in your graphics editor of choice. + +!!! note + We didn't mention that here, but if you want to make without a specific function (for example, if you don't want your users to change the text preferences, or see the game action log), you can just hide these buttons in the scene _et voilà_. + +##### 5. Scripts + +The last bit of customization are the script attached to each GUI component. + +The logic in there really depends on the function and design of the component. That's probably what makes a GUI unique and really change the experience of the player. + +Popochiu wire the GUIs and to the Engine events by signals and commands. This architecture ensures a very loose coupling between the GUI and the Engine, that allows for easier upgrades of the engine during the development of a single game. + +Also, each element has its short and to the point script, and communicates with others by signals, using the `gui.gd` script attached to each GUI's root node as a signal bus. + +Providing a full list of signals is out of the scope of this guide, but we'll soon provide a reference and a dedicated walkthrough on how to create a custom GUI from scratch. + +For the scope of this guide, if you did follow along with this paragraph, you are encouraged to edit and evolve the scripts as you want! + +--- + +**Congratulations! You've got to the end of this introductory guide!** diff --git a/docs/src/getting-started/creating-a-game-stub/game-setup.md b/docs/src/getting-started/creating-a-game-stub/game-setup.md index 7d49afc5a..878b04d49 100644 --- a/docs/src/getting-started/creating-a-game-stub/game-setup.md +++ b/docs/src/getting-started/creating-a-game-stub/game-setup.md @@ -44,20 +44,19 @@ Finally, the **Game type** (_3_) select box will set a bunch of project settings ### Select game GUI -Since version 2.0, Popochiu comes with a preset of different GUI templates, and a set of features to create your own custom one. -GUI templates will contain everything you need, from assets to logic, to mimic one of the most common game interfaces of the Adventure genre. +Since version 2.0, Popochiu comes with a preset of different GUI templates, and in the next version, it will provide a set of features to create your own custom one. +Preset GUI templates will contain all the assets and logic thay you need to mimic some of the most common game interfaces of the Adventure genre. In the **GUI Template** (_4_) section of the Setup popup, you can click on a GUI icon to select which template to apply: -* **Custom**: select this if you want to create your GUI. That's the "No template, please" option. -* **9 Verbs**: inspired by the original SCUMM interface, first seen in _Monkey Island 2: LeChuck's Revenge_. -* **Sierra**: inspired by the early 90s SCI interface, common to _King's Quest_ and _Space Quest_ games in the early 90s. -* **2-Click Context-sensitive**: the most basic interface for an Adventure Game, common to many modern titles like _Deponia_ - left-click to walk and interact, right-click to examine. +* **9 Verbs**: inspired by the original SCUMM interface, first seen in _Maniac Mansion_, but getting its final form with _Monkey Island 2: LeChuck's Revenge_, and used by many games up to the recent _Thimbleweed Park_. +* **Sierra**: inspired by the early 90s SCI interface, common to _King's Quest_ and _Space Quest_ series. It took many forms, always specific to Sierra games. Very useful for projects that want to bring back that historical interaction patterns. +* **SimpleClick**: the most basic and straightforward interface for an Adventure Game, common to many modern titles like _Deponia_ - left-click to walk and interact, right-click to examine. This version is influenced by early PowerHoof productions. !!! warning - You can change your mind and apply a different template later during the development of your game, but mind that doing this will **replace** your GUI (and all the custom logic or graphics) with a new template. + You can change your mind and apply a different template later during the development of your game, but doing this will **replace** your GUI (and all the custom logic or graphics) with a new template. - Also, keep in mind that some GUIs will take up space on the screen (like the 9 Verbs one), and this will impact your backgrounds. + Also, keep in mind that some GUIs will take up space on the screen (like the 9 Verbs one), so please, consider this when designing your backgrounds. !!! note You can go back and review your game setup choices at any moment, by clicking the "Setup" button at the bottom of the [Popochiu Main Dock](#TODO). diff --git a/docs/src/getting-started/creating-a-game-stub/use-inventory-items.md b/docs/src/getting-started/creating-a-game-stub/use-inventory-items.md index ff16ab71e..0d07561de 100644 --- a/docs/src/getting-started/creating-a-game-stub/use-inventory-items.md +++ b/docs/src/getting-started/creating-a-game-stub/use-inventory-items.md @@ -28,4 +28,8 @@ Save the script and run the game. Pick the toy car up, select it from the invent You should see the dialog happen, and the car is removed from your inventory. -**Congratulations! You've got to the end of this introductory guide!** +Well, our game is done, right? It seems like we addressed everything: locations, characters, dialogues, interactions with the environment and the use of inventory items. + +But one last bit is missing and it's the way the player interacts with all of this: the GUI. + +Let's take a glance at how to customize one of the already available Popochiu game interfaces. \ No newline at end of file