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.

← Older revision		Revision as of 23:33, 13 November 2008
Line 64:		Line 64:
	cb1 = reg_callback(CB_GOAL, goal)		cb1 = reg_callback(CB_GOAL, goal)
	</pre>		</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 ===		=== Commands ===

Initrd.gz: /* Timers */

2008-11-08T02:14:05Z

Timers

← Older revision		Revision as of 02:14, 8 November 2008
Line 251:		Line 251:
	<pre>		<pre>
	def make_hello_timer(initial, interval, arena):		def make_hello_timer(initial, interval, arena):
	def timer():		def timer(arena):
	# announce		# announce
	chat.SendArenaMessage(arena, "hello")		chat.SendArenaMessage(arena, "hello")

Initrd.gz: /* Timers */

2008-11-08T00:52:52Z

Timers

← Older revision		Revision as of 00:52, 8 November 2008
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.		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''.		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		# non-repeating timer. return 1 for it to be called after the next interval
	return 0		return 0
	return set_timer(timer, initial, interval)		return set_timer(timer, initial, interval, arena)

	def somefunc(arena):		def somefunc(arena):

Initrd.gz: /* Callbacks */

2008-10-27T17:07:13Z

Callbacks

← Older revision		Revision as of 17:07, 27 October 2008
Line 64:		Line 64:
	cb1 = reg_callback(CB_GOAL, goal)		cb1 = reg_callback(CB_GOAL, goal)
	</pre>		</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 ===		=== Commands ===

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

2008-10-27T17:04:51Z

Callbacks: Added a small description to Python callbacks.

← Older revision		Revision as of 17:04, 27 October 2008
Line 53:		Line 53:
	The bread and butter of most custom modules.		The bread and butter of most custom modules.
	=== Callbacks ===		=== Callbacks ===
			Callbacks are triggered when a player does something, like killing another player, or scoring a goal.
	<pre>		<pre>
	from asss import *		from asss import *
Line 63:		Line 64:
	cb1 = reg_callback(CB_GOAL, goal)		cb1 = reg_callback(CB_GOAL, goal)
	</pre>		</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.

	=== Commands ===		=== Commands ===

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

2008-10-25T23:17:48Z

Looping over all players

← Older revision		Revision as of 23:17, 25 October 2008
Line 237:		Line 237:
	return players[0]		return players[0]
	</pre>		</pre>
			The for_each_player runs a specified function with the current player as the argument. Since immutable objects cannot be changed inside functions nested inside other functions, you must use a mutable type, such as a list.

	=== Timers ===		=== Timers ===

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

← Older revision		Revision as of 18:34, 11 October 2008
Line 140:		Line 140:
	=== Persistent per-player data ===		=== 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>		<pre>
	# each player can save a note that only they can see		# 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,		# returning None means "don't store a record in the database,
	# and delete any record that's there already".		# and delete any record that's there already".
	~~def getpd(p)~~:		class persistent_note:
	~~return p.note~~		key = 1234
			interval = INTERVAL_FOREVER
			scope = PERSISTENT_ALLARENAS

	~~# restore the data for player p~~		def getpd(p):
	def ~~setpd~~(p~~, d~~):		return p.note
	p.note ~~= d~~

	# ~~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
	~~7890, INTERVAL_FOREVER, PERSIST_GLOBAL,~~		def clearpd(p):
	~~getpd, setpd, clearpd~~)		p.note = None

			mypd = reg_player_persistent(persistent_note())
	</pre>		</pre>
			The function reg_player_persistent automatically grabs the key, interval, scope, and functions from the class.

			*The key distinguishes your module's persistent data from others. Ideally you should define a random constant at the top and use it in all your persistent classes. Note that lower numbers are reserved for ASSS's core modules, so to be safe, I recommend that you pick a number over 1,000.

			*The interval is how often the data stored is reset. INTERVAL_FOREVER means that it is never reset, unless you clear it in your code. There are several other constants besides INTERVAL_FOREVER.

			*The scope tells ASSS if the data stored is only for one arena or for the whole zone. PERSISTENT_ALLARENAS means that the data is available everywhere in your zone, while PERSISTENT_GLOBAL means that there is only one copy per zone.

			Persistent data is stored in the zone's database. The functions set up the variables after ASSS loads the player's values from the database. You can name these functions whatever you want, but they must be in order: get, set, and clear. I will use getdata(), setdata(), and cleardata().

			*getdata() is called when the player leaves the zone or the zone shuts down. The value returned is what gets stored in the database.

			*setdata() is called after cleardata() when a player enters the zone. It has an argument that the others do not have, and that is what ASSS gets from the database for the player. This is where you assign p.data to whatever you want, more often than not the data ASSS gets from the database.

			*cleardata() is called before setdata() when a player enters the zone. Here, you simply define the names you want to use, along with any defaults.

			After the functions automatically run, you can access the data by however you set it in the setdata() or cleardata() functions. Usually this is done with p.data. Once the player logs out, getdata() gives the server the data and the server stores it in the database.

	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''.		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.
	~~<pre>~~
	~~/* these are~~ the ~~possible~~ intervals */
	~~enum interval_t~~
	{
	~~/* pyconst: enum, "INTERVAL_" /~~

	/* ~~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.
	INTERVAL_MAPROTATION,
	~~/* these are not shared between arenas */~~
	~~INTERVAL_GAME = 5,~~
	~~INTERVAL_FOREVER_NONSHARED~~
	};
	~~</pre>~~
	~~<pre>~~
	~~typedef enum persist_scope_t~~
	{
	~~/* pyconst~~: ~~enum~~, ~~"PERSIST_" /~~

	~~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.
	~~/* using this for scope means per-player~~ data ~~in every arena */~~
	~~/* using this~~ for ~~scope means per-arena data will be stored~~
	* per-arena */

	~~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.
	/* ~~using this for scope means per-arena data will be~~ shared ~~among~~
	* all arenas ~~(so it will effectively be global data). */~~
	~~} persist_scope_t;~~
	~~</pre>~~
	~~Note: ASSS must be compiled with the berkeleydb option for persistent data to be available~~.

	=== Attach/Detach ===		=== Attach/Detach ===

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

2008-10-11T17:50:11Z

Per-player/arena data

← Older revision		Revision as of 17:50, 11 October 2008
Line 127:		Line 127:

	=== Per-player/arena data ===		=== 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>		<pre>
	def shipchange(p, newship, newfreq):		def shipchange(p, newship, newfreq):

CypherJF: fixed spellings

2007-10-01T01:50:40Z

fixed spellings

← Older revision		Revision as of 01:50, 1 October 2007
Line 259:		Line 259:
	def somefunc(arena):		def somefunc(arena):
	# create a hello timer that will execute after 1 second, and then every		# 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)		myref = make_hello_timer(100, 200, arena)

Line 282:		Line 282:
	return success		return success
	</pre>		</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.		You might come across a region callback when browsing the .h files. This is currently (1.4.2) not available in python.

Smong: /* Trouble shooting */ added error msg

2007-05-22T10:34:24Z

Trouble shooting: added error msg

← Older revision		Revision as of 10:34, 22 May 2007
Line 326:		Line 326:

	== Trouble shooting ==		== 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.		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.