version 1.0.4

Welcome to "Yolkaris Odyssey," my first attempt at coding a game. As a developer with a passion for learning and trying new things, I ventured into the realm of game development without a background in gaming. This project is a text-based adventure game built with Python, inspired by the classic games that have intrigued and entertained us over the years.

In "Yolkaris Odyssey," players embark on an epic journey through fantastical worlds, encountering diverse characters, and making decisions that shape the course of their adventure. I designed this game to challenge myself and to bring a simple yet captivating story to life through code. Join me in exploring the universe of Yolkaris, where every choice you make carves a path through the mysteries and wonders of this text-based adventure.

Deployed Yolkaris Odyssey Game Link

• Table of Contents
• Project Goals
• Player Goals
• User Stories
• Game flowchart
• Files and Folder Structure
• Technology used
• Deployment and development
  • Cloning the project
  • Running the game in terminal
  • Deploying the Game to Heroku
  • Running the game with Docker
    • Installing Docker
    • Building and Running the Docker Container
• How to play
  • Game Commands
• Features
• Testing
  • Manual Testing
• Issues and Resolutions
  • Unresolved Issues
• Enhancements and Future Features
• Credits
  • Acknowledgements

Back to Top

The primary goal of creating "Yolkaris Odyssey" was to delve into the world of game development, leveraging my programming skills to build something fun, interactive, and engaging. I aimed to:

• Explore Game Mechanics: Learn the ins and outs of game design and development by creating a game from scratch.
• Challenge My Coding Skills: Push the boundaries of my Python knowledge by applying it to a completely new domain.
• Engage Players with Storytelling: Craft a compelling narrative that players can influence through their decisions, making each playthrough unique.

Back to Top

"Yolkaris Odyssey" is designed with the player's enjoyment and engagement at the forefront. Players are encouraged to:

• Embark on an Adventure: Dive into the rich, text-based world of Yolkaris, filled with lore, mystery, and intrigue.
• Make Meaningful Decisions: Each choice you make affects the story's outcome. Shape your destiny in the universe of Yolkaris. Solve Puzzles: Engage with puzzles and challenges that test your wit and reward your ingenuity.
• Discover Hidden Secrets: Explore thoroughly to uncover secrets and hidden storylines that enrich the game world. This game is for anyone who loves the idea of embarking on an interstellar journey, enjoys narrative-driven experiences, and appreciates the charm of text-based adventures. Whether you're a seasoned gamer or new to this genre, "Yolkaris Odyssey" offers a welcoming and intriguing experience.

Back to Top

• As a player, I want to choose the type of game (quick adventure or full exploration) to select a gaming experience that matches my available time and interest level.
• As a player, I wish to move in a non-linear fashion, exploring the game world freely and making decisions on where to go next, ensuring my adventure feels personalized and unique.
• As a player, I'd like to interact with objects and characters in the game, allowing me to engage with the story more deeply and influence the outcome based on my choices.
• As a player, I need clear instructions and help options, so I can understand gameplay mechanics and what actions are available to me, ensuring a smooth and enjoyable experience.
• As a player, I desire a compelling narrative and well-developed characters, making the game immersive and emotionally engaging.
• As a player, I would like to engage in battles with enemies, having the option to either continue fighting or escape if the fight turns unfavorable, providing me with strategic choices that impact the game's outcome.
• As a player, I am interested in utilizing a variety of weapons and armor throughout the game, allowing me to customize my combat strategy and adapt to different types of enemies.
• As a player, I want a method to restore my character's health, such as using potions or finding rest areas, enabling me to recover from battles and continue my adventure.
• As a user, I want to explore various locations within the game, each with its own unique challenges and story elements, providing a rich and diverse world to discover.

Back to Top

Creating the flowchart for "Yolkaris Odyssey" helped me structure the game's complex elements, including combat, story progression, and exploration. I used draw.io for its user-friendly interface and comprehensive features, allowing me to map out the game from start to finish without restrictions. This detailed flowchart includes all player commands, the combat system, story interactions, and mechanics for traveling between locations. It was a crucial step in developing a clear, navigable game experience, ensuring players have a roadmap through their adventure in "Yolkaris Odyssey."

Game Flowchart - PDF

Back to Top

During the development process, I initially had all the game logic written in a single file called run.py. However, upon receiving advice from my mentor, who recommended better organization, I decided to refactor the game. This led to the creation of a game folder, where I moved relevant classes into separate files, improving maintainability and readability.

• characters.py: Contains character classes such as Character, Player, Enemy, and Neutral.
• items.py: Includes the main Item class and its subclasses such as Weapon, Armour, and Potions.
• locations.py: Houses the main Location class and its related Area classes, defining various game environments.
• interactions.py: Contains classes related to game interactions, including Interaction and Combat.
• game_manager.py: Features a singleton class responsible for managing the game. It facilitates game initialization, as well as the ability to restart the game when needed.

In addition to the game folder, I also have a utils folder that includes:

• text_utils.py: Contains helper functions for manipulating text and aiding in game display and interaction.

This organizational structure has greatly improved the manageability of the game code and enhanced its readability.

Back to Top

• HTML5 and CSS: Used to customize the Code Institute template.
• Python: The primary programming language used to develop this game.
• Python Packages:
  • art: Used for ASCII art generation.
  • colorama: Used for colored text output in the terminal.
• Git and GitHub: Used Git for version control, allowing for collaboration and tracking of code changes on GitHub.
• Heroku: Deployed the game on Heroku's server, making it accessible to anyone with an internet connection.
• Docker: Leveraged Docker for local testing of the game without the need to deploy to Heroku.
• draw.io: Used to create the game flowchart, aiding in visualizing the game's structure and logic.
• Midjourney: Used to create the main game image, which was also utilized as the background.
• ChatGPT: Utilized to enhance the game's storylines and narratives.
• VSCode: Mainly used as the primary text editor for writing the game code.
• PyCharm: Utilized for debugging code in real-time with breakpoints, as well as identifying warnings and errors.

Back to Top

1. Install Git: If you haven't already installed Git on your computer, download and install it from the Git website. Follow the installation instructions for your operating system.
2. Create project folder mkdir yolkaris-odyssey
3. Change to the project directory cd yolkaris-odyssey
4. Clone the repository git clone https://github.com/patrickhladun/yolkaris-odyssey.git .

Back to Top

1. Open your terminal and change directory to the cloned project folder.
2. Install the required packages with pip install -r requirements.txt
3. Run the game python run.py

Back to Top

1. Login or Create Heroku Account: If you don't have one, create a Heroku account. Otherwise, log in to your existing account.
2. Create New App: From the Heroku dashboard, click the "New" button in the top right corner. Select "Create new app" from the drop-down menu.
3. Name and Region Selection: Choose a unique name and select the region.
4. Configure Environment Variables: Navigate to the "Settings" tab and locate the "Config Vars" section. Click "Reveal config vars" to expose the configuration variables.
5. Add buildpacks: Navigate to Buildpack and click Add Buildpack to add Python and nodejs. Ensure that the python buildpack is above the Nodejs buildpack.
6. Deploy from GitHub: Navigate to the "Deploy" section by clicking the "Deploy" tab in the top navbar. Select "GitHub" as the deployment method and connect your GitHub repository by searching for its name in the search bar. Click "connect" to link the repository to Heroku.
7. Deploy Branch: Scroll down and click "Deploy Branch" to initiate the deployment process. Heroku will notify you once the app is deployed, and you'll be provided with a button to view the deployed app.

Back to Top

To enjoy this game locally, Docker provides a convenient way to do so. I've prepared a Dockerfile to facilitate building the necessary container. Follow these steps to build and run the Docker container:

Back to Top

Firstly, ensure you have Docker installed on your system. You can download the appropriate version for your operating system from the official Docker website: Download Docker

Alternatively, if you're using macOS or Linux and are familiar with Homebrew, you can install Docker using Homebrew with the following command:

brew --cask install docker

Back to Top

Once Docker is installed and running, proceed with the following steps:

1. Build the Container: This command creates a Docker image based on the instructions in the Dockerfile.

docker build -t yolkaris-odyssey .

• docker build command builds a Docker image.
• -t yolkaris-odyssey tags the image with the name "yolkaris-odyssey". You can replace this with any desired name.
• . the dot specifies the build context, which is the current directory where the Dockerfile is located.

2. Run the Container: This command runs the Docker container based on the built image, mapping port 3000 on the host to port 8000 within the container.

docker run -p 3000:8000 yolkaris-odyssey

• docker run command runs a Docker container.
• -p 3000:8000 maps port 3000 on the host to port 8000 within the container. You can change the ports as needed.
• yolkaris-odyssey specifies the name of the Docker image to run as a container.

Back to Top

Embark on an epic journey in Yolkaris Odyssey, a captivating text-based adventure game set in the vibrant world of Yolkaris. Uncover hidden mysteries, tackle thrilling quests, and endeavor to restore the Grand Clock to its former glory. Here's how to kickstart your adventure:

1. Enter Your Name: Begin by typing in your name when prompted. This will personalize your journey through the game.

2. Choose Your Adventure: Upon entering the game, you'll encounter a screen where you must select your desired adventure:

   • The Broken Clock: Engage in a concise yet action-packed adventure set in a single location. Prepare for intense combat as you endeavor to save Yolkaris from impending doom.

   • The Dark Dust: Dive into a more extensive adventure spanning three distinct locations. Traverse the vast landscapes of Yolkaris as you confront a new threat endangering the planet. Keep in mind that the game lacks a save option, so strategize wisely! If you meet your demise later in the game, you'll need to restart from the beginning. Play smart, and may fortune favor you on your quest!

• map: Displays the map of your current location, showing areas you can explore.
• north: Move to the area north of your current location.
• south: Move to the area south of your current location.
• east: Move to the area east of your current location.
• west: Move to the area west of your current location.
• stats: View your character's health, attack, defense, and other vital stats.
• inventory: Access the items you've collected on your journey. Here, you can inspect items or use them.
• potion: Displays your potion options. Use this command when you need to restore health.
• search: Investigate your current location for hidden items or secrets.
• reset: Resets the game, allowing you to start over from the main screen.

Back to Top

At the outset of "Yolkaris Odyssey," players are presented with the choice between two distinct adventures. They can opt for "The Broken Clock," offering a swift and engaging storyline, or embark on "The Dark Dust," which presents an extended exploration across multiple planets. This initial selection demonstrates the game's flexible narrative approach, allowing players to tailor their gaming experience to their preferred pace and complexity level.

"Yolkaris Odyssey" has a combat system where you can decide your moves. You can keep fighting or choose to leave, heal up, and then come back to fight again. This way, you can make your own strategy on when to fight and when to step back. It makes the game more exciting because you get to plan your next step.

"Yolkaris Odyssey" offers a straightforward inventory system. Players can pick up items, check them, or use them when needed. This part of the game makes sure you can easily handle what you find on your adventure. It shows how keeping item management easy helps players focus more on the story and action.

Incorporating easter eggs and humor, the game illustrates how light-hearted elements and pop culture references can enhance the gaming experience. This aspect of game design underscores the importance of thematic diversity and player connection.

"Yolkaris Odyssey" lets you move freely on each planet's map. You can choose your own path and discover new things at your own pace. The game uses simple commands for moving around, so you can easily decide where to go next. With the "map" command, you can check the map anytime to see where you've been and where you haven't. This feature helps you keep track of your exploration and plan your adventure, making sure you don't miss out on any hidden secrets.

In "Yolkaris Odyssey," you can check your character's stats anytime. This feature lets you see how much health you have left, what weapon or armor you're using, and more. It's useful for planning your next move in the game and making sure you're ready for whatever comes next. By keeping an eye on your stats, you can make better decisions about when to fight, when to heal, and how to use your items and equipment to your advantage.

Click the image to watch the full game play through on YouTube.

Back to Top

To ensure the code is aligned with PEP8 standards, I have use PyCharms built-in PEP8 compliance checker. I've also utilized the Code Institute Python Linter to confirm that the code is compliant with PEP8 standards. This has helped me maintain a consistent coding style and structure throughout the project.

I've dedicated significant time to thoroughly testing its various aspects through manual playtesting. With a focus on ensuring a smooth user experience, I've meticulously explored each feature and scenario within the game.

Throughout the testing process, I've placed particular emphasis on input error handling to prevent users from encountering frustrating dead ends or lack of feedback. Every user interaction has been carefully considered to ensure that players always have the option to quit or cancel their selections, providing a seamless and intuitive gameplay experience.

Having played the game extensively myself, I've personally verified its functionality and stability across multiple playthroughs. This manual testing approach has allowed me to identify and address any potential issues, ensuring that players can enjoy the game without encountering unexpected obstacles.

Back to Top

• Repetitive Code Warning: While working on the add_new_item method, I encountered a warning about repeated code. To address this, I refactored the method by introducing a new equip method within the Interaction class. This new method handles the logic of equipping the player with items, resulting in cleaner and more maintainable code.

...
    def add_new_item(self, item):
        """
        Adds a new item to the player's inventory.
        """
        if isinstance(item, Weapon):
            if item.name == 'none':
                self.player.weapon = None
                return
            if item.received:
                paragraph(f"{item.received}", space=1)
            else:
                paragraph(f"You have received the '{item.name}'.", space=1)
            if item.description:
                paragraph(item.description, space=1)
            self.player.weapon = item

        elif isinstance(item, Armour):
            if item.name == 'none':
                self.player.armour = None
                return
            if item.received:
                paragraph(f"{item.received}", space=1)
            else:
                paragraph(f"You have received '{item.name}'.", space=1)
            if item.description:
                paragraph(item.description, space=1)
            self.player.armour = item
...

...
    def equip(self, item, item_type):
        """
        Equips the player with the item.
        """
        if item.name == 'none':
            setattr(self.player, item_type, None)
            return
        if item.received:
            paragraph(f"{item.received}", space=1)
        else:
            msg = f"You have received '{item.name}'." if item_type == 'armour' else f"You have received the '{item.name}'."
            paragraph(msg, space=1)
        if item.description:
            paragraph(item.description, space=1)
        setattr(self.player, item_type, item)

    def add_new_item(self, item):
        """
        Adds a new item to the player's inventory.
        """
        if isinstance(item, Weapon):
            self.equip(item, 'weapon')

        elif isinstance(item, Armour):
            self.equip(item, 'armour')
...

• During the story development process, I encountered the need to split long lines of text to fit within the 79-character limit. To address this, I alternated between using a small script I developed called py-split and PyCharm's "Fill Paragraph" quick fix feature when the "PEP 8: E501 line too long" warning appeared. However, I found that PyCharm's quick fix did not always produce the desired results, prompting me to rely more heavily on py-split to accurately split the text into multiple lines.

• This is a text-based game where I needed precise formatting of text in the console. To achieve this, I developed two helper functions: text and paragraph.

def text(
        text_line,
        delay=0.1,
        space=0,
        color=default_color
):
    """
    Prints text to the terminal with optional color.
    - text: the text to print
    - delay: the delay between each character
    - space: the number of new lines to print after the text
    - color: the color to apply to the text
    """
    line_space = '\n' * space
    colored_text = (color + text_line if color else text_line) + \
        Fore.RESET + line_space
    print(colored_text)
    time.sleep(delay)

def paragraph(
        long_string,
        space=0,
        delay=0.1,
        color=default_color
):
    """
    Prints a paragraph of text to the terminal with optional color.
    - long_string: the text to wrap and print as a paragraph
    - space: the number of new lines to print after the paragraph
    - color: the color to apply to the text
    """
    wrapped_text = textwrap.fill(long_string, width=74)
    lines = wrapped_text.split('\n')

    text(' ' * 3 + lines[0], color=color)

    for i in range(1, len(lines)):
        line = lines[i]
        if i == len(lines) - 1:
            text(line, color=color)
        else:
            text(line, color=color)

    add_space(space=space, delay=delay)

• The game needed player input in many places and proper error handling. To sort this out I developed a helper function called ask_user that handles the input and error handling in different area of the game. This make sure errors are consistent and relevant to the user input.

...
def ask_user(
        prompt_type: str = None,
        color=color_ask_user,
        prompt: str = None,
        error: str = None,
        space: int = 0,
        numbers=None
):
    """
    Prompts the user for input with an optional color.
    - type: the type of prompt ('continue' or 'confirm')
    - color: the color to apply to the prompt text
    - prompt: the prompt text to display (optional)
    """
    if numbers is None:
        numbers = ['1', '2']
    if prompt_type == "continue":
        prompt = prompt if prompt else "Press enter to continue: "
        line_space = '\n' * (space - 1) if space > 0 else ''
        print(color + prompt + Fore.RESET, end="")
        input().strip().lower()
        if space > 0:
            print(line_space)
    elif prompt_type == "number":
        while True:
            prompt = prompt if prompt else "Select a number: "
            print(color + prompt + Fore.RESET, end="")
            choice = input().strip()
            if choice in numbers:
                return int(choice)
            elif choice == '0':
                return 0
            else:
                error = error if error else ("Invalid choice. Please select a "
                                             "correct number.")
                text(color_error + error + Fore.RESET, space=1)
    elif prompt_type == "game":
        while True:
            prompt = prompt if prompt else "Select a game: "
            print(color + prompt + Fore.RESET, end="")
            choice = input().strip()
            if choice in numbers:
                return int(choice)
            error = error if error else ("Invalid choice. Please select a "
                                             "correct number.")
            text(color_error + error + Fore.RESET, space=1)
                
    elif prompt_type == "confirm":
        prompt = prompt if prompt else "Select 'yes' or 'no': "
        while True:
            print(color + prompt + " (y/n): " + Fore.RESET, end="")
            choice = input().lower().strip()
            if choice in ['yes', 'y']:
                return True
            elif choice in ['no', 'n']:
                return False
            error = error if error else ("Invalid input. Please enter 'yes' "
                                         "or 'no'.")
            text(color_error + error + Fore.RESET, space=1)
    elif prompt_type == "item":
        prompt = prompt if prompt else ("Do you want to 'use' or 'inspect' "
                                        "the item? (u/i), type '0' to cancel:")
        while True:
            print(color + prompt + Fore.RESET, end="")
            choice = input().lower().strip()
            if choice in ['use', 'u', 'inspect', 'i', '0']:
                return choice
            error = error if error else ("Invalid input. Please enter 'u' to "
                                         "use, 'i' to inspect the item or "
                                         "'0' to cancel.")
            text(color_error + error + Fore.RESET, space=1)
    elif prompt_type == "combat":
        prompt = "Do you want to 'fight' or 'retreat'? "
        while True:
            print(color + prompt + Fore.RESET, end="")
            choice = input().lower().strip()
            if choice == 'fight':
                return True
            elif choice == 'retreat':
                return False
            error = error if error else ("Invalid input. Please enter 'fight' "
                                         "or 'retreat'.")
            text(color_error + error + Fore.RESET, space=1)
    elif prompt_type == "retreat":
        prompt = "To continue press enter or 'retreat': "
        while True:
            print(color + prompt + Fore.RESET, end="")
            choice = input().lower().strip()
            if choice == 'retreat':
                return True
            elif choice == '':
                return False
            error = error if error else ("Invalid input. Please enter "
                                         "'retreat' or enter.")
            text(color_error + error + Fore.RESET, space=1)
    else:
        print(color + (prompt if prompt else "") + Fore.RESET, end="")
        return input().strip().lower()
...

• Issue 1 - Input execution timing issue during text output

Back to Top

As Yolkaris Odyssey evolves, here are some exciting features and enhancements that could elevate the gaming experience:

1. Player Accounts: Introduce a player account system to allow users to save their progress, earn achievements, and track their in-game accomplishments over time.
2. Saving Game State: Implement a saving mechanism to allow players to save their current game progress and resume their adventure at a later time.
3. Character Creation and Attributes: Expand character customization options by introducing a character creation system. Players can define attributes such as stamina, intelligence, luck, mana, and more, influencing their gameplay experience and decision-making abilities.
4. Larger and More Diverse Locations: Enrich the world of Yolkaris with a variety of captivating locations to explore. From bustling cities to mysterious forests and treacherous dungeons, offer players a diverse range of environments to immerse themselves in.
5. Quests and Storylines: Introduce compelling quests and storylines that unfold dynamically based on player choices and actions. From epic battles to intricate puzzles, provide engaging challenges that keep players invested in the narrative.
6. NPC Interactions: Enhance player immersion by incorporating rich NPC interactions. Allow players to engage in meaningful conversations with characters inhabiting the world of Yolkaris, each with their own stories, quests, and personalities.
7. Crafting and Trading: Introduce crafting mechanics that enable players to gather resources, craft items, and trade with other characters. From potions and weapons to rare artifacts, offer a wide array of crafting options to empower players in their journey.
8. Dynamic Events and Challenges: Spice up the gameplay experience with dynamic events and challenges that occur spontaneously throughout the game world. From sudden enemy invasions to hidden treasure hunts, keep players on their toes with unexpected surprises.
9. Companions and Allies: Allow players to recruit companions and allies to aid them in their adventures. From loyal pets to skilled mercenaries, offer a diverse roster of characters that players can enlist to accompany them on their quests.
10. Player-driven Economy: Create a player-driven economy where players can buy, sell, and trade goods with one another. Establish marketplaces, auction houses, and trading posts where players can interact and exchange resources, fostering a vibrant in-game economy.

By incorporating these features and enhancements, Yolkaris Odyssey can evolve into a rich and immersive text-based adventure game that captivates players and keeps them coming back for more.

Back to Top

• code institute template to start the project
• code institute CI Python Linter to check the code for PEP8 compliance
• imgbb for hosting the game image

Back to Top

• My mentor, Precious Ijege for providing me with advice on breaking the code to multiple files
• My kids for playing the game and showing me all the errors ;)