Quest System

The quests module provides quest tracking, objectives, and quest management functionality.

Quest Classes

Quest system for managing objectives and storylines.

This module provides a flexible quest system for tracking player progress, objectives, and rewards.

class barebones_rpg.quests.quest.QuestStatus(value)

Bases: Enum

Quest status states.

NOT_STARTED = 1

ACTIVE = 2

COMPLETED = 3

FAILED = 4

class barebones_rpg.quests.quest.ObjectiveType(value)

Bases: Enum

Types of quest objectives.

KILL_ENEMY = 1

COLLECT_ITEM = 2

TALK_TO_NPC = 3

REACH_LOCATION = 4

CUSTOM = 5

class barebones_rpg.quests.quest.QuestObjective(**data)

Bases: BaseModel

A single objective within a quest.

Example

>>> objective = QuestObjective(
...     description="Defeat 5 goblins",
...     objective_type=ObjectiveType.KILL_ENEMY,
...     target="Goblin",
...     target_count=5
... )

id: str

description: str

objective_type: ObjectiveType

current_count: int

target_count: int

completed: bool

target: Optional[str]

condition: Optional[Callable]

on_progress: Optional[Callable]

on_complete: 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].

increment(amount=1)

Increment progress on this objective.

Parameters:

amount (int) – Amount to increment by

Return type:

bool

Returns:

True if objective was just completed

complete()

Mark objective as completed.

Return type:

None

is_completed()

Check if objective is completed.

Return type:

bool

Returns:

True if completed

get_progress_text()

Get progress text for this objective.

Return type:

str

Returns:

Progress string like “3/5”

to_dict()

Convert objective to dictionary for saving.

Return type:

Dict[str, Any]

Returns:

Dictionary representation

classmethod from_dict(data)

Create objective from dictionary.

Parameters:

data (Dict[str, Any]) – Dictionary representation

Return type:

QuestObjective

Returns:

QuestObjective instance

class barebones_rpg.quests.quest.Quest(*, id=<factory>, name, description='', status=QuestStatus.NOT_STARTED, objectives=<factory>, exp_reward=0, gold_reward=0, item_rewards=<factory>, giver_npc_id=None, required_level=1, required_quests=<factory>, on_start=None, on_complete=None, on_fail=None, metadata=<factory>)

Bases: BaseModel

A quest with objectives and rewards.

Quests automatically register themselves with the QuestManager singleton when created.

Example

>>> quest = Quest(
...     name="Save the Village",
...     description="The village is under attack by goblins!"
... )  # Automatically registers to QuestManager
>>> quest.add_objective(QuestObjective(
...     description="Defeat goblin chief",
...     objective_type=ObjectiveType.KILL_ENEMY,
...     target="Goblin Chief"
... ))

id: str

name: str

description: str

status: QuestStatus

objectives: List[QuestObjective]

exp_reward: int

gold_reward: int

item_rewards: List[str]

giver_npc_id: Optional[str]

required_level: int

required_quests: List[str]

on_start: Optional[Callable]

on_complete: Optional[Callable]

on_fail: 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].

__init__(**data)

Initialize quest.

Note: Quests are not automatically registered to QuestManager. Call QuestManager().add_quest(quest) explicitly if you want to use the quest manager.

add_objective(objective)

Add an objective to the quest.

Parameters:

objective (QuestObjective) – Objective to add

Return type:

bool

Returns:

True if objective was added successfully

start(events=None, location=None, world=None)

Start the quest.

Parameters:

• events (Optional[EventManager]) – Event manager for publishing events

• location (Optional[Any]) – Optional location to check for retroactive progress (e.g., checking if entities still exist)

• world (Optional[Any]) – Optional world to check for retroactive progress across all locations

Return type:

None

complete(events=None)

Complete the quest.

Parameters:

events (Optional[EventManager]) – Event manager for publishing events

Return type:

None

fail(events=None)

Fail the quest.

Parameters:

events (Optional[EventManager]) – Event manager for publishing events

Return type:

None

check_completion(events=None)

Check if all objectives are completed.

Parameters:

events (Optional[EventManager]) – Event manager for publishing events

Return type:

bool

Returns:

True if quest should be completed

is_active()

Check if quest is active.

Return type:

bool

Returns:

True if quest is active

is_completed()

Check if quest is completed.

Return type:

bool

Returns:

True if quest is completed

is_failed()

Check if quest is failed.

Return type:

bool

Returns:

True if quest is failed

get_progress_percentage()

Get overall progress percentage.

Return type:

float

Returns:

Progress from 0.0 to 1.0

check_retroactive_progress(events=None, location=None, world=None)

Check for retroactive progress on objectives.

This method checks if objectives can be completed based on current world state, even if the required actions happened before the quest was started.

For example, if a quest requires killing a unique enemy (tracked by ID) and that enemy is already dead when the quest starts, this will mark the objective complete.

Objectives with ID-based targets (UUIDs) are considered unique and will be checked retroactively. Name-based targets are considered generic and won’t be checked.

Parameters:

• events (Optional[EventManager]) – Event manager for publishing events

• location (Optional[Any]) – Location to check for entity existence (for single-location quests)

• world (Optional[Any]) – World to check for entity existence (for multi-location quests)

Return type:

None

to_dict()

Convert quest to dictionary for saving.

Return type:

Dict[str, Any]

Returns:

Dictionary representation

classmethod from_dict(data, auto_register=False)

Create quest from dictionary.

Parameters:

• data (Dict[str, Any]) – Dictionary representation

• auto_register (bool) – If True, register to QuestManager (default: False to avoid duplicates)

Return type:

Quest

Returns:

Quest instance

class barebones_rpg.quests.quest.QuestManager(*args, **kwargs)

Bases: object

Manages all quests in the game (Singleton).

This is a framework-managed singleton. Access by instantiating directly: QuestManager()

Example

>>> quest = Quest(name="Tutorial Quest")  # Auto-registers
>>> QuestManager().start_quest(quest.id)
>>> # Or via game instance:
>>> game.quests.start_quest(quest.id)

__init__()

Initialize the quest manager.

classmethod reset()

Reset manager to initial state (for testing).

Clears the singleton instance, causing the next access to create a fresh instance with default initialization.

Return type:

None

add_quest(quest)

Add a quest to the manager.

Automatically registers any callbacks (on_start, on_complete, on_fail) to the CallbackRegistry for serialization support.

Parameters:

quest (Quest) – Quest to add

Return type:

bool

Returns:

True if quest was added successfully

get_quest(quest_id)

Get a quest by ID.

Parameters:

quest_id (str) – Quest ID

Return type:

Optional[Quest]

Returns:

Quest or None

get_quest_by_name(name)

Get a quest by name.

Parameters:

name (str) – Quest name

Return type:

Optional[Quest]

Returns:

Quest or None

start_quest(quest_id, events=None)

Start a quest.

Parameters:

• quest_id (str) – Quest ID to start

• events (Optional[EventManager]) – Event manager

Return type:

bool

Returns:

True if quest was started

complete_quest(quest_id, events=None)

Complete a quest.

Parameters:

• quest_id (str) – Quest ID

• events (Optional[EventManager]) – Event manager

Return type:

bool

Returns:

True if quest was completed

get_active_quests()

Get all active quests.

Return type:

List[Quest]

Returns:

List of active quests

get_completed_quests()

Get all completed quests.

Return type:

List[Quest]

Returns:

List of completed quests

update_objective(quest_id, objective_type, target, amount=1, events=None)

Update progress on matching objectives.

This is a helper method for common objective updates like killing enemies or collecting items.

Parameters:

• quest_id (str) – Quest ID

• objective_type (ObjectiveType) – Type of objective

• target (str) – Target identifier

• amount (int) – Amount to increment

• events (Optional[EventManager]) – Event manager

Return type:

bool

Returns:

True if any objectives were updated

save()

Save quest manager state.

Return type:

Dict[str, Any]

Returns:

Dictionary representation including quest state

load(data)

Load quest manager state.

Parameters:

data (Dict[str, Any]) – Saved data containing quest tracking

Return type:

None