Dialog System¶

The dialog module provides conversation trees, dialog nodes, and session management for NPC interactions.

Dialog Trees¶

Dialog system for conversations and choice trees.

This module provides a flexible dialog system for NPC conversations, branching narratives, and interactive storytelling.

class barebones_rpg.dialog.dialog.DialogConditions[source]¶

Bases: object

Helper class with common dialog condition factories.

This provides reusable condition functions for common dialog scenarios, reducing boilerplate in dialog tree creation.

Example

>>> from barebones_rpg.quests.quest import QuestStatus
>>> quest_started = DialogConditions.quest_status(quest, QuestStatus.ACTIVE)
>>> enemy_dead = DialogConditions.entity_not_in_location(location, "Goblin")

static quest_status(quest, status)[source]¶

Create a condition that checks if a quest has a specific status.

Parameters:

quest – Quest object to check
status – QuestStatus to check for

Return type:

Callable

Returns:

Condition function

static quest_not_started(quest)[source]¶

Create a condition that checks if a quest hasn’t been started.

Parameters:: quest – Quest object to check
Return type:: Callable
Returns:: Condition function

static quest_active(quest)[source]¶

Create a condition that checks if a quest is active.

Parameters:: quest – Quest object to check
Return type:: Callable
Returns:: Condition function

static quest_completed(quest)[source]¶

Create a condition that checks if a quest is completed.

Parameters:: quest – Quest object to check
Return type:: Callable
Returns:: Condition function

static entity_in_location(location, entity_name)[source]¶

Create a condition that checks if an entity exists in a location.

Parameters:

location – Location object to check
entity_name (str) – Name of entity to look for

Return type:

Callable

Returns:

Condition function

static entity_not_in_location(location, entity_name)[source]¶

Create a condition that checks if an entity does NOT exist in a location.

Parameters:

location – Location object to check
entity_name (str) – Name of entity to look for

Return type:

Callable

Returns:

Condition function

static all_conditions(*conditions)[source]¶

Create a condition that requires all sub-conditions to be true.

Parameters:: *conditions (Callable) – Variable number of condition functions
Return type:: Callable
Returns:: Combined condition function

static any_condition(*conditions)[source]¶

Create a condition that requires any sub-condition to be true.

Parameters:: *conditions (Callable) – Variable number of condition functions
Return type:: Callable
Returns:: Combined condition function

static not_condition(condition_func)[source]¶

Create a condition that inverts another condition.

Parameters:: condition_func (Callable) – Condition to invert
Return type:: Callable
Returns:: Inverted condition function

static always()[source]¶

Create a condition that is always true.

Useful as a fallback or when you want an option always available.

Return type:: Callable
Returns:: Always-true condition function

class barebones_rpg.dialog.dialog.DialogChoice(**data)[source]¶

Bases: BaseModel

A choice in a dialog tree.

Example

>>> choice = DialogChoice(
...     text="Tell me about the quest",
...     next_node_id="quest_info"
... )

>>> # With quest integration
>>> choice = DialogChoice(
...     text="I'll help you!",
...     next_node_id="accepted",
...     quest_to_start=my_quest
... )

text: str¶

next_node_id: Optional[str]¶

condition: Optional[Callable]¶

on_select: Optional[Callable]¶

quest_to_start: Optional[Any]¶

quest_to_update: Optional[tuple]¶

metadata: Dict[str, Any]¶

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

is_available(context)[source]¶

Check if this choice is available.

Parameters:: context (Dict[str, Any]) – Game context for evaluating conditions
Return type:: bool
Returns:: True if choice can be selected

select(context)[source]¶

Execute the choice’s on_select callback and handle quest actions.

Parameters:: context (Dict[str, Any]) – Game context
Return type:: Any
Returns:: Result of callback (if any)

class barebones_rpg.dialog.dialog.DialogNode(**data)[source]¶

Bases: BaseModel

A node in a dialog tree.

Each node contains text, optional speaker, and choices for the player.

Example

>>> node = DialogNode(
...     id="greeting",
...     speaker="Village Elder",
...     text="Welcome, traveler. How can I help you?",
...     choices=[
...         DialogChoice(text="Tell me about the village", next_node_id="village_info"),
...         DialogChoice(text="Goodbye", next_node_id=None)
...     ]
... )

id: str¶

speaker: Optional[str]¶

text: str¶

choices: List[DialogChoice]¶

on_enter: Optional[Callable]¶

on_exit: Optional[Callable]¶

metadata: Dict[str, Any]¶

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

get_available_choices(context)[source]¶

Get all available choices based on current context.

Parameters:: context (Dict[str, Any]) – Game context for evaluating conditions
Return type:: List[DialogChoice]
Returns:: List of available choices

enter(context)[source]¶

Call the on_enter callback.

Parameters:: context (Dict[str, Any]) – Game context
Return type:: Any
Returns:: Result of callback (if any)

exit(context)[source]¶

Call the on_exit callback.

Parameters:: context (Dict[str, Any]) – Game context
Return type:: Any
Returns:: Result of callback (if any)

class barebones_rpg.dialog.dialog.DialogTree(**data)[source]¶

Bases: BaseModel

A complete dialog tree.

Contains all nodes and manages navigation through the dialog.

Example

>>> tree = DialogTree(name="Village Elder Dialog")
>>> tree.add_node(DialogNode(
...     id="start",
...     speaker="Elder",
...     text="Hello!",
...     choices=[DialogChoice(text="Hi", next_node_id="greeting")]
... ))
>>> tree.set_start_node("start")

id: str¶

name: str¶

nodes: Dict[str, DialogNode]¶

start_node_id: Optional[str]¶

metadata: Dict[str, Any]¶

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

add_node(node)[source]¶

Add a node to the tree.

Parameters:: node (DialogNode) – Node to add
Return type:: bool
Returns:: True if node was added successfully

get_node(node_id)[source]¶

Get a node by ID.

Parameters:: node_id (str) – ID of node to retrieve
Return type:: Optional[DialogNode]
Returns:: Dialog node or None if not found

get_start_node()[source]¶

Get the starting node.

Return type:: Optional[DialogNode]
Returns:: Start node or None if not set

set_start_node(node_id)[source]¶

Set the starting node.

Parameters:: node_id (str) – ID of the start node
Return type:: bool
Returns:: True if node exists and was set as start node

validate_tree()[source]¶

Validate the dialog tree.

Return type:: List[str]
Returns:: List of validation errors (empty if valid)

class barebones_rpg.dialog.dialog.DialogSession(dialog_tree, game=None, context=None)[source]¶

Bases: object

Active dialog session.

Manages the state of an ongoing conversation. The framework automatically populates the context with game systems when a game instance is provided.

Example

>>> tree = DialogTree(name="Test")
>>> # ... add nodes ...
>>> # Simple - just pass game, framework handles context
>>> session = DialogSession(tree, game=game)
>>> # Or add custom context
>>> session = DialogSession(tree, game=game, context={"npc_mood": "happy"})

__init__(dialog_tree, game=None, context=None)[source]¶

Initialize a dialog session.

Parameters:

dialog_tree (DialogTree) – The dialog tree to run
game (Optional[Any]) – Game instance (framework auto-populates context from it)
context (Optional[Dict[str, Any]]) – Additional custom context data

start()[source]¶

Start the dialog session.

Return type:: Optional[DialogNode]
Returns:: The starting dialog node

get_current_node()[source]¶

Get the current dialog node.

Return type:: Optional[DialogNode]
Returns:: Current node or None

get_available_choices()[source]¶

Get available choices at current node.

Return type:: List[DialogChoice]
Returns:: List of available choices

make_choice(choice_index)[source]¶

Make a choice and navigate to next node.

Parameters:: choice_index (int) – Index of the choice to make
Return type:: Optional[DialogNode]
Returns:: Next dialog node or None if dialog ended

end()[source]¶

End the dialog session.

Return type:: None

barebones_rpg.dialog.dialog.create_linear_dialog(name, conversations, speaker=None)[source]¶

Create a simple linear dialog (no branching).

Parameters:

name (str) – Dialog name
conversations (List[Tuple[str, str]]) – List of (text, speaker) tuples
speaker (Optional[str]) – Default speaker name

Return type:

DialogTree

Returns:

Linear dialog tree

Dialog Renderer¶

Dialog UI rendering utilities.

This module provides rendering utilities for dialog trees, including dialog boxes, speaker names, text with word wrapping, and choice buttons.

class barebones_rpg.dialog.dialog_renderer.DialogRenderer(renderer, screen_width, screen_height)[source]¶

Bases: object

Renderer for dialog UI.

This class handles rendering of: - Dialog boxes with borders - Speaker names - Dialog text with word wrapping - Choice buttons with hover effects - Click handling for choices

Parameters:

renderer (Renderer) – The base renderer to use
screen_width (int) – Width of the screen in pixels
screen_height (int) – Height of the screen in pixels

__init__(renderer, screen_width, screen_height)[source]¶

Initialize the dialog renderer.

Parameters:

renderer (Renderer) – The base renderer to use
screen_width (int) – Width of the screen in pixels
screen_height (int) – Height of the screen in pixels

wrap_text(text, max_width, char_width=8)[source]¶

Wrap text to fit within a maximum width.

Parameters:

text (str) – Text to wrap
max_width (int) – Maximum width in pixels
char_width (int) – Approximate character width in pixels

Return type:

List[str]

Returns:

List of wrapped lines

get_dialog_box_bounds()[source]¶

Get the bounds of the dialog box.

Return type:: Tuple[int, int, int, int]
Returns:: Tuple of (x, y, width, height)

get_choice_bounds(choice_index, num_choices)[source]¶

Get the bounds of a choice button.

Parameters:

choice_index (int) – Index of the choice
num_choices (int) – Total number of choices

Return type:

Tuple[int, int, int, int]

Returns:

Tuple of (x, y, width, height)

is_mouse_over_choice(mouse_pos, choice_index, num_choices)[source]¶

Check if mouse is over a choice button.

Parameters:

mouse_pos (Tuple[int, int]) – Mouse position (x, y)
choice_index (int) – Index of the choice
num_choices (int) – Total number of choices

Return type:

bool

Returns:

True if mouse is over the choice

handle_click(event, session)[source]¶

Handle a mouse click on the dialog.

Parameters:

event (Event) – Pygame mouse button event
session (DialogSession) – The active dialog session

Return type:

bool

Returns:

True if a choice was selected

render_dialog_box()[source]¶: Render the dialog box background and border.

render_speaker(speaker_name)[source]¶

Render the speaker name.

Parameters:: speaker_name (str) – Name of the speaker

render_text(text)[source]¶

Render the dialog text with word wrapping.

Parameters:: text (str) – The text to render

render_choices(session)[source]¶

Render the dialog choices as buttons.

Parameters:: session (DialogSession) – The active dialog session

render_session(session)[source]¶

Render a complete dialog session.

This is a convenience method that renders all dialog components.

Parameters:: session (DialogSession) – The dialog session to render

render_with_overlay(session, overlay_alpha=180)[source]¶

Render dialog with a semi-transparent overlay over the world.

This creates a darkened background effect when dialog is active.

Parameters:

session (DialogSession) – The dialog session to render
overlay_alpha (int) – Alpha value for the overlay (0-255)

configure(dialog_box_height=None, dialog_box_margin=None, choice_height=None, choice_width=None, bg_color=None, speaker_color=None, speaker_font_size=None, text_font_size=None, choice_font_size=None, choice_y_start_offset=None, text_y_offset=None, text_line_spacing=None)[source]¶

Configure dialog renderer appearance.

Parameters:

dialog_box_height (Optional[int]) – Height of the dialog box
dialog_box_margin (Optional[int]) – Margin from screen edges
choice_height (Optional[int]) – Height of choice buttons
choice_width (Optional[int]) – Width of choice buttons
bg_color (Optional[Color]) – Background color
speaker_color (Optional[Color]) – Speaker name color