storyforge package

Submodules

storyforge.menu module

class storyforge.menu.StoryMenu(story, ui)

Bases: object

Class responsible for displaying and managing the game menu.

Attributes:

• story (Story): The game’s story object.

• ui (PygameUI): The game’s user interface object.

Methods:

• show_menu(): Displays the game’s main menu on the screen.

• continue_story(): Continues the story from a saved state or starts a new story, as chosen by the player.

• start_new_story(): Starts a new story, creating an empty state.

continue_story() → None

Continue the story from a saved state or start a new story, as chosen by the player.

Return:

None

show_menu() → None

Displays the game’s main menu on the screen.

Return:

None

start_new_story() → None

Starts a new story, creating an empty state.

Return:

None

storyforge.story module

class storyforge.story.Story(start_scene)

Bases: object

Class responsible for manipulating the game’s story.

Attributes:

• scenes (Dict[str, Dict[str, Union[str, List[Tuple[str, str]]]]]): A dictionary that contains the game’s scenes.

• choices (Dict[Tuple[str, str], str]): A dictionary that maps choices made by the player for upcoming scenes.

• current_scene (str): The name of the current scene.

• character (Dict[str, Optional[str]]): A dictionary that contains information about the character, such as name.

• default_player_name (Dict[str, str]): A dictionary containing the player’s default name.

Methods:

• save_state(): Saves the current state of the game in a JSON file.

• load_state() -> bool: Loads the previously saved state, if it exists.

• create_empty_state(): Creates an empty state to start the game.

• set_character_name(name: str): Sets the character’s name.

• add_scene(name: str, text: str, image: Optional[str] = None, character_image: Optional[str] = None, character_speech: Optional[str] = None):

  Adds a new scene to the story.

• add_choice(from_scene: str, text: str, to_scene: str): Adds a choice that the player can make in a given scene.

• has_choices() -> bool: Checks if there are choices available in the current scene.

• validate_story(): Validates the consistency of the story, looking for inaccessible scenes.

• run(): Runs the main game loop, showing the scenes, available options and processing the player’s choices.

• show_scene(): Displays the current game scene to standard output.

• show_choices(): Displays the options available to the player on standard output.

• make_choice(player_choice: str): Processes the player’s choice and advances to the next corresponding scene.

add_choice(from_scene: str, text: str, to_scene: str) → None

Adds a choice the player can make in a given scene.

Parameters:

• from_scene (str): The name of the source scene of the choice.

• text (str): The text of the choice.

• to_scene (str): The name of the scene the choice leads to.

Return:

None

add_scene(name: str, text: str, image: str | None = None, character_image: str | None = None, character_speech: str | None = None) → None

Adds a new scene to the story.

Parameters:

• name (str): The name of the scene.

• text (str): The text of the scene.

• image (Optional[str]): The name of the scene’s image file.

• character_image (Optional[str]): The name of the character image file in the scene.

• character_speech (Optional[str]): The character’s speech in the scene.

Return:

None

create_empty_state() → None

Creates an empty state to start the game.

Return:

None

has_choices() → bool

Checks whether there are choices available in the current scene.

Return:

bool: True if choices are available, False otherwise.

load_state() → bool

Loads the previously saved state, if it exists.

Return:

bool: True if the state was loaded successfully, False otherwise.

make_choice(player_choice: str) → None

Processes the player’s choice and advances to the next corresponding scene.

Parameters

• player_choice (str): The choice made by the player.

Return:

None

run() → None

Runs the main game loop, showing the scenes, available options and processing the player’s choices.

Return:

None

save_state() → None

Saves the current game state to a JSON file.

Return:

None

save_state_to_json(filename: str) → None

Saves the current game state to a JSON file.

Parameters:

• filename (str): The name of the JSON file to save the state.

Return:

None

set_character_name(name: str) → None

Sets the character’s name.

Parameters:

• name (str): The character’s name.

Return:

None

show_choices() → None

Displays the options available to the player on standard output.

Return:

None

show_scene() → None

Displays the current game scene to standard output.

Return:

None

validate_story() → None

Validates the consistency of the story by looking for inaccessible scenes.

Return:

None

storyforge.ui module

class storyforge.ui.PygameUI(story: Story)

Bases: object

Class to manage game UI using Pygame.

Attributes:

• story (Story): The game’s story object.

Public Methods:

• __init__(story: Story): Initializes the game’s user interface.

• show_initial_menu(): Displays the game’s initial menu.

• get_player_name(default_name: str) -> str: Gets the player’s name when running the game.

• render_text_with_background(text: str, height: int, bottom_aligned: bool = False, opacity: int = 128, speech_text: Optional[str] = None) -> pygame.Rect: Renders text with background.

• render_input_screen(input_string: str, default_name: str) -> None: Renders the input screen for the player name.

• show_input_screen(default_name: str) -> None: Displays the input screen for the player name.

• render_choice(choice_text: str, x: int, y: int) -> Tuple[pygame.Rect, int]: Renders a choice on the screen.

• render_text(text: str, x: int, y: int) -> pygame.Rect: Renders text on the screen.

• show_scene() -> None: Displays the current game scene on the screen.

• wait_for_click() -> None: Waits for a mouse click on the screen.

• show_choices(hover_choice: Optional[int] = None) -> Optional[int]: Displays the choice options on the screen.

• handle_events() -> None: Handles game events.

• run() -> None: Starts running the game.

• check_for_click() -> bool: Checks whether a click has occurred on the screen.

• check_text_and_speech_displayed() -> bool: Checks whether the scene text and the character’s speech (if any) have already been displayed.

• process_click(pos: Tuple[int, int]) -> None: Processes the mouse click on the screen.

• save_and_quit() -> None: Saves the current state and closes the game window.

check_for_click() → bool

Checks whether a click has occurred on the screen.

Return:

bool: True if a click occurred, False otherwise.

check_text_and_speech_displayed() → bool

Checks whether the scene text and character speech (if any) have already been displayed.

Return:

bool: True if the scene text and character speech have already been displayed, False otherwise.

get_player_name(default_name: str) → str

Gets the player’s name when running the game.

Parameters:

• default_name (str): The default name of the player.

Return:

str: The player’s name.

handle_events() → None

Handles game events.

Return:

None

process_click(pos: Tuple[int, int]) → None

Processes the mouse click on the screen.

Parameters:

• pos (Tuple[int, int]): The (x, y) coordinates of the mouse click.

Return:

None

render_choice(choice_text: str, x: int, y: int) → Tuple[Rect, int]

Renders a choice on the screen.

Parameters:

• choice_text (str): The text of the choice.

• x (int): The x coordinate of the center of the pick.

• y (int): The y-coordinate of the center of the pick.

Return:

Tuple[pygame.Rect, int]: A tuple containing the rectangle of the choice and the vertical space between choices.

render_input_screen(input_string: str, default_name: str) → None

Renders the input screen for the player name.

Parameters:

• input_string (str): The currently entered player name.

• default_name (str): The default name of the player.

Return:

None

render_text(text: str, x: int, y: int) → Rect

Renders text on the screen.

Parameters:

• text (str): The text to be rendered.

• x (int): The x-coordinate of the center of the text.

• y (int): The y-coordinate of the center of the text.

Return:

pygame.Rect: The rectangle surrounding the rendered text.

render_text_with_background(text: str, height: int, bottom_aligned: bool = False, opacity: int = 128, speech_text: str | None = None) → Rect

Renders text with background on the screen.

Parameters:

• text (str): The text to be rendered.

• height (int): The height of the background rectangle.

• bottom_aligned (bool): If True, the text is aligned at the bottom of the rectangle.

• opacity (int): The opacity of the background.

• speech_text (Optional[str]): The text of the character’s speech.

Return:

pygame.Rect: The rectangle surrounding the rendered text.

run(max_iterations: int = None) → None

Starts running the game.

Return:

None

save_and_quit() → None

Saves the current state and closes the game window.

Returns:

None

show_choices(hover_choice: int | None = None) → int | None

Displays choice options on the screen.

Parameters:

• hover_choice (Optional[int]): The number of the choice being highlighted by the mouse.

Return:

Optional[int]: The number of the choice highlighted by the mouse.

show_initial_menu() → None

Displays the game’s home menu on the screen.

Return:

None

show_input_screen(default_name: str) → None

Displays the input screen for the player name.

Parameters:

• default_name (str): The default name of the player.

Return:

None

show_scene() → None

Displays the current game scene on the screen.

Return:

None

wait_for_click() → None

Wait for a mouse click on the screen.

Returns:

None

welcome() → None

Displays the welcome message in terminal.

Return:

None

Module contents