### Install Make on Ubuntu

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/toolchain-and-dependencies.md

Use this command to install GNU Make on Ubuntu systems.

```bash
sudo apt install build-essential
```

--------------------------------

### Starting Dialogs

Source: https://github.com/carenalgas/popochiu/wiki/IDialog

These methods are used to initiate dialog sequences. `show_dialog` starts a named dialog tree, while `show_inline_dialog` presents a list of options directly.

```APIDOC
## Starting Dialogs

### Description
Use these methods to start dialog sequences or present inline options.

### Methods
- `show_dialog(dialog_name: String)`: Starts a branching dialog tree with the given name.
- `show_inline_dialog(options: Array)`: Displays a list of inline options for the user to choose from.

### Example
```GDScript
D.show_dialog('ConfirmAction')
D.show_inline_dialog(['Yes', 'Nope', "Don't know..."])
```
```

--------------------------------

### Direct Dialog Start (v1.9.0+)

Source: https://github.com/carenalgas/popochiu/wiki/Getting-started

Version 1.9.0 introduced direct property access to start dialogs, such as D.Welcome.start().

```gdscript
D.Welcome.start()
```

--------------------------------

### Install Make with Chocolatey

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/toolchain-and-dependencies.md

Install GNU Make on Windows using the Chocolatey package manager. This is the preferred method for native Windows installations.

```bash
choco install make
```

--------------------------------

### Install Make on Arch Linux

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/toolchain-and-dependencies.md

Use this command to install GNU Make on Arch Linux systems.

```bash
sudo pacman -Sy base-devel
```

--------------------------------

### setup_camera

Source: https://github.com/carenalgas/popochiu/wiki/PopochiuRoom

Configures the camera to follow the limits of this room's camera setup.

```APIDOC
## setup_camera

### Description
Called by Popochiu when loading the room to make the camera follow the limits of this room's camera setup.

### Method
`setup_camera()`
```

--------------------------------

### Singleton Access Examples

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/the-engine-handbook/scripting-principles.md

Examples of accessing various singleton objects provided by the engine. These singletons offer access to different game systems and data.

```gdscript
var E = Engine.get_singleton() # Access the Engine singleton
var R = Room.get_singleton() # Access the Room singleton
var C = Camera.get_singleton() # Access the Camera singleton
var I = Input.get_singleton() # Access the Input singleton
var D = Dialog.get_singleton() # Access the Dialog singleton
var A = Audio.get_singleton() # Access the Audio singleton
var G = Game.get_singleton() # Access the Game singleton
var T = Tilemap.get_singleton() # Access the Tilemap singleton
var Globals = Globals.get_singleton() # Access the Globals singleton
var Cursor = Cursor.get_singleton() # Access the Cursor singleton
```

--------------------------------

### Install Make with Xcode Command Line Tools on macOS

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/toolchain-and-dependencies.md

Install GNU Make on macOS by installing the Xcode command line tools. You will need to agree to the license in a popup.

```bash
xcode-select --install
```

--------------------------------

### start

Source: https://github.com/carenalgas/popochiu/wiki/PopochiuDialog

Initiates the dialog sequence.

```APIDOC
## start()

### Description
Starts this dialog by calling `show_dialog` in [IDialog](https://docs.godotengine.org/en/stable/classes/class_resource.html) passing as argument its own `script_name`.

### Method
Public

### Parameters
None
```

--------------------------------

### Room Lifecycle Events in GDScript

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/the-engine-handbook/scripting-principles.md

Implement room entry, transition completion, and exit logic. Use `_on_room_entered` for initial setup, `_on_room_transition_finished` for gameplay start, and `_on_room_exited` for cleanup.

```gdscript
extends PopochiuRoom

func _on_room_entered() -> void:
    # Set the stage before the player sees anything
    A.mx_background_theme.play()
    if state.visited_first_time:
        C.player.teleport_to_marker("EnterPos")
    else:
        C.player.teleport_to_marker("StartingPos")
        C.player.face_left()

func _on_room_transition_finished() -> void:
    # The room is now visible: start gameplay
    if state.visited_first_time:
        await E.cutscene([
            "Popsy: Where am I?",
            "Popsy: This place looks familiar...",
        ])

func _on_room_exited() -> void:
    # Clean up before leaving
    A.mx_background_theme.stop()
```

--------------------------------

### GDScript Class Example Following Guidelines

Source: https://github.com/carenalgas/popochiu/wiki/Coding-guidelines

This example demonstrates the recommended structure and conventions for GDScript classes in the Popochiu project, including ordering of elements, naming conventions, and static typing.

```gdscript
# Example class of coding guidelines.
#
# This fake GDScript class shows how the code in most of the Popochiu scripts
# is ordered and written.
# Group things according to the Code order section.
@tool
# Use PascalCase for class and node names
class_name PopochiuCodeGuidelines
extends Node

# Use the past tense to name signals
signal game_loaded(Dictionary)
signal ui_requested

enum Types {
	ROOM,
	CHARACTER,
	INVENTORY_ITEM,
	DIALOG,
}
enum FlipsWhen { NONE, MOVING_RIGHT, MOVING_LEFT }

# Use SNAKE_CASE (in uppercase) when defining constants
const SELECTED_FONT_COLOR := Color("706deb")
# Keep individual lines of code under 100 characters. If you can, try to keep
# lines under 80 characters
const PLAYER_CHARACTER_ICON :=
preload("res://addons/Popochiu/icons/player_character.png")
# Use PascalCase when loading a class into a constant (or a variable)
const PopochiuClickable :=
preload("res://addons/Popochiu/Engine/Objects/Clickable/PopochiuClickable.gd")

export var is_clickable := true
export var object_name := "" setget set_object_name

# Whenever you can use static typing when defining variables and method
# parameters
var is_cutscene_skipped := false
var hovered: PopochiuClickable = null setget set_hovered, get_hovered

# Private variables and methods start with underscore: _
#   > It will also apply to virtual methods from Popochiu 2.0 onwards
var _config := ConfigFile.new()
var _is_camera_shaking := false
var _shake_timer := 0.0
var _hovered_queue := []

@onready var btn_create: Button = %BtnCreate
@onready var creation_popup: Popup = %Loading


#region Godot ######################################################################################
# Surround functions with two blank lines
func _ready() -> void:
	_config = PopochiuResources.get_data_cfg()
	
	btn_create.pressed.connect(_on_create_pressed)

	_do_the_private_thing()
#     blank line 1   \ ( u.u)>
#     blank line 2   <(u.u ) /
func _process(delta: float) -> void:
	if _is_camera_shaking:
		_shake_timer -= delta


func _input(event: InputEvent) -> void:
	if event.is_action_released("popochiu-skip"):
		is_cutscene_skipped = true


#endregion

#region Virtual ####################################################################################
func _on_click() -> void:
	pass


func _on_right_click() -> void:
	pass


#endregion

#region Public #####################################################################################
func wait(time := 1.0, is_in_queue := true) -> void:
	if is_in_queue:
		yield()

	if is_cutscene_skipped:
		yield(get_tree(), "idle_frame")
		
		return
	
	yield(get_tree().create_timer(time), "timeout")


# Declare the return type of functions whenever you can
func do_something() -> bool:
	prints("I have to do something")
	return true


#endregion

#region SetGet #####################################################################################
func set_hovered(value: PopochiuClickable) -> void:
	hovered = value
	
	if not hovered:
		G.show_info()


func get_hovered() -> PopochiuClickable:
	return null if _hovered_queue.is_empty() else _hovered_queue[-1]



#endregion

#region Private ####################################################################################
func _on_create_pressed() -> void:
	creation_popup.popup_centered_minsize(Vector2(640, 360))


func _do_the_private_thing() -> void:
	prints("Shhhhhhhh", "...", "This is stupid!")


#endregion

```

--------------------------------

### Starting Specific Dialog Trees (v1.9.0+)

Source: https://github.com/carenalgas/popochiu/wiki/IDialog

Since version 1.9.0, you can start specific dialog trees directly using their namespaced access.

```APIDOC
## Starting Specific Dialog Trees (v1.9.0+)

### Description
Directly start a specific dialog tree by accessing its namespace.

### Method
- `D.[DialogName].start()`: Starts the dialog tree identified by `[DialogName]`.

### Example
```gdscript
D.ChatWithGlottis.start()
```
```

--------------------------------

### Run Documentation Development Server

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/toolchain-and-dependencies.md

Navigate to the 'docs' directory and run this command to start a Docker container for live previewing the documentation.

```bash
make docs-up
```

--------------------------------

### Hotspot Click Interaction Example

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/the-engine-handbook/scripting-principles.md

Implement click interactions for hotspots. This example shows a hotspot acting as a door that navigates to a new room on left-click and provides a description on right-click.

```gdscript
extends PopochiuHotspot

func _on_click() -> void:
    R.goto_room("Kitchen")

func _on_right_click() -> void:
    await C.player.face_clicked()
    await C.player.say("It leads to the kitchen.")
```

--------------------------------

### Prop Click Interaction Example

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/the-engine-handbook/scripting-principles.md

Implement click interactions for props. This example shows how to make a player character walk to the clicked prop, say something, and then react to a right-click.

```gdscript
extends PopochiuProp

func _on_click() -> void:
    await C.player.walk_to_clicked()
    await C.player.say("It's an old trophy. Dusty but proud.")

func _on_right_click() -> void:
    await C.player.face_clicked()
    await C.player.say("I don't want to touch it.")
```

--------------------------------

### Set and Get Methods

Source: https://github.com/carenalgas/popochiu/wiki/PopochiuProp

Methods for setting and getting properties of the PopochiuProp.

```APIDOC
## Set and get

* **set_current_frame**([int] value) *void*

  Updates the `current_frame` property of the `$Sprite` child to `value`.
* **set_frames**([int] value) *void*

  Updates the `hframes` property of the `$Sprite` child to `value`.
* **set_texture**([Texture] value) *void*

  Updates the `texture` property of the `$Sprite` child to `value`.
```

--------------------------------

### Start Branching Dialogs with IDialog

Source: https://github.com/carenalgas/popochiu/wiki/IDialog

Use these methods to initiate dialogs. 'show_dialog' starts a named dialog tree, while 'show_inline_dialog' creates a dialog with a list of options on the fly. Connect to 'dialog_finished' to be notified when a dialog completes.

```GDScript
D.show_dialog('ConfirmAction')
D.show_inline_dialog(['Yes', 'Nope', "Don't know..."])
D.connect('dialog_finished', self, '_leave_room') # Calls the "_leave_room" method once the current branching dialog has finished
```

--------------------------------

### Install Make with Homebrew on macOS

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/toolchain-and-dependencies.md

Install GNU Make on macOS using the Homebrew package manager. This is the preferred method.

```bash
brew install make
```

--------------------------------

### Camera Zoom and Offset Example

Source: https://github.com/carenalgas/popochiu/wiki/Popochiu

Demonstrates how to offset the camera before zooming in and then restore it. Useful for ensuring dialogs are visible within the viewport during zoom effects.

```GDScript
E.run([
    # Offset the camera before it zooms in so dialogs are shown inside the viewport
    E.camera_offset(Vector2(0.0, -16.0)),
    E.camera_zoom(Vector2.ONE * 0.5, 0.5),
    'Player: Oh, oh.',
    # Restore the camera's offset to its default value before zooming out
    E.camera_offset(),
    E.camera_zoom(Vector2.ONE, 0.5)
  ])
```

--------------------------------

### Markdown Definition List Example

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/contributing-documentation/conventions.md

Provides an example of creating definition lists in Markdown, which are an alternative to HTML's <dl> tags. Supports multi-line definitions and newlines.

```markdown
**This is a term or question**
: This is it's definition or answer.  
Multiple lines are supported (notice the double space in the line above, to create a newline character)

**Can I do more?**
: Sure, you are supposed to!
```

--------------------------------

### Start Dialog Node Directly (v1.9.0+)

Source: https://github.com/carenalgas/popochiu/wiki/IDialog

Since version 1.9.0, you can directly start a dialog node using its node path. This provides a more direct way to access and initiate specific dialogs.

```GDScript
D.ChatWithGlottis.start()
```

--------------------------------

### Initiate Branching Dialogs

Source: https://github.com/carenalgas/popochiu/wiki/Getting-started

Start dialog sequences using D.show_dialog() for named dialogs or D.show_inline_dialog() for a list of options.

```gdscript
D.show_dialog('Welcome')
D.show_inline_dialog(['Yes', 'Nope', "Don't know..."])
```

--------------------------------

### show_dialog(script_name: String)

Source: https://github.com/carenalgas/popochiu/wiki/IDialog

Starts a PopochiuDialog identified by `script_name`. The dialog tree concludes when the `dialog_finished` signal is emitted.

```APIDOC
## show_dialog(script_name: String)

### Description
Starts the [PopochiuDialog](./PopochiuDialog) identified with `script_name`. The dialog tree will finish when the signal `dialog_finished`, in this script, is emitted. The list of dialogs in the [Main tab](https://github.com/mapedorr/popochiu/wiki/Main-tab) shows the names you can pass to this method in order to start any of those dialog trees.

### Method
void

### Parameters
#### Path Parameters
- **script_name** (String) - The name of the dialog script to start.
```

--------------------------------

### Set and Get Methods

Source: https://github.com/carenalgas/popochiu/wiki/PopochiuClickable

Methods for accessing and modifying properties like description, walk-to point, and baseline, including editor helper visualization.

```APIDOC
## Set and get

* **get_description()** *[String](https://docs.godotengine.org/en/stable/classes/class_string.html)*

  Returns the `description` of the object passing it through `E.get_text()`, which can be used to show it in different languages when using localization.

* **get_walk_to_point()** *[Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html)*

  When running the game, returns the global position of the `walk_to_point`. When in the Editor, returns the value of the `walk_to_point`.

* **set_baseline(** [int](https://docs.godotengine.org/en/stable/classes/class_int.html) `value` **)** *void*

  When in the Editor, makes the `$BaselineHelper` child to be rendered in the Canvas showing a line where the `baseline` of this object is.

* **set_room(** [PopochiuRoom](./PopochiuRoom) `value` **)** *void*

  Calls `on_room_set()` when the room to which this object belongs is setted.

* **set_walk_to_point(** [Vector2](https://docs.godotengine.org/en/stable/classes/class_vector2.html) `value` **)** *void*

  When in the Editor, makes the `$WalkToHelper` child to be rendered in the Canvas showing a [Position2D](https://docs.godotengine.org/en/stable/classes/class_position2d.html) where the `walk_to_point` of this object is.
```

--------------------------------

### Good Commit Message Example

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/conventions/code-versioning.md

A good commit message starts with 'refs #<issue_number>:', followed by a capital letter, and ends with a full stop. It explains the 'why' behind the change.

```text
refs #123: Made the function to flip the character's sprite public.
```

--------------------------------

### Dialog Interface (`D`)

Source: https://context7.com/carenalgas/popochiu/llms.txt

The `D` singleton manages dialog trees, allowing for starting named dialogs, showing inline options, and defining custom dialog resources with branching logic.

```APIDOC
## Dialog Interface (`D`)

### Description
Manages branching dialog trees using `PopochiuDialog` resources and `PopochiuDialogOption` entries. Dialogs can be started by name, shown inline, or defined via custom resources.

### Methods
- `D.ChatWithPopsy.start()`: Starts a predefined dialog named 'ChatWithPopsy'.
- `D.show_inline_dialog(options: Array[String]) -> PopochiuDialogOption`: Displays an ad-hoc list of options and returns the selected one.
- `create_option(id: String, properties: Dictionary) -> PopochiuDialogOption`: Creates a dialog option with specified text and properties.
- `D.say_selected()`: Makes the player character say the text of the selected dialog option.
- `turn_on_options(option_ids: Array[String])`: Makes specified options visible.
- `turn_off_options(option_ids: Array[String])`: Hides specified options.
- `turn_off_forever_options(option_ids: Array[String])`: Hides specified options permanently.
- `stop()`: Ends the current dialog.
- `D.create_gibberish(text: String) -> String`: Creates a string of garbled text.

### Dialog Resource Example (`PopochiuDialog`)
```gdscript
extends PopochiuDialog

func _on_build_options(existing_options: Array[PopochiuDialogOption]) -> Array[PopochiuDialogOption]:
    return [
        create_option("Greeting", { text = "Hi there!" }),
        create_option("AskName",  { text = "What's your name?" }),
        create_option("Bye",      { text = "Goodbye.",  visible = false }),
    ]

func _on_start() -> void:
    await C.Popsy.say("Oh, a visitor!")

# Option handler - method name must match option id in snake_case
func _on_option_greeting(opt: PopochiuDialogOption) -> void:
    await D.say_selected()
    await C.Popsy.say("Hello yourself!")
    turn_on_options(["AskName", "Bye"])
    turn_off_options(["Greeting"])

func _on_option_ask_name(opt: PopochiuDialogOption) -> void:
    await D.say_selected()
    await C.Popsy.say("I'm Popsy! Nice to meet you.")
    turn_off_forever_options(["AskName"])

func _on_option_bye(opt: PopochiuDialogOption) -> void:
    await D.say_selected()
    await C.Popsy.say("Farewell!")
    stop()
```

### Dialog State Persistence Example
```gdscript
extends PopochiuDialog

class Disposition:
    var trust: float = 0.5
    var anger: float = 0.0

var attitude := Disposition.new()

func _on_start() -> void:
    if attitude.trust > 0.7:
        await C.Bartender.say("Good to see you!")

func _on_save() -> Dictionary:
    return { "attitude": { "trust": attitude.trust, "anger": attitude.anger } }

func _on_load(data: Dictionary) -> void:
    var d: Dictionary = data.get("attitude", {})
    attitude.trust = d.get("trust", 0.5)
    attitude.anger = d.get("anger", 0.0)
```
```

--------------------------------

### Initialize Dialog Flow with on_start

Source: https://github.com/carenalgas/popochiu/wiki/Dialog

Use the `on_start` method to execute actions before dialog options are displayed. Always include a yield statement.

```GDScript
func start() -> void:
  yield(E.run([
    C.walk_to_clicked(),
    C.face_clicked(),
    "Player: What's going down, clown?",
    'Clown: Hey, back off, Suit',
    "Clown: I'm practicing",
  ]), 'completed')
  .start()
```

--------------------------------

### Audio Interface (`A`)

Source: https://context7.com/carenalgas/popochiu/llms.txt

The `A` singleton provides access to all audio cues for playback. It supports playing sound effects and music, including positional 2D audio and queued playback.

```APIDOC
## Audio Interface (`A`)

### Description
Provides access to all audio cues by their resource name. `PopochiuAudioCue` objects are played via their `play()` method. Music cues loop; sound effects play once. Positional 2D audio is supported.

### Methods
- `cue.play()`: Plays an audio cue. Can be blocking (waits for completion) or non-blocking.
- `cue.play(blocking: bool, position: Vector2)`: Plays a 2D positional audio cue.
- `E.queue(actions: Array)`: Plays a sequence of audio actions.
- `cue.queue_play()`: Adds an audio cue to a playback queue.
- `cue.queue_play(blocking: bool)`: Adds a blocking audio cue to a playback queue.
- `cue.stop()`: Stops playback of an audio cue.
- `cue.stop(fade_out_duration: float)`: Stops playback with a fade-out effect.
- `A.is_playing_cue(cue_name: String) -> bool`: Checks if a specific audio cue is currently playing.

### Example Usage
```gdscript
# --- Play audio cues -------------------------------------------------------------
await A.sfx_tv_on.play()               # blocking: waits until the cue finishes
A.mx_house.play()                      # non-blocking: music continues in background
A.sfx_door_creak.play(false, global_position)  # 2D positional audio

# --- Audio in queues -------------------------------------------------------------
await E.queue([
    A.mx_toon_town.queue_play(),        # non-blocking: music starts, queue continues
    A.vo_scream.queue_play(true),       # blocking: queue waits for voice to end
    A.sfx_boing.queue_play(),
])

# --- Stop audio ------------------------------------------------------------------
A.mx_house.stop()
A.mx_house.stop(0.5)                   # fade out over 0.5s

# --- Check playback state --------------------------------------------------------
var playing: bool = A.is_playing_cue("mx_house")
```
```

--------------------------------

### Export Engine API References

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/README.md

Run this make command to export all engine API documentation to markdown format. This is necessary for local preview and is automatically triggered before manual production deploys.

```bash
make docs-extract
```

--------------------------------

### Get and Modify AudioStreamPlayer

Source: https://github.com/carenalgas/popochiu/wiki/IAudio

Demonstrates how to get the AudioStreamPlayer for an AudioCue and modify its properties, such as pitch_scale.

```GDScript
# Get the AudioStreamPlayer that plays sfx_locker_open
var asp: AudioStreamPlayer = A.play_no_block('sfx_locker_open')

# Do something with it
asp.pitch_scale = A.semitone_to_pitch(-5.0)
```

--------------------------------

### Deploy Documentation with Make

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/README.md

Use this command to deploy documentation to production. It requires writing permissions on the main repository and creates a local `gh-pages` branch. Avoid manual commits or merging to this branch.

```bash
make docs-deploy
```

--------------------------------

### on_start()

Source: https://github.com/carenalgas/popochiu/wiki/Dialog

Use this method to trigger actions before dialog options are displayed. It requires a yield statement.

```APIDOC
## on_start()

### Description
Use it to trigger something you want to happen before the dialog options appear.
> IMPORTANT: You must always use a yield.

### Method Signature
`on_start() -> void`

### Example
```GDScript
func start() -> void:
  yield(E.run([
    C.walk_to_clicked(),
    C.face_clicked(),
    "Player: What's going down, clown?",
    'Clown: Hey, back off, Suit',
    "Clown: I'm practicing",
  ]), 'completed')
  .start()
```
```

--------------------------------

### Popochiu Installation Confirmation Message

Source: https://github.com/carenalgas/popochiu/wiki/Getting-started

This message appears in the Godot Output panel after successfully installing and enabling the Popochiu plugin. It confirms the plugin is active and ready for use.

```text
[es] Estás usando Popochiu, un plugin para crear juegos point n' click
[en] You're using Popochiu, a plugin for making point n' click games
▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ( o )3(o)/ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
```

--------------------------------

### E.queueable() - Wrapping Godot Methods

Source: https://context7.com/carenalgas/popochiu/llms.txt

Explains how to use E.queueable() to integrate arbitrary Godot methods, including those with parameters and signals, into Popochiu's sequential scripting system.

```APIDOC
## E.queueable()

### Description
`E.queueable()` allows you to wrap any Godot method, including asynchronous ones, so they can be seamlessly integrated into `E.queue()` or `E.cutscene()` instruction arrays. This is useful for calling custom functions or built-in Godot methods that return signals.

### Method
`E.queueable(object: Object, method: StringName, params: Array = [], signal: StringName = "completed") -> PackedScene`

### Parameters
- **object** (Object) - The object containing the method to call.
- **method** (StringName) - The name of the method to call.
- **params** (Array, optional) - An array of parameters to pass to the method. Defaults to an empty array.
- **signal** (StringName, optional) - The name of the signal that indicates the method has completed. Defaults to "completed".

### Request Example
```gdscript
# Example: Wait for an animation to finish
await E.queue([
    E.queueable($AnimationPlayer, "play", ["magic_trick"], "animation_finished"),
])

# Example: Call a custom async method and wait for its completion
func _my_custom_action() -> void:
    # ... custom logic ...
    emit_signal("completed") # Assuming 'completed' signal is defined

await E.queue([
    E.queueable(self, "_my_custom_action", [], "completed"),
])
```

### Response
- **Success Response**: The wrapped method is executed, and the script waits until the specified signal is emitted before continuing the sequence.
```

--------------------------------

### Start Dialogue on Node Click

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/how-to-develop-a-game/script-your-first-dialogue.md

This function is called when a specific node (e.g., a character) is clicked. It initiates the dialogue sequence by calling `C.player.face_clicked()` and then starting the dialogue with `D.PopsyHouseChat.start()`.

```gdscript
func _on_click() -> void:
	await C.player.face_clicked()
	D.PopsyHouseChat.start()
```

--------------------------------

### Sequential Scripting with E.queue() and E.cutscene()

Source: https://context7.com/carenalgas/popochiu/llms.txt

Demonstrates how to use E.queue() for standard sequential actions and E.cutscene() for skippable sequences, including character dialogue, pauses, and custom actions.

```APIDOC
## E.queue() / E.cutscene()

### Description
Use `E.queue()` for standard sequential game logic and `E.cutscene()` for player-skippable sequences. Both methods accept arrays of instructions, which can include character dialogue (as strings or with emotions), system text, pauses, and custom queued actions.

### Method
`await E.queue(instructions: Array)`
`await E.cutscene(instructions: Array)`

### Parameters
- **instructions** (Array) - An array of instructions to be executed sequentially.
  - String: Shorthand for character dialogue or system text.
  - `Character.queue_walk_to(Vector2)`: Queues a character to walk to a position.
  - `Character.queue_face_right()`: Queues a character to face right.
  - `E.queueable(object, method, params, signal)`: Wraps a Godot method for use in the queue.
  - String with dots (`.`, `..`, `...`): Creates pauses of increasing duration.

### Request Example
```gdscript
# Example using E.queue()
await E.queue([
    "Popsy: Where am I?",
    "Popsy(happy): Oh, I remember now!",
    ".", # 0.25s pause
    C.Popsy.queue_walk_to(Vector2(200, 120)),
    "Popsy: Hmm, nothing.",
])

# Example using E.cutscene()
await E.cutscene([
    "Popsy: I can't believe I'm here.",
    C.Popsy.queue_walk_to(Vector2(200, 120)),
    "Popsy: The air feels different.",
])
```

### Response
- **Success Response**: The sequence of instructions is executed. The `await` keyword ensures the game waits for the sequence to complete before proceeding.
```

--------------------------------

### Manage Documentation Service with Docker Compose

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/README.md

Alternative method to manage the documentation service without GNU Make. Use these commands to start, stop, and view logs for the documentation service.

```bash
docker compose up -d
```

```bash
docker compose down
```

```bash
docker compose up
```

--------------------------------

### Basic Character Actions with C Singleton

Source: https://context7.com/carenalgas/popochiu/llms.txt

Demonstrates fundamental character interactions such as walking to clicked objects, facing clicked objects, and having characters speak. Use 'await' for sequential actions in script. Non-blocking NPC speech can be initiated without 'await'.

```gdscript
func _on_click() -> void:
    await C.walk_to_clicked()              # PC walks to last clicked object
    await C.face_clicked()                 # PC faces last clicked object
    await C.player.say("It's locked.")     # PC says a line
    await C.player.say("Hmm...", "sad")    # PC says with emotion
    C.GrumpyOldMan.say("Snort!")           # NPC speaks in background (non-blocking)
```

--------------------------------

### Executing Commands with Popochiu

Source: https://github.com/carenalgas/popochiu/wiki/Popochiu

Shows how to use the Popochiu class to execute sequences of commands, including dialogue and timed actions.

```APIDOC
## Executing Commands with Popochiu

### Description
This section details how to use the Popochiu class to run sequences of commands, such as displaying dialogue or performing timed actions. Commands can be made skippable.

### Methods

* **`E.run(commands: Array)`**: Executes a list of commands sequentially. Commands can be strings for dialogue or other actions.

### Example
```GDScript
E.run(['Player: Hi', '...'])
E.run(['Wait(1.0)', 'Player: How are you?'])
```
```

--------------------------------

### get_active_walkable_area_name

Source: https://github.com/carenalgas/popochiu/wiki/PopochiuRoom

Gets the name of the currently active PopochiuWalkableArea.

```APIDOC
## get_active_walkable_area_name

### Description
Returns the `name` of the active [PopochiuWalkableArea](./PopochiuWalkableArea).

### Method
`get_active_walkable_area_name() -> String`

### Returns
* **String** - The name of the active walkable area.
```

--------------------------------

### get_character_ignore_walkable_areas

Source: https://github.com/carenalgas/popochiu/wiki/ICharacter

Gets the value of the 'ignore_walkable_areas' property for a specified character.

```APIDOC
## get_character_ignore_walkable_areas

### Description
Retrieves the 'ignore_walkable_areas' setting for a given character.

### Method
get_character_ignore_walkable_areas(chr_name: String) -> bool

### Parameters
- **chr_name** (String) - The name of the character.

### Returns
- bool - The current value of the 'ignore_walkable_areas' property.
```

--------------------------------

### Play Transition with PopochiuITransitionLayer

Source: https://context7.com/carenalgas/popochiu/llms.txt

Initiates screen transitions using the T singleton. Supports predefined and custom transitions with various play modes.

```gdscript
# --- Play a transition -----------------------------------------------------------
await T.play_transition("fade", 1.0)                        # fade, 1 second
await T.play_transition("wipe_left", 0.5)                   # wipe left, 0.5s
await T.play_transition("fade", 0.5, T.PLAY_MODE.IN_OUT)    # both enter+leave
await T.play_transition("flash", 0.3, T.PLAY_MODE.PLAY_AND_REVERSE)
```

```gdscript
# --- Manual curtain control (no animation) ----------------------------------------
T.show_curtain()                          # instantly black out screen
T.show_curtain(Color.DARK_BLUE)           # custom color
T.hide_curtain()                          # instantly reveal screen
```

```gdscript
# --- Query available transitions -------------------------------------------------
var all: PackedStringArray        = T.get_all_transitions_list()
var predefined: PackedStringArray = T.get_predefined_transitions_list()
var custom: PackedStringArray     = T.get_custom_transitions_list()
var has_custom: bool              = T.has_custom_transition("horizontal_wipe")
```

```gdscript
# --- Queue variant ---------------------------------------------------------------
E.queue([
    T.queue_play_transition("fade", 0.5),
    "Popsy: Scene change!",
])
```

```gdscript
# --- Room change with explicit transition ----------------------------------------
func _on_click() -> void:
    await T.play_transition("wipe_left", 0.4, T.PLAY_MODE.LEAVE)
    await R.goto_room("Interior", false)   # no built-in transition; we handled it
```

--------------------------------

### Basic Item Interaction

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/the-engine-handbook/working-with-game-state.md

Example of interacting with an inventory item and modifying its state.

```gdscript
func _on_item_used(item: PopochiuInventoryItem) -> void:
	if item == I.Key and I.Key.state.is_rusty:
		await C.player.say("Let me clean this key up...")
		I.Key.state.is_rusty = false
		await C.player.say("Much better!")
```

--------------------------------

### play_now

Source: https://github.com/carenalgas/popochiu/wiki/AudioCueSound

Plays the sound cue immediately. Similar to `play`, it supports waiting for completion and specifying a 2D position.

```APIDOC
## play_now(wait_to_end = false, position_2d = Vector2.ZERO)

### Description
Plays the sound immediately. If `wait_to_end` is `true` the function will pause until the audio clip finishes. You can play the clip from a specific `position_2d` in the scene if the [AudioCue](./AudioCue) has its ***is_2d*** property as `true`. Can be [yield](https://docs.godotengine.org/en/stable/classes/class_%40gdscript.html#class-gdscript-method-yield).

### Parameters
#### Path Parameters
- **wait_to_end** (bool) - Optional - If true, pauses until the audio clip finishes.
- **position_2d** (Vector2) - Optional - The 2D position in the scene to play the sound from.

### Request Example
```GDScript
func on_room_entered() -> void:
  A.sfx_door_close.play_now()
```
```

--------------------------------

### Accessing Points

Source: https://github.com/carenalgas/popochiu/wiki/IRoom

Retrieve a specific point by its name or get a list of all points in the room.

```APIDOC
## get_point(point_name: String) -> Vector2

### Description
Returns the global position of the Position2D node inside $Points which name is equal to point_name. Returns Vector2D.ZERO if the node doesn't exists.

### Method
get_point

### Parameters
#### Path Parameters
- **point_name** (String) - Required - The name of the point to retrieve.

### Response
#### Success Response (Vector2)
- Returns the Vector2 global position of the point.

## get_points() -> Array

### Description
Returns all the Position2D inside the $Points child.

### Method
get_points

### Response
#### Success Response (Array)
- Returns an array of all Position2D nodes in the $Points child.
```

--------------------------------

### Accessing Regions

Source: https://github.com/carenalgas/popochiu/wiki/IRoom

Retrieve a specific region by its name or get a list of all regions in the room.

```APIDOC
## get_region(region_name: String) -> PopochiuRegion

### Description
Returns the PopochiuRegion inside the "regions" group which script_name matches region_name.

### Method
get_region

### Parameters
#### Path Parameters
- **region_name** (String) - Required - The name of the region to retrieve.

### Response
#### Success Response (PopochiuRegion)
- Returns the PopochiuRegion object if found.

## get_regions() -> Array

### Description
Returns all the PopochiuRegions inside the "regions" group.

### Method
get_regions

### Response
#### Success Response (Array)
- Returns an array of all PopochiuRegion objects in the room.
```

--------------------------------

### Accessing Hotspots

Source: https://github.com/carenalgas/popochiu/wiki/IRoom

Retrieve a specific hotspot by its name or get a list of all hotspots in the room.

```APIDOC
## get_hotspot(hotspot_name: String) -> PopochiuHotspot

### Description
Returns the PopochiuHotspot inside the "hotspots" group which script_name matches hotspot_name.

### Method
get_hotspot

### Parameters
#### Path Parameters
- **hotspot_name** (String) - Required - The name of the hotspot to retrieve.

### Response
#### Success Response (PopochiuHotspot)
- Returns the PopochiuHotspot object if found.

## get_hotspots() -> Array

### Description
Returns all the PopochiuHotspots inside the "hotspots" group.

### Method
get_hotspots

### Response
#### Success Response (Array)
- Returns an array of all PopochiuHotspot objects in the room.
```

--------------------------------

### GDScript: Good Line Length Example

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/contributing-to-popochiu/conventions/coding-standards.md

Demonstrates proper line wrapping for GDScript code to maintain readability within the 100-column limit. This is crucial for code that is easily viewable in the Godot editor.

```gdscript
await PopochiuUtils.t.play_transition(
    PopochiuConfig.get_tl_default_room_transition(),
    PopochiuConfig.get_tl_room_transition_duration(),
    PopochiuConfig.get_tl_room_transition_mode_enter()
)
```

--------------------------------

### Accessing Props

Source: https://github.com/carenalgas/popochiu/wiki/IRoom

Retrieve a specific prop by its name or get a list of all props in the room.

```APIDOC
## get_prop(prop_name: String) -> PopochiuProp

### Description
Returns the PopochiuProp inside the "props" group which script_name matches prop_name.

### Method
get_prop

### Parameters
#### Path Parameters
- **prop_name** (String) - Required - The name of the prop to retrieve.

### Response
#### Success Response (PopochiuProp)
- Returns the PopochiuProp object if found.

## get_props() -> Array

### Description
Returns all the PopochiuProps inside the "props" group.

### Method
get_props

### Response
#### Success Response (Array)
- Returns an array of all PopochiuProp objects in the room.
```

--------------------------------

### Character Actions

Source: https://github.com/carenalgas/popochiu/wiki/ICharacter

Examples of common actions that can be performed on characters using the ICharacter interface.

```APIDOC
## Character Actions Examples

### Description
Demonstrates how to make characters perform actions like facing a target, speaking, or moving.

### Methods

*   **face_clicked()**
    *   Description: Makes the player character face the clicked node.
    *   Example: `C.face_clicked()`

*   **character_say(character_name, message)**
    *   Description: Makes a specified character say a message.
    *   Parameters:
        *   `character_name` (String) - The name of the character to speak.
        *   `message` (String) - The message the character will say.
    *   Example: `C.character_say('Glottis', 'Hi Manny!')`

*   **player.face_left()**
    *   Description: Makes the player character face left.
    *   Example: `C.player.face_left()`

*   **[CharacterName].say(message)** (Since version 1.9.0)
    *   Description: Makes a specific character instance say a message.
    *   Parameters:
        *   `message` (String) - The message the character will say.
    *   Example: `C.Glottis.say('Hi Manny!')`

*   **[CharacterName].face_right()** (Since version 1.9.0)
    *   Description: Makes a specific character instance face right.
    *   Example: `C.Manny.face_right()`

*   **[CharacterName].walk_to_hotspot(hotspot_name)** (Since version 1.9.0)
    *   Description: Makes a specific character instance walk to a specified hotspot.
    *   Parameters:
        *   `hotspot_name` (String) - The name of the hotspot to walk to.
    *   Example: `C.Meche.walk_to_hotspot('Window')`
```

--------------------------------

### Navigate Rooms and Play Audio

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/the-engine-handbook/scripting-principles.md

Control game flow by navigating to different rooms using R.goto_room() and play background music using the A singleton.

```gdscript
# Navigate to another room
R.goto_room("Kitchen")

# Play background music
A.mx_kitchen_theme.play()
```

--------------------------------

### Accessing Runtime Room Instance

Source: https://github.com/carenalgas/popochiu/wiki/IRoom

Get the instance of a room accessed via the 'R' shortcut.

```APIDOC
## get_runtime_room(script_name: String) -> PopochiuRoom

### Description
Returns the instance of the room accessed with R. It stores the instance in _room_instances for quicker later access.

### Method
get_runtime_room

### Parameters
#### Path Parameters
- **script_name** (String) - Required - The script name of the room to retrieve.

### Response
#### Success Response (PopochiuRoom)
- Returns the PopochiuRoom instance.
```

--------------------------------

### Handle Dialog Events in Popochiu

Source: https://github.com/carenalgas/popochiu/blob/develop/docs/src/the-engine-handbook/scripting-principles.md

Implement `_on_start` to begin dialog and `_option_selected` to handle player choices. Use `C.Popsy.say`, `C.Bartender.say`, `D.say_selected`, `turn_off_options`, `C.player.say`, and `D.finish_dialog` for various dialog interactions.

```gdscript
extends PopochiuDialog

func _on_start() -> void:
    await C.Popsy.say("Hey there!")
    await C.Bartender.say("What can I get you?")

func _option_selected(opt: PopochiuDialogOption) -> void:
    match opt.id:
        "AskForBeer":
            await D.say_selected()  # Speak the same text that's on the dialog option's label
            await C.Bartender.say("Coming right up!")
            turn_off_options(["AskForBeer"])
        "AskAboutTreasure":
            await C.player.say("Do you know anything about the cursed hidden treasure?")
            await C.Bartender.say("I don't know what you're talking about...")
        "Bye":
            await C.Popsy.say("See you later!")
            D.finish_dialog() # End the dialog when the player says goodbye
```

--------------------------------

### Registering Custom GUI Verbs with E.register_command()

Source: https://context7.com/carenalgas/popochiu/llms.txt

Shows how to add custom verbs (actions) to the game's GUI using E.register_command() and E.register_command_without_id(), allowing for custom player interactions.

```APIDOC
## E.register_command()

### Description
`E.register_command()` and `E.register_command_without_id()` are used to define custom verbs or actions that can be invoked through the game's GUI. This allows you to extend the available interactions beyond the default ones.

### Method
`E.register_command(id: int, name: String, callable: Callable)`
`E.register_command_without_id(name: String, callable: Callable) -> int`

### Parameters
- **id** (int) - A unique integer ID for the command (used with `register_command`).
- **name** (String) - The display name of the verb (e.g., "Smell", "Taste").
- **callable** (Callable) - A callable function or method that will be executed when the verb is invoked.

### Request Example
```gdscript
# In a script that extends Popochiu's command system, e.g., gui_commands.gd
func _init() -> void:
    super()
    E.register_command(100, "Smell", smell)
    var taste_id := E.register_command_without_id("Taste", taste)

func smell() -> void:
    await C.player.say("I don't want to smell that.")

func taste() -> void:
    await C.player.say("Better not.")
```

### Response
- **Success Response**: The custom command is registered and becomes available in the game's GUI. Invoking the command executes the associated callable function.
```

--------------------------------

### play

Source: https://github.com/carenalgas/popochiu/wiki/AudioCueMusic

Plays the music track with optional fade duration and starting position. This method can be yielded.

```APIDOC
## play

### Description
Plays the music track. It can fade for `fade_duration` seconds. You can change the track starting position in seconds with `music_position`. Can be yielded.

### Method
play

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **fade_duration** (float) - Optional - Duration in seconds for fading in the music.
* **music_position** (float) - Optional - Starting position of the track in seconds.

### Request Example
```gdscript
func on_room_transition_finished() -> void:
  E.run([
    A.mx_classic.play(1.5),
    A.sfx_intro.play(),
    "Player: I like this music..."
  ])
```

### Response
#### Success Response (void)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Read-only Runtime Properties

Source: https://context7.com/carenalgas/popochiu/llms.txt

Access read-only properties of a character at runtime to get information about their current state.

```APIDOC
## Read-only Runtime Properties

### Description
Access read-only properties of a character at runtime to get information about their current state.

### Properties
`target_position: Vector2`
`is_talking: bool`
`is_animating: bool`
`is_visible_in_room: bool`
`current_animation: String`
```

--------------------------------

### Setup Room on Entry with GDScript

Source: https://github.com/carenalgas/popochiu/wiki/Room

Use on_room_entered to set up room elements when a player enters. This method is called before the room fades in and is not blocking. It's suitable for positioning the player or conditionally disabling props.

```GDScript
func on_room_entered() -> void:
  C.player.position = get_point('Entrance')
  # The Globals singleton is something you have to create by your own.
  if Globals.game_state.has(GameState.DENTAL_COPY_DELIVERED):
    get_prop('Dentures').disable = true # Hide the prop and don't listen inputs on it
```

--------------------------------

### play_now

Source: https://github.com/carenalgas/popochiu/wiki/AudioCueMusic

Plays the music track immediately with optional fade duration and starting position. This method can be yielded.

```APIDOC
## play_now

### Description
Plays the music track immediately. It can fade for `fade_duration` seconds. You can change the track starting position in seconds with `music_position`. Can be yielded.

### Method
play_now

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **fade_duration** (float) - Optional - Duration in seconds for fading in the music.
* **music_position** (float) - Optional - Starting position of the track in seconds.

### Request Example
```gdscript
func on_interact() -> void:
  A.mx_radio_emotion.play_now()

  E.run([
    '...',
    "Player: Wait...",
    "Player: That radio station",
    '...',
    "Player: Is it Fernando Martínez?"
  ])
```

### Response
#### Success Response (void)
This method does not return a value.

#### Response Example
None
```