repository·master·Indexed 41 days ago
https://github.com/lordmauve/adventurelibA lightweight Python library for beginners to create text-based adventure games. It provides a command-handling system using the @when decorator for pattern matching, a Bag class for item management, and an Item class for game objects. It includes features like hierarchical Command Contexts to restrict command availability, a custom prompt system, and a say() function for formatted prose output.
adventurelib is a library designed to provide basic functionality for writing text-based adventure games. It focuses on ease of use, specifically targeting beginners. It provides the command-handling infrastructure, while higher-level game concepts like rooms, items, and characters are left for the developer to implement as they learn Python.Contexts can be nested using dot notation (e.g., parent.child).
Hierarchy Rules:
wonderland.flying, all commands registered to wonderland, wonderland.flying, and those with no context are available.# Available in 'wonderland' and 'wonderland.flying'
@when('north', dir='north')
# Overrides 'north' behavior specifically in 'confused' context
@when('north', dir='south', context='confused')
# Overrides 'north' behavior specifically in 'confused.really' sub-context
@when('north', context='confused.really')
def confused_north():
say('The cauliflowers are in bloom this year.')Unlike many text-based adventure engines that provide pre-built systems for rooms, items, and NPCs, adventurelib provides minimal built-in support for these structures. This is a deliberate design choice intended to force developers to model game state and business logic themselves.
When using adventurelib, you are responsible for implementing:
The core mechanism of adventurelib is defining functions that execute in response to specific user commands. You use the @when decorator to map a command pattern to a Python function. The decorator supports pattern matching where placeholders (like THING) are passed as arguments to the decorated function.
@when('take THING')
def take(thing):
print(f'You take the {thing}.')
inventory.append(thing)While the adventurelib API is in English, you can write games in other languages. However, be aware of the following technical limitations regarding non-English text:
@when() decorator matches on the basis of words (splitting on spaces). This may not function correctly for ideographic or logographic languages.@when('take ITEM') rely on uppercase/lowercase distinctions, which may not exist in all languages.rooms system has built-in identifiers north, south, east, and west. While you can add your own directions, functions like room.exits() will return these English identifiers and must be translated before being displayed to the user.say() function may behave unexpectedly, and @when pattern matching uses a left-to-right greedy approach.Adventurelib uses a greedy algorithm for capturing values. An uppercase placeholder will 'eat' as many words as possible until it hits the next static word in the command pattern.
To prevent unexpected behavior when capturing multiple objects, it is best practice to include static 'separator' words like to, with, or on in your command patterns. This helps the parser correctly split phrases.
# Good: 'to' acts as a delimiter
@when('give ITEM to RECIPIENT')
# Risky: 'ITEM' might eat 'RECIPIENT' if no delimiter exists
@when('give ITEM RECIPIENT')A Bag is a collection of items that allows you to look up objects by the names players type. It is a set subclass, meaning it supports iteration and adding items. You can use Bag to represent player inventories, items in a room, or even groups of characters.
bag.find(name): Returns the item matching the name without removing it. Returns None if no match is found.bag.take(name): Returns the item matching the name and removes it from the bag. Returns None if no match is found.bag.add(item): Adds an item to the bag if it isn't already present.bag.get_random(): Returns a random item without removing it.bag.take_random(): Removes and returns a random item.name in bag: Checks if a name exists in the bag.inventory = Bag()
@when('inventory')
def show_inventory():
print('You have:')
for item in inventory:
print(f'* {item}')The Room object supports compass directions (north, south, east, west) by default. When you assign a room to one of these attributes on another room, adventurelib automatically creates a bi-directional relationship. For example, if space.north = spaceship, then spaceship.south will automatically point back to space.
space.north = spaceship
# This is automatically true:
# spaceship.south is spaceadventurelib is a single-file library, you can manually download adventurelib.py and place it in the same directory as your game script. This allows you to use the library without a formal installation process.To begin a new game, import all functions from adventurelib and call start() at the very end of your script. This initializes the game loop and allows the player to interact with the terminal.
All game logic and command definitions must be placed between the import statement and the start() call.
from adventurelib import *
# Your game logic goes here
start()To implement movement, you can use the @when decorator with the direction keyword argument. This allows a single function to handle multiple directions by receiving the direction name as a parameter. Use current_room.exit(direction) to find the destination.
@when('north', direction='north')
@when('south', direction='south')
@when('east', direction='east')
@when('west', direction='west')
@when('n', direction='north')
@when('s', direction='south')
@when('e', direction='east')
@when('w', direction='west')
def go(direction):
global current_room
room = current_room.exit(direction)
if room:
current_room = room
print(f'You go {direction}.')
# Assuming a look() function exists to show room description
print(current_room)You can install adventurelib using pip from your command line.
pip install adventurelib