From 5da870beab3cc086d40690ee22282d64e591bbed Mon Sep 17 00:00:00 2001 From: Count Infinity Date: Wed, 19 Nov 2025 01:01:28 -0700 Subject: [PATCH 1/2] Clarify caller keyword requirement --- docs/source/Components/Prototypes.md | 5 ++--- evennia/prototypes/spawner.py | 6 ++++-- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/source/Components/Prototypes.md b/docs/source/Components/Prototypes.md index c99e49061f..63a4aaefec 100644 --- a/docs/source/Components/Prototypes.md +++ b/docs/source/Components/Prototypes.md @@ -167,9 +167,8 @@ The default protfuncs available out of the box are defined in `evennia/prototype | `$div(, )` | Returns value2 / value1 | | `$toint()` | Returns value converted to integer (or value if not possible) | | `$eval()` | Returns result of [literal-eval](https://docs.python.org/2/library/ast.html#ast.literal_eval) of code string. Only simple python expressions. | -| `$obj()` | Returns object #dbref searched globally by key, tag or #dbref. Error if more than one found. | -| `$objlist()` | Like `$obj`, except always returns a list of zero, one or more results. | -| `$dbref(dbref)` | Returns argument if it is formed as a #dbref (e.g. #1234), otherwise error. | +| `$obj()` | Returns object searched globally by key, tag or #dbref. Requires `caller` kwarg in `spawner.spawn()` for access checks. See [searching callables](./FuncParser.md#evenniautilsfuncparsersearching_callables). | +| `$objlist()` | Like `$obj`, except always returns a list of zero, one or more results. Requires `caller` kwarg in `spawner.spawn()` for access checks. See [searching callables](./FuncParser.md#evenniautilsfuncparsersearching_callables). | For developers with access to Python, using protfuncs in prototypes is generally not useful. Passing real Python functions is a lot more powerful and flexible. Their main use is to allow in-game builders to do limited coding/scripting for their prototypes without giving them direct access to raw Python. diff --git a/evennia/prototypes/spawner.py b/evennia/prototypes/spawner.py index 2a6db5d84c..37976d9449 100644 --- a/evennia/prototypes/spawner.py +++ b/evennia/prototypes/spawner.py @@ -653,7 +653,8 @@ def batch_update_objects_with_prototype( if it's not set in the prototype. With `exact=True`, all un-specified properties of the objects will be removed if they exist. This will lead to a more accurate 1:1 correlation between the object and the prototype but is usually impractical. - caller (Object or Account, optional): This may be used by protfuncs to do permission checks. + caller (Object or Account, optional): The object requesting the update. Required when using + protofuncs that perform searches. For example ($obj, $objlist, $dbref, $search). protfunc_raise_errors (bool): Have protfuncs raise explicit errors if malformed/not found. This is highly recommended. Returns: @@ -890,7 +891,8 @@ def spawn(*prototypes, caller=None, **kwargs): prototype_key (will be used to find the prototype) or a full prototype dictionary. These will be batched-spawned as one object each. Keyword Args: - caller (Object or Account, optional): This may be used by protfuncs to do access checks. + caller (Object or Account, optional): The object requesting the update. Required when using + protofuncs that perform searches. For example ($obj, $objlist, $dbref, $search). prototype_modules (str or list): A python-path to a prototype module, or a list of such paths. These will be used to build the global protparents dictionary accessible by the input From 01a907d9fb1db80e13b57c4c7c1133d64aa51146 Mon Sep 17 00:00:00 2001 From: Count Infinity Date: Wed, 19 Nov 2025 22:24:32 -0700 Subject: [PATCH 2/2] Add back in --- docs/source/Components/Prototypes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/Components/Prototypes.md b/docs/source/Components/Prototypes.md index 63a4aaefec..875dcdd18c 100644 --- a/docs/source/Components/Prototypes.md +++ b/docs/source/Components/Prototypes.md @@ -167,7 +167,7 @@ The default protfuncs available out of the box are defined in `evennia/prototype | `$div(, )` | Returns value2 / value1 | | `$toint()` | Returns value converted to integer (or value if not possible) | | `$eval()` | Returns result of [literal-eval](https://docs.python.org/2/library/ast.html#ast.literal_eval) of code string. Only simple python expressions. | -| `$obj()` | Returns object searched globally by key, tag or #dbref. Requires `caller` kwarg in `spawner.spawn()` for access checks. See [searching callables](./FuncParser.md#evenniautilsfuncparsersearching_callables). | +| `$obj()` | Returns object searched globally by key, tag or #dbref. Requires `caller` kwarg in `spawner.spawn()` for access checks. See [searching callables](./FuncParser.md#evenniautilsfuncparsersearching_callables). ($dbref() is an alias and works the same) | | `$objlist()` | Like `$obj`, except always returns a list of zero, one or more results. Requires `caller` kwarg in `spawner.spawn()` for access checks. See [searching callables](./FuncParser.md#evenniautilsfuncparsersearching_callables). | For developers with access to Python, using protfuncs in prototypes is generally not useful. Passing real Python functions is a lot more powerful and flexible. Their main use is to allow in-game builders to do limited coding/scripting for their prototypes without giving them direct access to raw Python.