World

The world is where your adventure lives, this is the root of you entire story and where all the events happen. To create the basis of a World you use and subclass the two classes described bellow:

class pyzork.world.Location(**kwargs)

A location represents a place in which the player exists while out of combat, this is where players usually go about their normal tasks of discovering things and such. A location can be of any scale, it could be a room or individual corners of the room or it could be an entire country, you can design as you wish.

Parameters:

• name (Optional[str]) – The name of the location, if this is not provided then the library will fall back to the docstring of the class and then to the class name itself
• description (Optional[str]) – A description of the location, if none is provided it will default to the __init__ docstring.
• npcs (Optional[List[Entity]]) – Optional list of entities with which the player can interact
• enemies (Optional[List[Enemy]]) – Optional list of enemies against which the player will fight when they enter the location

name

The name of the location

Type:str

description

The description of the location, which gets printed when the user enters it if the enter method is not overriden.

Type:Optional[str]

npcs

List of npcs that can be interacted with

Type:List[Entity]

enemies

List of enemies the user will battle when entering the first time

Type:List[Enemy]

visited

How many times the user has visited this place

Type:int

can_move_to(location: Union[pyzork.enums.Direction, Location]) → bool

Boolean check if the player can travel in this direction or location

Parameters:location (Union[Direction, Location]) – The location/direction to check Returns:True if you can travel that way, else False Return type:bool

directional_move(direction: pyzork.enums.Direction) → pyzork.world.Location

Returns the location of of the exit in this direction

Parameters:direction (Direction) – The direction to check Returns:The location or None Return type:Optional[Location]

enter(player: Player, from_location: Location) → Optional[bool]

Method to be overwritten by the user to create a custom behavior when the player enters this location. By default simply prints the name and description.

Parameters:

• player (Player) – The player instance entering the location
• from_location (Location) – The location the player is coming from

Returns:

If the method returns False then the move will be cancelled and the player will be sent back to from_location

Return type:

Optional[Bool]

exit(player: Player, to_location: Location) → Optional[bool]

Method to be overwritten by the user to create a custom behavior when the player exits this location. Does nothing by default.

Parameters:

• player (Player) – The player instance leaving the location
• to_location (Location) – The location the player is going to

Returns:

If the method returns False then the move will be cancelled and the player will remain in this current location.

Return type:

Optional[Bool]

classmethod from_dict(**kwargs)

Create a Location from a set of kwargs, takes the same parameters as the class and returns a subclass of it by the same name. If you add npcs and enemies through this you must pass the classes themselves and not the instances.

one_way_connect(direction: pyzork.enums.Direction, connected_location: Optional[pyzork.world.Location] = None)

Create or remove a one way connection to connected_location. This means that going in direction will take the use to connected_location. If no connected_location is provided then it will remove any exit for this location in that direction, all other connections remain intact.

Parameters:

• direction (Direction) – The direction of the exit you wish to edit
• connected_location (Optional[Location]) – The location you want to connect this one to, if none are provided then it will break of any existing connection.

print_exits(world: pyzork.world.World)

Print all the exits for this location

print_interaction(world: pyzork.world.World, direction: pyzork.enums.Direction)

Method called to print a flavor text related to reaching this location from another location. Prints the direction and name of the location by default

Parameters:

• world (World) – The world the location is in
• direction (Direction) – The direction the location is in compared to the world.current_location

print_npcs(world: pyzork.world.World)

Print all the npc interactions for this location

two_way_connect(direction: pyzork.enums.Direction, connected_location: Optional[pyzork.world.Location] = None)

Connect this Location with the connected_location in a way that the connected location can be reached by going in the direction. If no location is provided then the connection in that direction will be broken in both ways. The two way connections means that the player will also be able to go from the connection_location to this location in the opposite way.

Parameters:

• direction (Direction) – The direction of the exit you wish to edit
• connected_location (Optiona[Location]) – The location you want to make the connection to, if none are provided then it will break off any existing connection both ways

class pyzork.world.Shop(**kwargs)

Shops are special locations where the only interactions that can be performed are related to buying and selling items. You can only buy and sell items which are registed in the shop, you cannot sell an item which is not registered in the shop, as this allows for dynamic pricing accross shops.

Parameters:

• items (List[ShopItem]) – List of items for sale
• resell (Optional[float]) – The value of an item when being sold to the shop, percentage of the initial value, 1 by default. If this is set for zero then resale is disabled for this shop.
• name (str) – Name of the shop
• description (Optional[str]) – Optional description of the shop

name

The name of the shop

Type:str

description

The description of the shop, which gets printed when the user enters it if the :method:enter is not overriden.

Type:Optional[str]

items

The list of items that can be bought or sold

Type:List[ShopItem]

resell

The multipler applied on the original price to get the resale value of an item.

Type:float

can_move_to(location: Union[pyzork.enums.Direction, Location]) → bool

Boolean check if the player can travel in this direction or location

Parameters:location (Union[Direction, Location]) – The location/direction to check Returns:True if you can travel that way, else False Return type:bool

directional_move(direction: pyzork.enums.Direction) → pyzork.world.Location

Returns the location of of the exit in this direction

Parameters:direction (Direction) – The direction to check Returns:The location or None Return type:Optional[Location]

enter(player: Player, from_location: Location) → Optional[bool]

Method to be overwritten by the user to create a custom behavior when the player enters this location. By default simply prints the name and description.

Parameters:

• player (Player) – The player instance entering the location
• from_location (Location) – The location the player is coming from

Returns:

If the method returns False then the move will be cancelled and the player will be sent back to from_location

Return type:

Optional[Bool]

exit(player: Player, to_location: Location) → Optional[bool]

Method to be overwritten by the user to create a custom behavior when the player exits this location. Does nothing by default.

Parameters:

• player (Player) – The player instance leaving the location
• to_location (Location) – The location the player is going to

Returns:

If the method returns False then the move will be cancelled and the player will remain in this current location.

Return type:

Optional[Bool]

classmethod from_dict(**kwargs)

Allows you to create a shop from kwargs, takes the same parameters as the class.

one_way_connect(direction: pyzork.enums.Direction, connected_location: Optional[pyzork.world.Location] = None)

Create or remove a one way connection to connected_location. This means that going in direction will take the use to connected_location. If no connected_location is provided then it will remove any exit for this location in that direction, all other connections remain intact.

Parameters:

• direction (Direction) – The direction of the exit you wish to edit
• connected_location (Optional[Location]) – The location you want to connect this one to, if none are provided then it will break of any existing connection.

print_exits(world: pyzork.world.World)

Print all the exits for this location

print_interaction(world: pyzork.world.World, direction: pyzork.enums.Direction)

Method called to print a flavor text related to reaching this shop from another location.

Parameters:

• world (World) – The world the location is in
• direction (Direction) – The direction the location is in compared to the world.current_location

print_items(player: Player)

Print all the items for sale in this shop on the money of the player.

print_npcs(world: pyzork.world.World)

Print all the npc interactions for this location

shop_loop(player: Player)

The heart of the shop system, this allows the player to buy, sell, exit the shop, view his stats/inventory and use/equip items.

two_way_connect(direction: pyzork.enums.Direction, connected_location: Optional[pyzork.world.Location] = None)

Connect this Location with the connected_location in a way that the connected location can be reached by going in the direction. If no location is provided then the connection in that direction will be broken in both ways. The two way connections means that the player will also be able to go from the connection_location to this location in the opposite way.

Parameters:

• direction (Direction) – The direction of the exit you wish to edit
• connected_location (Optiona[Location]) – The location you want to make the connection to, if none are provided then it will break off any existing connection both ways

update_alive()

remove all the dead stuff

class pyzork.world.World(**kwargs)

The world is the class that englobes everything, this is where your adventure lives and happens. You don’t need to subclass this class, only call it and pass it to the game_loop

Parameters:

• locations (List[Location]) – A list of all the location in this world
• player (Player) – The player of this world
• start (Optional[Location]) – The place where the player starts, by default it is the first Location in locations
• end_game (Optional[Callable[[EndGame], None]]) – Optional method for handling what happens when the game is finished, could be either because the player has won, died or many other possible reasons.
• error_handler (Optional[Callable[[Exception], None]]) – Optional method to handle other errors in case any arise.

current_location

The location the Player is currently in

Type:Location

player

The player of this world

Type:Player

locations

A list of location instances representing all possible locations in the world

Type:List[Location]

can_move(location: Union[pyzork.enums.Direction, pyzork.world.Location]) → bool

Check if the player can move from their current location in that direction/location

Parameters:location (Union[Direction, Location]) – The direction/location Returns:True if the player can move there Return type:bool

directional_move(direction: pyzork.enums.Direction) → Optional[Location]

Convert a direction into a location, if it exists, else return None

Parameters:direction (Direction) – The direction you want to move in Returns:The location that is in that direction Return type:Optional[Location]

end_game(e: EndGame)

Method to be overwritten either through subclassing or by passing it as a parameters when instancing the world. Is called when an Endgame exception is raised. Signifying the player has either died or won.

Parameters:e (EndGame) – The endgame error that caused this

end_turn()

Decrement the duration of all player modifiers by 1

error_handler(e: Exception)

Error handler for all other errors, can be used to either restart the loop or kill the game. Can be overriden by either subclassing or by passing it as a parameter when instancing the world.

Parameters:e (Exception) – the error that was caught

initiate_battle(enemies: List[Enemy])

Start a battle and the battle loop between the player of this world and a list of enemies. If you want to inject your own battle class. This method must start the battle, this is usually done through the Battle.battle_loop method

Parameters:enemies (List[Enemy]) – List of enemies to fight

legal_travel(location: pyzork.world.Location)

Attempt a travel move, compared to simply World.travel this checks if the player can move to this location from their current location and move there if they can.

Parameters:location (Location) – The location to attept moving too

print_menu()

Prints the context menu that is available everywhere, this is only visual.

travel(new_location: pyzork.world.Location)

Travel in a to a location regadless of if it is a “legal” move, this instantly transports the player to the target location and initatie battle if any enemies are present.

Parameters:new_location (Location) – The location to travel to, this does not have to be connected to the current location.

travel_parser()

Gets the user input and check if it matches against a set of parsers using python’s new walrus operator.

world_loop()

Handler for traveling around the world. This method calls end turn so modifiers and effects will expire while the user travels in the world. Unless you’re doing some advanced stuff with the library such as handling the game loop on your own you shouldn’t need to call this.

Examples

Basic Location

The most basic form of a location is one created which only has a name, description, list of npcs and list of enemies. This kind of locations use the default behaviour of the parent class:

from pyzork import Location

from my_adventure.enemies import Goblin
from my_adventure.npcs import OldMan, Table

MarketPlace = Location.from_dict(
    name="Market Place",
    description="This is a nice market"
    npcs=[OldMan, Table],
    enemies=[Goblin]
)

Here we see a basic example, of a markeplace with a Goblin as an enemy as a table and old man that can be interacted with. NOTE: As you can notice, the parameters being passed to npcs and enemies are list of CLASSES not instances, this is key to avoid all instances of that location having the same instance.

Sublcassed Location

A more complex example, giving more flexibility, and a chanc to overwrite any methods you desire to add in your own:

from pyzork import Location

from my_adventure.locations import Docks

class Island(Location):
"""A Small Island"""
def enter(self, player, from_location):
    post_output(self.name)
    if isinstance(from_location, Docks):
        post_output("\n\nYou beach your boat on the sand")
    else:
        post_output("\n\nYou arrive on a beach")

def exit(self, player, to_location):
    post_output(self.name)
    if isinstance(to_location, Docks):
        post_output("\n\nYou take the boat back to the docks")
    else:
        post_output("\n\nYou leave the beach")

In this example we ovveride the enter and exit method to print different message based on where the player is coming from. Logically if they’re going to the docks from the island you can’t just walk there, you take a boat. Therefore, overwriting these methods allow you to add some flair to your game, with different messages based on where the user is coming from.

Shop Example

Shop are special locations where the player buys and sells items, allowing them to make money or buy powerful weapons. Making a shop is very simple, you don’t need to subclass anything to make your own version of a shop, you can easily pass the required argument to Shop.from_dict, like so:

from pyzork import Shop

MarketShop = Shop.from_dict(
    resell=0.25,
    name="A Big Shop",
    items=[
        ShopItem(item=Sword, price=25, amount=1),
        ShopItem(item=HealthPotion, amount=5, price=10),
        ShopItem(item=HealingOnguent, amount=3, price=5),
        ShopItem(item=SwordAndShield, price=30)
    ]
)

This shop is called “A Big Shop”, sells swords, healing potions, healing onguents. It also sells sword and shield combos but since it starts with an amount of zero it won’t sell any till the player sells some the shop first. Items sold to the shop are taken at a quarter of their original value.

World Example

So how it come all together? How do you take all the creations you made and group them up into a single world? Here’s a basic example, regrouping the class we created in previous examples:

from pyzork import Player, World, Direction

from my_adventure.locations import MarketShop, Island, Docks, MarketPlace

shop = MarketShop()
island = Island()
docks = Docks()
market = MarketPlace()

market.two_way_connect(Direction.east, docks)
market.two_way_connect(Direction.north, shop)
docks.two_way_connect(Direction.east, island)

player = Player()

world = World(locations=[shop, island, docks, market], start=market, player=player)

Using the module’s visualisation function we can see that this is what our world looks like: