Update game template class doc strings to be more up-to-date. Resolve #3387

evennia/scripts/scripts.py

@@ -6,13 +6,12 @@ ability to run timers.
 """
 
 from django.utils.translation import gettext as _
-from twisted.internet.defer import Deferred, maybeDeferred
-from twisted.internet.task import LoopingCall
-
 from evennia.scripts.manager import ScriptManager
 from evennia.scripts.models import ScriptDB
 from evennia.typeclasses.models import TypeclassBase
 from evennia.utils import create, logger
+from twisted.internet.defer import Deferred, maybeDeferred
+from twisted.internet.task import LoopingCall
 
 __all__ = ["DefaultScript", "DoNothing", "Store"]
 
@@ -672,8 +671,85 @@ class ScriptBase(ScriptDB, metaclass=TypeclassBase):
 class DefaultScript(ScriptBase):
     """
     This is the base TypeClass for all Scripts. Scripts describe
-    events, timers and states in game, they can have a time component
-    or describe a state that changes under certain conditions.
+    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()
 
     """