=====================================
things and verbs: how objects interact
=====================================

the thing/verb system lets world objects respond to player actions. instead of hardcoding behavior in commands, objects carry their own verb handlers. two ways to register verbs: decorator-based (python classes) or toml-based (content files). both converge to the same dispatch mechanism.

object base class
=================

``Object`` (object.py) is the foundation for all world entities. it has:

- ``name`` - what the object is called
- ``location`` - another Object or None (the entire containment system)
- ``x``, ``y`` - coordinates in the world
- ``_contents`` - list of objects inside this one
- ``_verbs`` - dict mapping verb names to handlers

``__post_init__`` scans the instance for methods decorated with ``@verb`` and auto-registers them in ``_verbs``.

thing and container
===================

``Thing`` (thing.py) extends Object for portable items::

    name: str
    description: str
    portable: bool = True
    aliases: list[str] = []
    readable_text: str | None = None
    tags: set[str] = field(default_factory=set)

``Container`` (container.py) extends Thing with containment rules::

    capacity: int
    closed: bool = False
    locked: bool = False

``can_accept()`` checks object type, open state, and capacity before allowing insertions.

verb registration: decorator path
==================================

the ``@verb`` decorator (verbs.py) marks methods as verb handlers. it sets ``_verb_name`` on the function. ``Object.__post_init__`` discovers these and calls ``register_verb()``::

    class Fountain(Thing):
        @verb("drink")
        async def drink(self, player, args):
            await player.send("You drink from the fountain.\r\n")

when you instantiate the fountain, the drink handler automatically registers in ``_verbs["drink"]``.

verb registration: toml path
=============================

``ThingTemplate`` (things.py) defines objects in toml::

    name = "chest"
    description = "a sturdy wooden chest with iron bindings"
    portable = false
    capacity = 5
    closed = true
    locked = false
    aliases = ["box"]

    [verbs]
    unlock = "verb_handlers:unlock_handler"

``spawn_thing()`` (things.py) creates a Thing or Container from the template. if ``capacity`` is set, you get a Container. if ``verbs`` dict is present, it resolves "module:function" strings via importlib and binds them with functools.partial.

``verb_handlers.py`` contains standalone functions referenced by toml. example::

    async def unlock_handler(obj, player, args):
        if not isinstance(obj, Container):
            await player.send("That's not lockable.\r\n")
            return
        if not obj.locked:
            await player.send("It's already unlocked.\r\n")
            return
        # check for key in inventory...
        obj.locked = False
        await player.send(f"You unlock the {obj.name}.\r\n")

two paths, one dispatch
=======================

decorator-based and toml-based verbs both populate ``Object._verbs``. the command dispatcher doesn't care which path was used.

finding objects
===============

``find_object()`` (verbs.py) searches for targets:

1. player inventory first
2. ground at player position second
3. matches by name or aliases (case-insensitive)

returns the object or None.

command dispatch fallback
=========================

the command dispatcher (commands/__init__.py) tries registered commands first. if no match, it tries verb dispatch:

1. parse input as "verb target" (e.g., "drink fountain")
2. call ``find_object()`` for target
3. check ``obj.has_verb(verb)``
4. call ``obj.call_verb(verb, player, args)``

this lets content authors add new interactions without modifying command code.

use command
===========

``use`` (commands/use.py) provides explicit verb access::

    use fountain           # calls fountain's "use" verb
    use key on chest       # calls chest's "use" verb with args="key on chest"

parses input, finds object, checks for "use" verb, calls handler.

code
====

relevant files::

    src/mudlib/object.py           # Object base class, verb registration
    src/mudlib/thing.py            # Thing class
    src/mudlib/container.py        # Container class
    src/mudlib/verbs.py            # @verb decorator, find_object()
    src/mudlib/things.py           # ThingTemplate, spawn_thing()
    src/mudlib/verb_handlers.py   # standalone verb functions for toml
    src/mudlib/commands/__init__.py  # command dispatcher with verb fallback
    src/mudlib/commands/use.py     # explicit verb command
    content/things/                # toml thing definitions