Writing Modules In Python - Revision history

Initrd.gz: /* Callbacks */ Updated python callbacks with a link to the Callbacks page.

2008-11-13T23:33:57Z

‎Callbacks: Updated python callbacks with a link to the Callbacks page.

Initrd.gz: /* Timers */

2008-11-08T02:14:05Z

‎Timers

Initrd.gz: /* Timers */

2008-11-08T00:52:52Z

‎Timers

Initrd.gz: /* Callbacks */

2008-10-27T17:07:13Z

‎Callbacks

Initrd.gz: /* Callbacks */ Added a small description to Python callbacks.

2008-10-27T17:04:51Z

‎Callbacks: Added a small description to Python callbacks.

Initrd.gz: /* Looping over all players */

2008-10-25T23:17:48Z

‎Looping over all players

Initrd.gz: /* Persistent per-player data */ Updated to ASSS v1.4.2

2008-10-11T18:34:38Z

‎Persistent per-player data: Updated to ASSS v1.4.2

Initrd.gz: /* Per-player/arena data */

2008-10-11T17:50:11Z

‎Per-player/arena data

CypherJF: fixed spellings

2007-10-01T01:50:40Z

fixed spellings

Smong: /* Trouble shooting */ added error msg

2007-05-22T10:34:24Z

‎Trouble shooting: added error msg

@@ Line 64: / Line 64: @@
 cb1 = reg_callback(CB_GOAL, goal)
 </pre>
-The ref_callback function takes two parameters: An ID for the action, which are constants imported from the asss module and begin with "CB_", and the function to call when the action is triggered. Different IDs take different parameters, and some require you to return a value. This simple module sends the text "goal." to the arena that the player who scored a goal is in.
+The ref_callback function takes two parameters: An ID for the action, which are constants imported from the asss module and begin with "CB_", and the function to call when the action is triggered. Different IDs take different parameters, and some require you to return a value. This simple module sends the text "goal." to the arena that the player who scored a goal is in. Check out the [[Callbacks]] page for a list of callbacks and the arguments they take.
 === Commands ===

@@ Line 251: / Line 251: @@
 <pre>
 def make_hello_timer(initial, interval, arena):
-     def timer():
+     def timer(arena):
          # announce
          chat.SendArenaMessage(arena, "hello")

@@ Line 244: / Line 244: @@
 Good for checking if a game is over yet. '''A reference to the timer is returned and must be retained''' (you can use per-arena data to store it). Losing the reference will cancel the timer.
-''initial'' is the time in 1/100th's of a second before the nested function timer() will be called, you can cancel the timer before it is called. ''interval'' is the time gap, again in 1/100th's of a second between all future calls of timer(). So make_hello_timer(100, 200, arena) will make it send the arena message "hello" every 2 seconds starting from 1 second after make_hello_timer() was called.
+''initial'' is the time in 1/100th's of a second before the nested function timer() will be called, you can cancel the timer before it is called. ''interval'' is the time gap, again in 1/100th's of a second between all future calls of timer(). The last parameter is a parameter that is sent to the function. You only get one, so if you need more, put them all in a tuple. So make_hello_timer(100, 200, arena) will make it send the arena message "hello" every 2 seconds starting from 1 second after make_hello_timer() was called.
 The third argument to set_timer (''interval'') can be omitted and it will be assumed to be the same as ''initial''.
@@ Line 256: / Line 256: @@
          # non-repeating timer. return 1 for it to be called after the next interval
          return 0
-     return set_timer(timer, initial, interval)
+     return set_timer(timer, initial, interval, arena)
 def somefunc(arena):

@@ Line 64: / Line 64: @@
 cb1 = reg_callback(CB_GOAL, goal)
 </pre>
-The ref_callback function takes two parameters: An ID for the callback to be created and the function to call when the action is triggered. Different IDs take different parameters, and some require you to return a value.
+The ref_callback function takes two parameters: An ID for the action, which are constants imported from the asss module and begin with "CB_", and the function to call when the action is triggered. Different IDs take different parameters, and some require you to return a value. This simple module sends the text "goal." to the arena that the player who scored a goal is in.
 === Commands ===

@@ Line 53: / Line 53: @@
 The bread and butter of most custom modules.
 === Callbacks ===
 <pre>
 from asss import *
@@ Line 63: / Line 64: @@
 cb1 = reg_callback(CB_GOAL, goal)
 </pre>
 === Commands ===

@@ Line 237: / Line 237: @@
      return players[0]
 </pre>
 === Timers ===

@@ Line 140: / Line 140: @@
 === Persistent per-player data ===
-<div style="color: red; font-weight: bold; border: thin solid; padding: 5px 5px 5px 5px">Note this has changed since 1.4.2. See bin/fg_turf.py for the latest implementation. Or the example at: http://forums.minegoboom.com/viewtopic.php?p=63321#63321</div>
+ASSS has built in mechanisms for saving data per player and per arena across sessions (users logging off or server restarting).
-ASSS has built in mechanisms for saving data per player and per arena across sessions (users logging off or server restarting).
+Note: ASSS must be compiled with the berkeleydb option for persistent data to be available.
-You need to provide three functions that will be called by ASSS to save, restore and clear the data. The example below is a complete module.
+Since 1.4.2, persistent data functions are stored in classes. The example below is a complete module.
 <pre>
 # each player can save a note that only they can see
@@ Line 166: / Line 166: @@
 # returning None means "don't store a record in the database,
 # and delete any record that's there already".
-def getpd(p):
+class persistent_note:
-     return p.note
+     key = 1234
-# restore the data for player p
+    def getpd(p):
-def setpd(p, d):
+        return p.note
-# reset/clear the data for player p
+    # restore the data for player p
-def clearpd(p):
+    def setpd(p, d):
-    p.note = None
+        p.note = d
-mypd = reg_player_persistent(
+    # reset/clear the data for player p
-, INTERVAL_FOREVER, PERSIST_GLOBAL,
+    def clearpd(p):
-	getpd, setpd, clearpd)
+        p.note = None
 </pre>
 Ideally you should load the module when the server starts. Alternatively if you load it dynamically you can kick everyone (not desirable) or alter the code to catch AttributeError when it attempts to read from the per player data ''.note''.
-Taking a look at ''reg_player_persistent'' the number ''7890'' is arbitrary, but must be unique for every module using persistent data. Low numbers are reserved for the core modules. ''INTERVAL_FOREVER'' is how long this data will be kept for. Interestingly the INTERVAL_* constants are defined in statcodes.h, not persist.h. ''PERSIST_GLOBAL'' is defined in persist.h. Here are the respective code extracts (as of Feb 7 2005).
+Here are some of the intervals and their meanings.
-	/* these are shared between arenas with the same arenagrp */
+*INTERVAL_FOREVER: I discussed this in the example.
-	INTERVAL_FOREVER = 0,
+*INTERVAL_RESET: Every time the server goes through a reset, the data is cleared.
-	INTERVAL_RESET,
+*INTERVAL_MAPROTATION: Every time the map changes, the data is cleared.
-	PERSIST_ALLARENAS,
+If you define data with these intervals, the data is not stored for the whole zone, rather just the arena the module is attached to.
-	PERSIST_GLOBAL
+*INTERVAL_GAME: After the flag game is over, the data is cleared.
-	/* using this for scope means per-player data shared among all arenas */
+*INTERVAL_FOREVER_NONSHARED: Same as forever, only that it is not shared with other arenas.
 === Attach/Detach ===

@@ Line 127: / Line 127: @@
 === Per-player/arena data ===
-Use this to store game state, player score, etc.
+Use this to store game state, player score, etc. Note that the data is deleted after the server goes down or the player logs out.
 <pre>
 def shipchange(p, newship, newfreq):

@@ Line 259: / Line 259: @@
 def somefunc(arena):
      # create a hello timer that will execute after 1 second, and then every
-     #  2 seconds until cancelled. timers can cancel themselves, see above.
+     #  2 seconds until canceled. timers can cancel themselves, see above.
      myref = make_hello_timer(100, 200, arena)
@@ Line 282: / Line 282: @@
      return success
 </pre>
-It is a good idea to cache ''rgn'' within [[#Per-player.2Farena_data|per-arena data]] so you don't add unecessary load to the server looking it up everytime.
+It is a good idea to cache ''rgn'' within [[#Per-player.2Farena_data|per-arena data]] so you don't add unnecessary load to the server looking it up every time.
 You might come across a region callback when browsing the .h files. This is currently (1.4.2) not available in python.

@@ Line 326: / Line 326: @@
 == Trouble shooting ==
-If code won't run at all check to see if there is a mix of tabs and spaces used for indenting. If so convert all indents to the same type (tabs or spaces). It may not be necessary to do this for the entire module, just in affected functions.
+If code won't run at all check to see if there is a mix of tabs and spaces used for indenting (SyntaxError: invalid syntax). If so convert all indents to the same type (tabs or spaces). It may not be necessary to do this for the entire module, just in affected functions.
 Look at the asss console for execution errors (at the time of writing not all errors are relayed to logged in staff), and if that doesn't help, add some chat.SendArenaMessage(ALLARENAS, "i'm at line ...") type messages to locate the buggy piece of code.