9. User Interface & Menus
# 9. User Interface & Menus
The Defold Platformer Framework includes a comprehensive user interface system that allows you to create menus, HUDs, and other UI elements for your game. This section covers how to work with the UI components included in the framework.
## UI Components Overview
The framework provides several pre-built UI components:
- Main menu
- Pause menu
- Game HUD (heads-up display)
- Level complete screen
- Game over screen
- Options menu
All UI elements are built using Defold's GUI system and can be customized to match your game's visual style.
## GUI Scenes Structure
The UI components are organized in the following structure:
```mermaid
graph TD
A[Main UI Controller] --> B[Main Menu]
A --> C[Game HUD]
A --> D[Pause Menu]
A --> E[Level Complete]
A --> F[Game Over]
A --> G[Options Menu]
B --> B1[Play Button]
B --> B2[Options Button]
B --> B3[Credits Button]
B --> B4[Exit Button]
C --> C1[Health Display]
C --> C2[Score Display]
C --> C3[Collectibles Counter]
C --> C4[Timer]
D --> D1[Resume Button]
D --> D2[Restart Button]
D --> D3[Options Button]
D --> D4[Quit Button]
```
## Working with the Main Menu
The main menu is the first screen players see when launching your game. To customize it:
1. Open `/gui/main_menu.gui` in the Defold editor
2. Modify the existing elements or add new ones
3. Update the script `/gui/main_menu.gui_script` to handle any new functionality
### Main Menu Script
The main menu script handles button clicks and transitions:
```lua
function on_message(self, message_id, message, sender)
if message_id == hash("click") then
if message.node == gui.get_node("play_button") then
msg.post("main:/controller", "start_game")
elseif message.node == gui.get_node("options_button") then
msg.post("main:/controller", "show_options")
elseif message.node == gui.get_node("exit_button") then
msg.post("@system:", "exit", {code = 0})
end
end
end
```
## Game HUD
The game HUD displays important information during gameplay such as:
- Player health
- Score
- Collected items
- Timer
- Level information
### Customizing the HUD
To customize the HUD:
1. Open `/gui/game_hud.gui` in the Defold editor
2. Modify the existing elements or add new ones
3. Update the script `/gui/game_hud.gui_script` to handle any new functionality
### Updating HUD Values
The HUD receives messages to update its values:
```lua
function on_message(self, message_id, message, sender)
if message_id == hash("update_health") then
update_health_display(self, message.health, message.max_health)
elseif message_id == hash("update_score") then
update_score_display(self, message.score)
elseif message_id == hash("update_coins") then
update_coin_display(self, message.coins)
end
end
```
## Pause Menu
The pause menu appears when the player pauses the game. To customize it:
1. Open `/gui/pause_menu.gui` in the Defold editor
2. Modify the existing elements or add new ones
3. Update the script `/gui/pause_menu.gui_script` to handle any new functionality
### Pause Menu Implementation
The pause menu is shown/hidden through messages:
```lua
function on_message(self, message_id, message, sender)
if message_id == hash("show") then
gui.set_enabled(self.root, true)
msg.post(".", "acquire_input_focus")
-- Pause game logic
msg.post("main:/controller", "pause_game")
elseif message_id == hash("hide") then
gui.set_enabled(self.root, false)
msg.post(".", "release_input_focus")
-- Resume game logic
msg.post("main:/controller", "resume_game")
end
end
```
## Level Complete and Game Over Screens
These screens appear when the player completes a level or loses the game. They follow a similar structure to the pause menu and can be customized in the same way.
## Adding Animations to UI Elements
You can add animations to make your UI more dynamic:
```lua
-- Animate a button on hover
function animate_button(node)
local scale = 1.1
gui.animate(node, "scale", vmath.vector3(scale, scale, 1), gui.EASING_OUTQUAD, 0.2)
end
-- Reset animation
function reset_button(node)
gui.animate(node, "scale", vmath.vector3(1, 1, 1), gui.EASING_OUTQUAD, 0.2)
end
```
## Creating Custom UI Elements
To create custom UI elements:
1. Create a new GUI file in the `/gui` directory
2. Design your UI using Defold's GUI nodes (Box, Text, Pie, etc.)
3. Create a script to handle the UI logic
4. Register the UI in the main controller
## Responsive UI Design
The framework supports responsive UI that adapts to different screen sizes:
```lua
function init(self)
-- Get the current screen dimensions
self.screen_width = render.get_window_width()
self.screen_height = render.get_window_height()
-- Adjust UI elements based on screen size
adjust_ui_for_screen(self)
end
function adjust_ui_for_screen(self)
local scale_factor = math.min(self.screen_width / 1280, self.screen_height / 720)
gui.set_scale(self.root, vmath.vector3(scale_factor, scale_factor, 1))
-- Center the UI
local pos = vmath.vector3(self.screen_width/2, self.screen_height/2, 0)
gui.set_position(self.root, pos)
end
```
## Handling Input in UI
The framework uses Defold's input system to handle user interactions:
```lua
function on_input(self, action_id, action)
if action_id == hash("touch") and action.pressed then
local nodes = gui.get_nodes()
for _, node in ipairs(nodes) do
if gui.pick_node(node, action.x, action.y) then
handle_button_click(self, node)
return true
end
end
end
return false
end
```
## UI Themes and Styling
The framework includes a simple theming system that allows you to change the look of all UI elements at once:
```lua
-- In your theme.lua file
local theme = {
colors = {
primary = vmath.vector4(0.2, 0.4, 0.8, 1.0),
secondary = vmath.vector4(0.8, 0.2, 0.4, 1.0),
background = vmath.vector4(0.1, 0.1, 0.1, 1.0),
text = vmath.vector4(1.0, 1.0, 1.0, 1.0)
},
fonts = {
title = hash("title_font"),
body = hash("body_font")
}
}
return theme
```
Apply the theme in your GUI scripts:
```lua
local theme = require("gui.theme")
function init(self)
-- Apply theme colors
gui.set_color(gui.get_node("background"), theme.colors.background)
gui.set_color(gui.get_node("title"), theme.colors.text)
-- Apply theme fonts
gui.set_font(gui.get_node("title"), theme.fonts.title)
end
```
## Best Practices for UI Development
1. **Keep it simple**: Don't overcrowd your UI with too many elements
2. **Consistent style**: Maintain a consistent visual style across all UI screens
3. **Feedback**: Provide visual and audio feedback for user interactions
4. **Accessibility**: Consider different screen sizes and accessibility options
5. **Performance**: Minimize the number of nodes and animations to maintain good performance
By following these guidelines and using the provided UI components, you can create a polished and professional user interface for your platformer game.