📖 Adventure Terminal Documentation

print() is how callbacks communicate with the player. You can print multiple lines, use escape sequences for spacing, and combine it with f-strings for dynamic messages. Return True from the callback to prevent the engine from also printing its default description.

from advengine import Game

def examine_torch(game, command, thing_name):
    print("\nThe torch flickers in a sudden draught.")
    print("Its orange glow illuminates carved runes on the wall:")
    print("  'NORTH LEADS TO PERIL — SOUTH TO REFUGE'")
    print()  # blank line for spacing
    return True  # suppress the default "You use the torch." message

game = Game('mygame.txt')
game.add_callback('use', 'torch', examine_torch)
game.run()

Variables outside your functions are module-level variables that persist across the whole game session. Python has several built-in types: int for counting, str for text, bool for True/False flags, and float for decimal numbers.

from advengine import Game

gold_count = 0       # int — counts coins
player_title = ""   # str — earned title
has_crown = False   # bool — tracks a one-time event

def take_coin(game, command, thing_name):
    global gold_count, player_title
    gold_count += 1
    if gold_count == 1:
        player_title = "Apprentice"
    elif gold_count == 5:
        player_title = "Treasure Seeker"
    elif gold_count >= 10:
        player_title = "Master of Gold"
    print(f"\nCoins collected: {gold_count}  |  Title: {player_title}")
    return False  # also let the engine pick up the coin normally

game = Game('mygame.txt')
game.add_callback('take', 'gold coin', take_coin)
game.run()

input() pauses the game and waits for the player to type something, then returns it as a str. Use .strip().lower() to normalize the answer so capitalisation and extra spaces don't matter.

from advengine import Game

def use_riddle_door(game, command, thing_name):
    print("\nThe stone door rumbles. A voice echoes:")
    print("  'What has teeth but cannot bite?'")
    answer = input("Your answer: ").strip().lower()

    if answer == "comb":
        print("The door grinds open! 'Correct,' the voice whispers.")
        door = game.player.current_location.get_thing("riddle door")
        north = game.player.current_location.get_exit("north")
        if north:
            north.reveal()
    else:
        print(f"'{answer}?' the door cackles. 'Wrong! Try again.'")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'riddle door', use_riddle_door)
game.run()

Python's arithmetic operators — + - * / // % ** — work naturally on integers and floats. Integer division (//) is handy when you need a whole number result (e.g., a quarter of max health). min() / max() prevent values from going out of range.

from advengine import Game

def drink_potion(game, command, thing_name):
    max_hp = game.player.max_health
    current_hp = game.player.health

    heal_amount = max_hp // 4        # integer division: 25% of max
    new_hp = current_hp + heal_amount  # addition
    new_hp = min(new_hp, max_hp)      # cap at max — can't overheal
    actual_healed = new_hp - current_hp

    game.player.health = new_hp
    print(f"\nYou drink the potion. Healed {actual_healed} HP.")
    print(f"Health: {new_hp} / {max_hp}")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'potion', drink_potion)
game.run()

Strings support + for concatenation, * for repetition, and f-strings (f"...") for embedding expressions. Common methods: .upper(), .lower(), .strip(), .replace(), .split().

from advengine import Game

hero_name = "Adventurer"   # could be set from input() earlier

def talk_to_king(game, command, thing_name):
    border = "*" * 40          # string repetition
    greeting = "Hail, " + hero_name + "!"  # concatenation
    title = hero_name.upper()  # string method

    print(f"\n{border}")
    print(f"  {greeting}")
    print(f"  'We have been expecting you, {title}.'")
    print(f"  'The kingdom is yours to save.'")
    print(border)
    return True

game = Game('mygame.txt')
game.add_callback('talk', 'king', talk_to_king)
game.run()

Comments (lines starting with #) are notes for human readers — Python ignores them completely. Good comments explain why code does something, not just what it does. Docstrings ("""...""" right after a def) describe what a function does and appear in help tools.

from advengine import Game

# Phase tracking: False = puzzle not yet solved
lever_pulled = False

def use_lever(game, command, thing_name):
    """Pull the mill lever to grind the grain and reveal the hidden passage."""
    global lever_pulled

    # Once pulled, the lever is stuck — don't allow a second pull
    if lever_pulled:
        print("The lever is already in position.")
        return True

    # Mark the puzzle phase as complete
    lever_pulled = True

    print("\nThe millstone grinds to life — revealing a hidden passage below!")

    # Reveal the concealed exit so the player can go down
    passage = game.player.current_location.get_exit("down")
    if passage:
        passage.reveal()

    return True

game = Game('mygame.txt')
game.add_callback('use', 'lever', use_lever)
game.run()

Comparison operators (== != < > <= >=) return True or False. Logical operators (and or not) combine those booleans. in tests membership in a sequence.

from advengine import Game

def use_drawbridge(game, command, thing_name):
    has_key   = game.player.has_thing("iron key")    # bool
    low_hp    = game.player.health < 20              # comparison
    full_hp   = game.player.health == game.player.max_health

    if has_key and not low_hp:
        print("You unlock the drawbridge and stride across confidently.")
        game.player.current_location.get_exit("north").reveal()
    elif has_key and low_hp:
        print("You limp across the drawbridge. Better find a healer soon!")
        game.player.current_location.get_exit("north").reveal()
    elif not has_key:
        print("The drawbridge is locked. You need an iron key.")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'drawbridge', use_drawbridge)
game.run()

Division (/) always returns a float in Python 3. Use round(value, digits) to control decimal places. Be aware of floating-point imprecision: 0.1 + 0.2 is 0.30000000000000004 — round() is your friend.

from advengine import Game

def check_vitals(game, command, thing_name):
    hp = game.player.health
    max_hp = game.player.max_health

    ratio = hp / max_hp          # float division, e.g. 0.6666...
    pct   = round(ratio * 100, 1)  # e.g. 66.7

    # Determine status string based on percentage
    if pct >= 75.0:
        status = "Excellent condition"
    elif pct >= 50.0:
        status = "Lightly wounded"
    elif pct >= 25.0:
        status = "Badly hurt"
    else:
        status = "Near death!"

    print(f"\n[Vitals] HP: {hp}/{max_hp}  ({pct}%)  — {status}")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'mirror', check_vitals)
game.run()

A while loop repeats as long as its condition is True. It's useful when you don't know in advance how many times to repeat — for example, retrying until the player gives the right answer.

from advengine import Game

RIDDLES = [
    ("What runs but has no legs?",              "water"),
    ("What has a head but no face?",            "coin"),
    ("The more you take, the more you leave behind.", "footsteps"),
]

def consult_oracle(game, command, thing_name):
    print("\nThe oracle speaks: 'Answer my riddles to earn a reward.'")
    score = 0
    i = 0
    while i < len(RIDDLES):
        question, correct = RIDDLES[i]
        answer = input(f"Riddle {i+1}: {question}\n> ").strip().lower()
        if answer == correct:
            print("'Correct!' the oracle chimes.")
            score += 1
        else:
            print(f"'Wrong — the answer was {correct!r}.'")
        i += 1

    print(f"\nYou scored {score} / {len(RIDDLES)}.")
    if score == len(RIDDLES):
        print("'Worthy!' A gem appears at your feet.")
    return True

game = Game('mygame.txt')
game.add_callback('talk', 'oracle', consult_oracle)
game.run()

A for loop iterates over any sequence — a list, a string, a range. game.player.inventory is a list of Thing objects, which makes it a natural target for iteration. Use enumerate() to get both the index and value in one loop.

from advengine import Game

def use_crystal_ball(game, command, thing_name):
    inventory = game.player.inventory

    if not inventory:
        print("\nThe crystal ball shows... nothing. Your pack is empty.")
        return True

    print("\nThe crystal ball reveals your possessions:")
    total_weight = 0
    for i, item in enumerate(inventory, 1):
        print(f"  {i}. {item.name} — {item.description}")
        total_weight += item.weight

    print(f"Total weight carried: {total_weight}")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'crystal ball', use_crystal_ball)
game.run()

break exits a loop immediately. continue skips the rest of the current iteration and moves to the next. Together they let you write efficient searches and filters inside loops.

from advengine import Game

WEAPONS = ["sword", "dagger", "bow", "axe", "spear"]

def use_armory_mirror(game, command, thing_name):
    print("\nThe armory mirror scans your kit...")
    best_weapon = None

    for item in game.player.inventory:
        if item.name not in WEAPONS:
            continue      # skip anything that isn't a weapon
        best_weapon = item.name
        break           # stop after the first weapon found

    if best_weapon:
        print(f"Your primary weapon: {best_weapon}")
    else:
        print("You carry no weapons! The dungeon ahead is dangerous.")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'armory mirror', use_armory_mirror)
game.run()

Define reusable logic in helper functions with descriptive parameters. A function is a named block of code; parameters are the inputs it accepts, and arguments are the actual values passed when calling it. Helper functions keep callbacks short and readable.

from advengine import Game

def health_status(hp, max_hp):
    """Return a descriptive string for the given health values."""
    pct = hp / max_hp * 100
    if pct > 75:  return "You feel strong and ready for anything."
    if pct > 50:  return "You have a few cuts but press on."
    if pct > 25:  return "You are badly hurt. Find a healer."
    return "You are on the brink of collapse!"

def use_mirror(game, command, thing_name):
    msg = health_status(game.player.health, game.player.max_health)
    print(f"\nThe mirror reflects your weary face. {msg}")
    return True

def enter_inn(game, command, direction):
    # Reuse the same helper function in a different callback
    msg = health_status(game.player.health, game.player.max_health)
    print(f"\nThe innkeeper looks you over. {msg}")
    return False

game = Game('mygame.txt')
game.add_callback('use', 'mirror', use_mirror)
game.add_callback('move', 'Inn', enter_inn)
game.run()

Variables defined inside a function are local — they disappear after the function returns. Variables defined at the top of the file are global. To modify a global variable from inside a function, declare it with the global keyword first; otherwise Python creates a new local variable with the same name and the global stays unchanged.

from advengine import Game

drink_count = 0  # global — tracks how many times the fountain was used

def use_fountain(game, command, thing_name):
    global drink_count  # required to modify the global variable
    drink_count += 1

    if drink_count == 1:
        print("\nYou drink. The water tastes sweet and cool.")
        game.player.health = min(game.player.health + 10, game.player.max_health)
    elif drink_count == 2:
        print("\nYou drink again. A warm tingling fills your hands.")
        game.player.health = min(game.player.health + 5, game.player.max_health)
    else:
        print("\nThe fountain has run dry. Not even a drip remains.")

    print(f"Health: {game.player.health} / {game.player.max_health}")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'fountain', use_fountain)
game.run()

A return statement sends a value back to the caller and exits the function. Functions that return True or False (predicates) are especially useful for checking game-state conditions in a readable way. Callbacks themselves return True (handled) or False (pass through).

from advengine import Game

def can_open_vault(game):
    """Return True only when all vault conditions are met."""
    has_gem    = game.player.has_thing("blue gem")
    has_scroll = game.player.has_thing("ancient scroll")
    alive      = game.player.health > 0
    return has_gem and has_scroll and alive  # returns a bool

def use_vault_door(game, command, thing_name):
    if can_open_vault(game):  # call the helper and check its return value
        print("\nThe vault door clicks and swings open!")
        east = game.player.current_location.get_exit("east")
        if east:
            east.reveal()
    else:
        print("\nThe vault door won't budge. Something is still missing...")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'vault door', use_vault_door)
game.run()

An exception is an error that occurs at runtime. A try / except block lets you catch specific exceptions instead of crashing. Always catch the most specific exception type you expect (e.g., FileNotFoundError, ValueError) rather than using a bare except:.

import json
from advengine import Game

NOTES_FILE = "quest_notes.json"

def use_journal(game, command, thing_name):
    try:
        with open(NOTES_FILE) as f:
            data = json.load(f)
        print("\n=== Quest Journal ===")
        for entry in data["entries"]:
            print(f"  • {entry}")
    except FileNotFoundError:
        print("\nThe journal is blank — no entries recorded yet.")
    except json.JSONDecodeError:
        print("\nThe journal pages are smudged and unreadable.")
    except KeyError:
        print("\nThe journal format is unfamiliar. Nothing to read.")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'journal', use_journal)
game.run()

A tuple is an ordered, immutable sequence: once created it cannot be changed. This makes tuples ideal for fixed-structure data like coordinates, RGB colors, or paired values you want to unpack in one line: x, y = position. Tuples use parentheses: (x, y).

from advengine import Game

# Map each direction to a (dx, dy) offset — tuples are immutable
COMPASS = {
    "north": (0,  1),
    "south": (0, -1),
    "east":  (1,  0),
    "west":  (-1, 0),
}

player_pos = (0, 0)  # starting position as a tuple

def track_position(game, command, direction):
    global player_pos
    dx, dy = COMPASS.get(direction, (0, 0))  # unpack the tuple
    x, y = player_pos                           # unpack current position
    player_pos = (x + dx, y + dy)               # create a new tuple
    print(f"  [Map position: {player_pos}]")
    return False

game = Game('mygame.txt')
game.add_callback('move', track_position)
game.run()

A list is an ordered, mutable sequence of values. Unlike tuples, you can add, remove, and change items after creation. Lists are created with square brackets: [1, 2, 3]. Use in to test membership and len() for the count.

from advengine import Game

visited_rooms = []  # mutable list — grows as the player explores

def log_visit(game, command, direction):
    location_name = game.player.current_location.name

    if location_name not in visited_rooms:  # membership test
        visited_rooms.append(location_name)
        print(f"  [New discovery! Rooms explored: {len(visited_rooms)}]")
    return False

def use_explorer_badge(game, command, thing_name):
    print("\nRooms you have explored:")
    for room in visited_rooms:
        print(f"  ✓ {room}")
    print(f"Total: {len(visited_rooms)}")
    return True

game = Game('mygame.txt')
game.add_callback('move', log_visit)
game.add_callback('use', 'explorer badge', use_explorer_badge)
game.run()

Combining for loops with lists is one of Python's most used patterns. You can loop over a list to search, filter, transform, or accumulate values. Building a new list inside the loop (instead of modifying the original while iterating) avoids subtle bugs.

from advengine import Game

CURSED_KEYWORDS = ["skull", "shadow", "cursed", "dark"]

def use_altar(game, command, thing_name):
    print("\nThe altar glows blue, scanning your belongings...")

    cursed_items = []  # build a new list of matches
    for item in game.player.inventory:
        for keyword in CURSED_KEYWORDS:
            if keyword in item.name.lower():
                cursed_items.append(item.name)
                break  # only add the item once even if multiple keywords match

    if cursed_items:
        print("Cursed objects detected:")
        for name in cursed_items:
            print(f"  ⚠ {name}")
        print("The altar trembles with disapproval.")
    else:
        print("Your pack is clean. The altar hums approvingly.")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'altar', use_altar)
game.run()

Lists have many built-in methods: .append(x) adds to the end, .remove(x) deletes the first occurrence, .sort() sorts in place, .pop() removes and returns the last item, .index(x) finds a position, and .count(x) counts occurrences. These all modify the list in place — no assignment needed.

from advengine import Game

quest_log = []  # shared list — no global needed if we only mutate, not reassign

def take_map(game, command, thing_name):
    quest_log.append("Found the treasure map")       # append
    quest_log.sort()                                    # sort alphabetically
    print(f"Quest log updated ({len(quest_log)} entries).")
    return False

def take_key(game, command, thing_name):
    quest_log.append("Obtained the bronze key")
    quest_log.sort()
    print(f"Quest log updated ({len(quest_log)} entries).")
    return False

def use_campfire(game, command, thing_name):
    print("\n=== Quest Log ===")
    if not quest_log:
        print("  (empty)")
    for i, entry in enumerate(quest_log, 1):
        print(f"  {i}. {entry}")
    return True

game = Game('mygame.txt')
game.add_callback('take', 'map', take_map)
game.add_callback('take', 'bronze key', take_key)
game.add_callback('use', 'campfire', use_campfire)
game.run()

Use the built-in open() function to read and write files. The with statement ensures the file is closed automatically. json is the standard library module for reading and writing JSON — a simple, human-readable format for structured data. Always use try / except around file operations.

import json
from advengine import Game

SCORE_FILE = "trophy_scores.json"

def load_scores():
    """Read scores from file; return [] if file missing or invalid."""
    try:
        with open(SCORE_FILE) as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return []

def save_score(name, score):
    """Append a new score, sort descending, keep only top 10, write to file."""
    scores = load_scores()
    scores.append({"name": name, "score": score})
    scores.sort(key=lambda s: s["score"], reverse=True)
    with open(SCORE_FILE, "w") as f:
        json.dump(scores[:10], f, indent=2)  # write top 10 only

def use_trophy(game, command, thing_name):
    name = input("Enter your name for the scoreboard: ").strip()
    if name:
        save_score(name, game.player.score)
        print(f"Score of {game.player.score} saved!")

    print("\n── High Scores ──")
    for i, entry in enumerate(load_scores(), 1):
        print(f"  {i:2}. {entry['name']:<15}  {entry['score']}")
    return True

game = Game('mygame.txt')
game.add_callback('use', 'trophy', use_trophy)
game.run()