evennia.scripts.scripts

This module defines Scripts, out-of-character entities that can store data both on themselves and on other objects while also having the ability to run timers.

class evennia.scripts.scripts.DefaultScript(*args, **kwargs)

Bases: ScriptBase

This is the base TypeClass for all Scripts. Scripts describe all entities/systems without a physical existence in the game world that require database storage (like an economic system or combat tracker). They can also have a timer/ticker component.

A script type is customized by redefining some or all of its hook methods and variables.

• available properties (check docs for full listing, this could be outdated).

key (string) - name of object name (string)- same as key aliases (list of strings) - aliases to the object. Will be saved

to database as AliasDB entries but returned as strings.

dbref (int, read-only) - unique #id-number. Also “id” can be used. date_created (string) - time stamp of object creation permissions (list of strings) - list of permission strings

desc (string) - optional description of script, shown in listings obj (Object) - optional object that this script is connected to

and acts on (set automatically by obj.scripts.add())

interval (int) - how often script should run, in seconds. <0 turns

off ticker

start_delay (bool) - if the script should start repeating right away or

wait self.interval seconds

repeats (int) - how many times the script should repeat before

stopping. 0 means infinite repeats

persistent (bool) - if script should survive a server shutdown or not is_active (bool) - if script is currently running

• Handlers

locks - lock-handler: use locks.add() to add new lock strings db - attribute-handler: store/retrieve database attributes on this

self.db.myattr=val, val=self.db.myattr

ndb - non-persistent attribute handler: same as db but does not

create a database entry when storing data

• Helper methods

create(key, **kwargs) start() - start script (this usually happens automatically at creation

and obj.script.add() etc)

stop() - stop script, and delete it pause() - put the script on hold, until unpause() is called. If script

is persistent, the pause state will survive a shutdown.

unpause() - restart a previously paused script. The script will continue

from the paused timer (but at_start() will be called).

time_until_next_repeat() - if a timed script (interval>0), returns time

until next tick

• Hook methods (should also include self as the first argument):

at_script_creation() - called only once, when an object of this

class is first created.

is_valid() - is called to check if the script is valid to be running

at the current time. If is_valid() returns False, the running script is stopped and removed from the game. You can use this to check state changes (i.e. an script tracking some combat stats at regular intervals is only valid to run while there is actual combat going on).

at_start() - Called every time the script is started, which for persistent

scripts is at least once every server start. Note that this is unaffected by self.delay_start, which only delays the first call to at_repeat().

at_repeat() - Called every self.interval seconds. It will be called

immediately upon launch unless self.delay_start is True, which will delay the first call of this method by self.interval seconds. If self.interval==0, this method will never be called.

at_pause() at_stop() - Called as the script object is stopped and is about to be

removed from the game, e.g. because is_valid() returned False.

at_script_delete() at_server_reload() - Called when server reloads. Can be used to

save temporary variables you want should survive a reload.

at_server_shutdown() - called at a full server shutdown. at_server_start()

classmethod create(key, **kwargs)

Provides a passthrough interface to the utils.create_script() function.

Parameters:

key (str) – Name of the new object.

Returns:

object (Object) – A newly created object of the given typeclass. errors (list): A list of errors in string form, if any.

at_script_creation()

Only called once, when script is first created.

is_valid()

Is called to check if the script’s timer is valid to run at this time. Should return a boolean. If False, the timer will be stopped.

at_start(**kwargs)

Called whenever the script timer is started, which for persistent timed scripts is at least once every server start. It will also be called when starting again after a pause (including after a server reload).

Parameters:

**kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_repeat(**kwargs)

Called repeatedly if this Script is set to repeat regularly.

Parameters:

**kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_pause(manual_pause=True, **kwargs)

Called when this script’s timer pauses.

Parameters:

manual_pause (bool) – If set, pausing was done by a direct call. The non-manual pause indicates the script was paused as part of the server reload.

at_stop(**kwargs)

Called whenever when it’s time for this script’s timer to stop (either because is_valid returned False, it ran out of iterations or it was manuallys stopped.

Parameters:

**kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_script_delete()

Called when the Script is deleted, before stopping the timer.

Returns:

bool – If False, the deletion is aborted.

at_server_reload()

This hook is called whenever the server is shutting down for restart/reboot. If you want to, for example, save non-persistent properties across a restart, this is the place to do it.

at_server_shutdown()

This hook is called whenever the server is shutting down fully (i.e. not for a restart).

at_server_start()

This hook is called after the server has started. It can be used to add post-startup setup for Scripts without a timer component (for which at_start could be used).

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.scripts.scripts.DefaultScript'

typename = 'DefaultScript'

class evennia.scripts.scripts.DoNothing(*args, **kwargs)

Bases: DefaultScript

A script that does nothing. Used as default fallback.

at_script_creation()

Setup the script

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.scripts.scripts.DoNothing'

typename = 'DoNothing'

class evennia.scripts.scripts.Store(*args, **kwargs)

Bases: DefaultScript

Simple storage script

at_script_creation()

Setup the script

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.scripts.scripts.Store'

typename = 'Store'

class evennia.scripts.scripts.Deferred(canceller: Callable[[Deferred[Any]], None] | None = None)

Bases: Awaitable[_SelfResultT]

This is a callback which will be put off until later.

Why do we want this? Well, in cases where a function in a threaded program would block until it gets a result, for Twisted it should not block. Instead, it should return a L{Deferred}.

This can be implemented for protocols that run over the network by writing an asynchronous protocol for L{twisted.internet}. For methods that come from outside packages that are not under our control, we use threads (see for example L{twisted.enterprise.adbapi}).

For more information about Deferreds, see doc/core/howto/defer.html or U{http://twistedmatrix.com/documents/current/core/howto/defer.html}

When creating a Deferred, you may provide a canceller function, which will be called by d.cancel() to let you do any clean-up necessary if the user decides not to wait for the deferred to complete.

@ivar called: A flag which is C{False} until either C{callback} or

C{errback} is called and afterwards always C{True}.

@ivar paused: A counter of how many unmatched C{pause} calls have been made

on this instance.

@ivar _suppressAlreadyCalled: A flag used by the cancellation mechanism

which is C{True} if the Deferred has no canceller and has been cancelled, C{False} otherwise. If C{True}, it can be expected that C{callback} or C{errback} will eventually be called and the result should be silently discarded.

@ivar _runningCallbacks: A flag which is C{True} while this instance is

executing its callback chain, used to stop recursive execution of L{_runCallbacks}

@ivar _chainedTo: If this L{Deferred} is waiting for the result of another

L{Deferred}, this is a reference to the other Deferred. Otherwise, L{None}.

__init__(canceller: Callable[[Deferred[Any]], None] | None = None) → None

Initialize a L{Deferred}.

@param canceller: a callable used to stop the pending operation

scheduled by this L{Deferred} when L{Deferred.cancel} is invoked. The canceller will be passed the deferred whose cancellation is requested (i.e., C{self}).

If a canceller is not given, or does not invoke its argument’s C{callback} or C{errback} method, L{Deferred.cancel} will invoke L{Deferred.errback} with a L{CancelledError}.

Note that if a canceller is not given, C{callback} or C{errback} may still be invoked exactly once, even though defer.py will have already invoked C{errback}, as described above. This allows clients of code which returns a L{Deferred} to cancel it without requiring the L{Deferred} instantiator to provide any specific implementation support for cancellation. New in 10.1.

@type canceller: a 1-argument callable which takes a L{Deferred}. The

return result is ignored.

addBoth(callback: Any, *args: Any, **kwargs: Any) → Deferred[Any]

Convenience method for adding a single callable as both a callback and an errback.

See L{addCallbacks}.

addCallback(callback: Any, *args: Any, **kwargs: Any) → Deferred[Any]

Convenience method for adding just a callback.

See L{addCallbacks}.

addCallbacks(callback: Callable[[...], _NextResultT] | Callable[[...], Deferred[_NextResultT]] | Callable[[...], Failure] | Callable[[...], _NextResultT | Deferred[_NextResultT] | Failure], errback: Callable[[...], _NextResultT] | Callable[[...], Deferred[_NextResultT]] | Callable[[...], Failure] | Callable[[...], _NextResultT | Deferred[_NextResultT] | Failure] | None = None, callbackArgs: Tuple[Any, ...] = (), callbackKeywords: Mapping[str, Any] = mappingproxy({}), errbackArgs: Tuple[object, ...] = (), errbackKeywords: Mapping[str, object] = mappingproxy({})) → Deferred[_NextResultT]

Add a pair of callbacks (success and error) to this L{Deferred}.

These will be executed when the ‘master’ callback is run.

@note: The signature of this function was designed many years before

PEP 612; ParamSpec provides no mechanism to annotate parameters like C{callbackArgs}; this is therefore inherently less type-safe than calling C{addCallback} and C{addErrback} separately.

@return: C{self}.

addErrback(errback: Any, *args: Any, **kwargs: Any) → Deferred[Any]

Convenience method for adding just an errback.

See L{addCallbacks}.

addTimeout(timeout: float, clock: <InterfaceClass twisted.internet.interfaces.IReactorTime>, onTimeoutCancel: ~typing.Callable[[~twisted.internet.defer._SelfResultT | ~twisted.python.failure.Failure, float], ~twisted.internet.defer._NextResultT | ~twisted.python.failure.Failure] | None = None) → Deferred[_SelfResultT | _NextResultT]

Time out this L{Deferred} by scheduling it to be cancelled after C{timeout} seconds.

The timeout encompasses all the callbacks and errbacks added to this L{defer.Deferred} before the call to L{addTimeout}, and none added after the call.

If this L{Deferred} gets timed out, it errbacks with a L{TimeoutError}, unless a cancelable function was passed to its initialization or unless a different C{onTimeoutCancel} callable is provided.

@param timeout: number of seconds to wait before timing out this

L{Deferred}

@param clock: The object which will be used to schedule the timeout. @param onTimeoutCancel: A callable which is called immediately after

this L{Deferred} times out, and not if this L{Deferred} is otherwise cancelled before the timeout. It takes an arbitrary value, which is the value of this L{Deferred} at that exact point in time (probably a L{CancelledError} L{Failure}), and the C{timeout}. The default callable (if C{None} is provided) will translate a L{CancelledError} L{Failure} into a L{TimeoutError}.

@return: C{self}.

@since: 16.5

asFuture(loop: AbstractEventLoop) → Future[_SelfResultT]

Adapt this L{Deferred} into a L{Future} which is bound to C{loop}.

@note: converting a L{Deferred} to an L{Future} consumes both

its result and its errors, so this method implicitly converts C{self} into a L{Deferred} firing with L{None}, regardless of what its result previously would have been.

@since: Twisted 17.5.0

@param loop: The L{asyncio} event loop to bind the L{Future} to.

@return: A L{Future} which will fire when the L{Deferred} fires.

callback(result: _SelfResultT | Failure) → None

Run all success callbacks that have been added to this L{Deferred}.

Each callback will have its result passed as the first argument to the next; this way, the callbacks act as a ‘processing chain’. If the success-callback returns a L{Failure} or raises an L{Exception}, processing will continue on the error callback chain. If a callback (or errback) returns another L{Deferred}, this L{Deferred} will be chained to it (and further callbacks will not run until that L{Deferred} has a result).

An instance of L{Deferred} may only have either L{callback} or L{errback} called on it, and only once.

@param result: The object which will be passed to the first callback

added to this L{Deferred} (via L{addCallback}), unless C{result} is a L{Failure}, in which case the behavior is the same as calling C{errback(result)}.

@raise AlreadyCalledError: If L{callback} or L{errback} has already been

called on this L{Deferred}.

called = False

cancel() → None

Cancel this L{Deferred}.

If the L{Deferred} has not yet had its C{errback} or C{callback} method invoked, call the canceller function provided to the constructor. If that function does not invoke C{callback} or C{errback}, or if no canceller function was provided, errback with L{CancelledError}.

If this L{Deferred} is waiting on another L{Deferred}, forward the cancellation to the other L{Deferred}.

chainDeferred(d: Deferred[_SelfResultT]) → Deferred[None]

Chain another L{Deferred} to this L{Deferred}.

This method adds callbacks to this L{Deferred} to call C{d}’s callback or errback, as appropriate. It is merely a shorthand way of performing the following:

d1.addCallbacks(d2.callback, d2.errback)

When you chain a deferred C{d2} to another deferred C{d1} with C{d1.chainDeferred(d2)}, you are making C{d2} participate in the callback chain of C{d1}. Thus any event that fires C{d1} will also fire C{d2}. However, the converse is B{not} true; if C{d2} is fired, C{d1} will not be affected.

Note that unlike the case where chaining is caused by a L{Deferred} being returned from a callback, it is possible to cause the call stack size limit to be exceeded by chaining many L{Deferred}s together with C{chainDeferred}.

@return: C{self}.

debug = False

errback(fail: Failure | BaseException | None = None) → None

Run all error callbacks that have been added to this L{Deferred}.

Each callback will have its result passed as the first argument to the next; this way, the callbacks act as a ‘processing chain’. Also, if the error-callback returns a non-Failure or doesn’t raise an L{Exception}, processing will continue on the success-callback chain.

If the argument that’s passed to me is not a L{Failure} instance, it will be embedded in one. If no argument is passed, a L{Failure} instance will be created based on the current traceback stack.

Passing a string as **fail’ is deprecated, and will be punished with a warning message.

An instance of L{Deferred} may only have either L{callback} or L{errback} called on it, and only once.

@param fail: The L{Failure} object which will be passed to the first

errback added to this L{Deferred} (via L{addErrback}). Alternatively, a L{Exception} instance from which a L{Failure} will be constructed (with no traceback) or L{None} to create a L{Failure} instance from the current exception state (with a traceback).

@raise AlreadyCalledError: If L{callback} or L{errback} has already been

called on this L{Deferred}.

@raise NoCurrentExceptionError: If C{fail} is L{None} but there is

no current exception state.

classmethod fromCoroutine(coro: Coroutine[Deferred[Any], Any, _T] | Generator[Deferred[Any], Any, _T]) → Deferred[_T]

Schedule the execution of a coroutine that awaits on L{Deferred}s, wrapping it in a L{Deferred} that will fire on success/failure of the coroutine.

Coroutine functions return a coroutine object, similar to how generators work. This function turns that coroutine into a Deferred, meaning that it can be used in regular Twisted code. For example:

import treq
from twisted.internet.defer import Deferred
from twisted.internet.task import react

async def crawl(pages):
    results = {}
    for page in pages:
        results[page] = await treq.content(await treq.get(page))
    return results

def main(reactor):
    pages = [
        "http://localhost:8080"
    ]
    d = Deferred.fromCoroutine(crawl(pages))
    d.addCallback(print)
    return d

react(main)

@since: Twisted 21.2.0

@param coro: The coroutine object to schedule.

@raise ValueError: If C{coro} is not a coroutine or generator.

classmethod fromFuture(future: Future[_SelfResultT]) → Deferred[_SelfResultT]

Adapt a L{Future} to a L{Deferred}.

@note: This creates a L{Deferred} from a L{Future}, I{not} from

a C{coroutine}; in other words, you will need to call L{asyncio.ensure_future}, L{asyncio.loop.create_task} or create an L{asyncio.Task} yourself to get from a C{coroutine} to a L{Future} if what you have is an awaitable coroutine and not a L{Future}. (The length of this list of techniques is exactly why we have left it to the caller!)

@since: Twisted 17.5.0

@param future: The L{Future} to adapt.

@return: A L{Deferred} which will fire when the L{Future} fires.

pause() → None

Stop processing on a L{Deferred} until L{unpause}() is called.

paused = 0

unpause() → None

Process all callbacks made since L{pause}() was called.

class evennia.scripts.scripts.ExtendedLoopingCall(f: Callable[[...], object], *a: object, **kw: object)

Bases: LoopingCall

Custom child of LoopingCall that can start at a delay different than self.interval and self.count=0. This allows it to support pausing by resuming at a later period.

start_delay = None

callcount = 0

start(interval, now=True, start_delay=None, count_start=0)

Start running function every interval seconds.

This overloads the LoopingCall default by offering the start_delay keyword and ability to repeat.

Parameters:

• interval (int) – Repeat interval in seconds.

• now (bool, optional) – Whether to start immediately or after start_delay seconds.

• start_delay (int, optional) – This only applies is now=False. It gives number of seconds to wait before starting. If None, use interval as this value instead. Internally, this is used as a way to start with a variable start time after a pause.

• count_start (int) – Number of repeats to start at. The count goes up every time the system repeats. This is used to implement something repeating N number of times etc.

Raises:

• AssertError – if trying to start a task which is already running.

• ValueError – If interval is set to an invalid value < 0.

Notes

As opposed to Twisted’s inbuilt count mechanism, this system will count also if force_repeat() was called rather than just the number of interval seconds since the start. This allows us to force-step through a limited number of steps if we want.

force_repeat()

Force-fire the callback

Raises:

AssertionError – When trying to force a task that is not running.

next_call_time()

Get the next call time. This also takes the eventual effect of start_delay into account.

Returns:

int or None –

The time in seconds until the next call. This

takes start_delay into account. Returns None if the task is not running.

class evennia.scripts.scripts.LoopingCall(f: Callable[[...], object], *a: object, **kw: object)

Bases: object

Call a function repeatedly.

If C{f} returns a deferred, rescheduling will not take place until the deferred has fired. The result value is ignored.

@ivar f: The function to call. @ivar a: A tuple of arguments to pass the function. @ivar kw: A dictionary of keyword arguments to pass to the function. @ivar clock: A provider of

L{twisted.internet.interfaces.IReactorTime}. The default is L{twisted.internet.reactor}. Feel free to set this to something else, but it probably ought to be set before calling L{start}.

@ivar running: A flag which is C{True} while C{f} is scheduled to be called

(or is currently being called). It is set to C{True} when L{start} is called and set to C{False} when L{stop} is called or if C{f} raises an exception. In either case, it will be C{False} by the time the C{Deferred} returned by L{start} fires its callback or errback.

@ivar _realLastTime: When counting skips, the time at which the skip

counter was last invoked.

@ivar _runAtStart: A flag indicating whether the ‘now’ argument was passed

to L{LoopingCall.start}.

__init__(f: Callable[[...], object], *a: object, **kw: object) → None

call: <InterfaceClass twisted.internet.interfaces.IDelayedCall> | None = None

property deferred: Deferred[LoopingCall] | None

DEPRECATED. L{Deferred} fired when loop stops or fails.

Use the L{Deferred} returned by L{LoopingCall.start}.

interval: float | None = None

reset() → None

Skip the next iteration and reset the timer.

@since: 11.1

running = False

start(interval: float, now: bool = True) → Deferred[LoopingCall]

Start running function every interval seconds.

@param interval: The number of seconds between calls. May be less than one. Precision will depend on the underlying platform, the available hardware, and the load on the system.

@param now: If True, run this call right now. Otherwise, wait until the interval has elapsed before beginning.

@return: A Deferred whose callback will be invoked with C{self} when C{self.stop} is called, or whose errback will be invoked when the function raises an exception or returned a deferred that has its errback invoked.

starttime: float | None = None

stop() → None

Stop running function.

classmethod withCount(countCallable: Callable[[int], object]) → LoopingCall

An alternate constructor for L{LoopingCall} that makes available the number of calls which should have occurred since it was last invoked.

Note that this number is an C{int} value; It represents the discrete number of calls that should have been made. For example, if you are using a looping call to display an animation with discrete frames, this number would be the number of frames to advance.

The count is normally 1, but can be higher. For example, if the reactor is blocked and takes too long to invoke the L{LoopingCall}, a Deferred returned from a previous call is not fired before an interval has elapsed, or if the callable itself blocks for longer than an interval, preventing I{itself} from being called.

When running with an interval of 0, count will be always 1.

@param countCallable: A callable that will be invoked each time the

resulting LoopingCall is run, with an integer specifying the number of calls that should have been invoked.

@return: An instance of L{LoopingCall} with call counting enabled,

which provides the count as the first positional argument.

@since: 9.0

class evennia.scripts.scripts.ScriptBase(*args, **kwargs)

Bases: ScriptDB

Base class for scripts. Don’t inherit from this, inherit from the class DefaultScript below instead.

This handles the timer-component of the Script.

objects = <evennia.scripts.manager.ScriptManager object>

at_idmapper_flush()

If we’re flushing this object, make sure the LoopingCall is gone too.

at_first_save(**kwargs)

This is called after very first time this object is saved. Generally, you don’t need to overload this, but only the hooks called by this method.

Parameters:

**kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

delete()

Delete the Script. Normally stops any timer task. This fires at_script_delete before deletion.

Returns:

bool –

If deletion was successful or not. Only time this can fail would be if

the script was already previously deleted, or at_script_delete returns False.

basetype_setup()

Changes fundamental aspects of the type. Usually changes are made in at_script creation instead.

at_init()

Called when the Script is cached in the idmapper. This is usually more reliable than overriding __init__ since the latter can be called at unexpected times.

at_script_creation()

Should be overridden in child.

at_script_delete()

Called when script is deleted, before the script timer stops.

Returns:

bool – If False, deletion is aborted.

is_valid()

If returning False, at_repeat will not be called and timer will stop updating.

at_repeat(**kwargs)

Called repeatedly every interval seconds, once .start() has been called on the Script at least once.

Parameters:

**kwargs (dict) – Arbitrary, optional arguments for users overriding the call (unused by default).

at_start(**kwargs)

at_pause(**kwargs)

at_stop(**kwargs)

start(interval=None, start_delay=None, repeats=None, **kwargs)

Start/Unpause timer component, optionally with new values. If given, this will update the Script’s fields. This will start at_repeat being called every interval seconds.

Keyword Arguments:

• interval (int) – How often to fire at_repeat in seconds.

• start_delay (int) – If the start of ticking should be delayed and by how much.

• repeats (int) – How many repeats. 0 for infinite repeats.

• **kwargs – Optional (default unused) kwargs passed on into the at_start hook.

Notes

If setting the start-delay of a paused Script, the Script will restart exactly after that new start-delay, ignoring the time it was paused at. If only changing the interval, the Script will come out of pause comparing the time it spent in the old interval with the new interval in order to determine when next to fire.

Examples

• Script previously had an interval of 10s and was paused 5s into that interval. Script is now restarted with a 20s interval. It will next fire after 15s.

• Same Script is restarted with a 3s interval. It will fire immediately.

update(interval=None, start_delay=None, repeats=None, **kwargs)

Start/Unpause timer component, optionally with new values. If given, this will update the Script’s fields. This will start at_repeat being called every interval seconds.

Keyword Arguments:

• interval (int) – How often to fire at_repeat in seconds.

• start_delay (int) – If the start of ticking should be delayed and by how much.

• repeats (int) – How many repeats. 0 for infinite repeats.

• **kwargs – Optional (default unused) kwargs passed on into the at_start hook.

Notes

If setting the start-delay of a paused Script, the Script will restart exactly after that new start-delay, ignoring the time it was paused at. If only changing the interval, the Script will come out of pause comparing the time it spent in the old interval with the new interval in order to determine when next to fire.

Examples

• Script previously had an interval of 10s and was paused 5s into that interval. Script is now restarted with a 20s interval. It will next fire after 15s.

• Same Script is restarted with a 3s interval. It will fire immediately.

stop(**kwargs)

Stop the Script’s timer component. This will not delete the Sctipt, just stop the regular firing of at_repeat. Running .start() will start the timer anew, optionally with new settings..

Parameters:

**kwargs – Optional (default unused) kwargs passed on into the at_stop hook.

pause(**kwargs)

Manually the Script’s timer component manually.

Parameters:

**kwargs – Optional (default unused) kwargs passed on into the at_pause hook.

unpause(**kwargs)

Manually unpause a Paused Script.

Parameters:

**kwargs – Optional (default unused) kwargs passed on into the at_start hook.

time_until_next_repeat()

Get time until the script fires it at_repeat hook again.

Returns:

int or None –

Time in seconds until the script runs again.

If not a timed script, return None.

Notes

This hook is not used in any way by the script’s stepping system; it’s only here for the user to be able to check in on their scripts and when they will next be run.

remaining_repeats()

Get the number of returning repeats for limited Scripts.

Returns:

int or None –

The number of repeats remaining until the Script

stops. Returns None if it has unlimited repeats.

reset_callcount(value=0)

Reset the count of the number of calls done.

Parameters:

value (int, optional) – The repeat value to reset to. Default is to set it all the way back to 0.

Notes

This is only useful if repeats != 0.

force_repeat()

Fire a premature triggering of the script callback. This will reset the timer and count down repeats as if the script had fired normally.

exception DoesNotExist

Bases: DoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

path = 'evennia.scripts.scripts.ScriptBase'

typename = 'ScriptBase'

class evennia.scripts.scripts.ScriptDB(*args, **kwargs)

Bases: TypedObject

The Script database representation.

The TypedObject supplies the following (inherited) properties:

key - main name name - alias for key typeclass_path - the path to the decorating typeclass typeclass - auto-linked typeclass date_created - time stamp of object creation permissions - perm strings dbref - #id of object db - persistent attribute storage ndb - non-persistent attribute storage

The ScriptDB adds the following properties:

desc - optional description of script obj - the object the script is linked to, if any account - the account the script is linked to (exclusive with obj) interval - how often script should run start_delay - if the script should start repeating right away repeats - how many times the script should repeat persistent - if script should survive a server reboot is_active - bool if script is currently running

exception DoesNotExist

Bases: ObjectDoesNotExist

exception MultipleObjectsReturned

Bases: MultipleObjectsReturned

property account

A wrapper for getting database field db_account.

db_account

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

**Child.parent** is a **ForwardManyToOneDescriptor** instance.

db_account_id

db_attributes

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

db_date_created

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_desc

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_interval

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_is_active

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_key

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_lock_storage

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_obj

Accessor to the related object on the forward side of a many-to-one or one-to-one (via ForwardOneToOneDescriptor subclass) relation.

In the example:

class Child(Model):
    parent = ForeignKey(Parent, related_name='children')

**Child.parent** is a **ForwardManyToOneDescriptor** instance.

db_obj_id

db_persistent

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_repeats

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_start_delay

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

db_tags

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

db_typeclass_path

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property desc

A wrapper for getting database field db_desc.

get_next_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=True, **kwargs)

get_previous_by_db_date_created(*, field=<django.db.models.fields.DateTimeField: db_date_created>, is_next=False, **kwargs)

id

A wrapper for a deferred-loading field. When the value is read from this object the first time, the query is executed.

property interval

A wrapper for getting database field db_interval.

property is_active

A wrapper for getting database field db_is_active.

property obj

Property wrapper that homogenizes access to either the db_account or db_obj field, using the same object property name.

property object

Property wrapper that homogenizes access to either the db_account or db_obj field, using the same object property name.

objects = <evennia.scripts.manager.ScriptDBManager object>

path = 'evennia.scripts.models.ScriptDB'

property persistent

A wrapper for getting database field db_persistent.

receiver_script_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

property repeats

A wrapper for getting database field db_repeats.

sender_script_set

Accessor to the related objects manager on the forward and reverse sides of a many-to-many relation.

In the example:

class Pizza(Model):
    toppings = ManyToManyField(Topping, related_name='pizzas')

**Pizza.toppings** and **Topping.pizzas** are **ManyToManyDescriptor** instances.

Most of the implementation is delegated to a dynamically defined manager class built by **create_forward_many_to_many_manager()** defined below.

property start_delay

A wrapper for getting database field db_start_delay.

typename = 'SharedMemoryModelBase'

class evennia.scripts.scripts.ScriptManager(*args, **kwargs)

Bases: ScriptDBManager, TypeclassManager

class evennia.scripts.scripts.TypeclassBase(name, bases, attrs)

Bases: SharedMemoryModelBase

Metaclass which should be set for the root of model proxies that don’t define any new fields, like Object, Script etc. This is the basis for the typeclassing system.

evennia.scripts.scripts.maybeDeferred(f: ~typing.Callable[[~_P], ~twisted.internet.defer.Deferred[~twisted.internet.defer._T] | ~typing.Coroutine[~twisted.internet.defer.Deferred[~typing.Any], ~typing.Any, ~twisted.internet.defer._T] | ~twisted.internet.defer._T], *args: ~typing.~_P, **kwargs: ~typing.~_P) → Deferred[_T]

Invoke a function that may or may not return a L{Deferred} or coroutine.

Call the given function with the given arguments. Then:

• If the returned object is a L{Deferred}, return it.

• If the returned object is a L{Failure}, wrap it with L{fail} and return it.

• If the returned object is a L{types.CoroutineType}, wrap it with L{Deferred.fromCoroutine} and return it.

• Otherwise, wrap it in L{succeed} and return it.

• If an exception is raised, convert it to a L{Failure}, wrap it in L{fail}, and then return it.

@param f: The callable to invoke @param args: The arguments to pass to C{f} @param kwargs: The keyword arguments to pass to C{f}

@return: The result of the function call, wrapped in a L{Deferred} if necessary.