Clone wiki

asss / Adviser


Advisers are a form of hooking. They are a formal means for modules to extend or modify the behavior of the module that defines the adviser. A module should define an adviser when it implements a feature or behavior that other modules may need to modify in a controlled way.

Properties of advisers

  • They are a collection of functions to be implemented or values to be defined, associated with a type identifier.
  • Typically adviser functions should return data to the caller, either through the function return value, or through a pointer argument.
  • Advisers are not used for event notification, as there is no guarantee that the defining module will consult every adviser. Callbacks should be used instead for event notification.
  • The defining module calls functions in the adviser, like an interface, and they will often call multiple advisers to work on a single request. Unlike interfaces, the goal of advisers is to let the instantiating module influence functionality.
  • Can be implemented several times by many modules on the same scope, there is no real limit to the number of advisers per type.
  • Not all fields necessarily have to be filled in the instance. The defining module must document how its fields are used and verify them.

Naming convention:

  • struct name: A<advisertype>
  • adviser identifier: A_<ADVISERTYPE>
  • adviser version: "advisertype-version"

Adviser types must start with ADVISER_HEAD_DECL

Advisers must start with ADVISER_HEAD_INIT(A_<ADVISERTYPE>) to store the adviser type identifier.


  • game.h defines an Appk adviser.
  • game.c calls a list of Appk advisers to modify its behavior.
  • (not shown: game.c handling EditIndividualPPK)
  • pacifier.c includes game.h and implements and registers an Appk adviser.

Defining an adviser


#define A_PPK "ppk-1"

/** the position packet adviser struct */
typedef struct Appk

	/** Modifies a player's position packet before it is sent out.
	 * The adviser may edit the packet, but should not rely on
	 * this function for notification, as other advisers may be
	 * consulted. Instead the CB_PPK callback should be used for
	 * notification.
	 * @param p the player that the position packet belongs to
	 * @param pos a pointer to the position packet
	void (*EditPPK)(Player *p, struct C2SPosition *pos);
	/** Modifies a player's position packet before it is sent to a specific player.
	 * @param p the player that the position packet belongs to
	 * @param t the player that the position packet will be sent to
	 * @param pos a pointer to the position packet
	 * @param extralen the extra length of the position packet (0 = none, 2 = energy, 10 = epd)
	 * @return TRUE if this function modified the packet, FALSE otherwise
	int (*EditIndividualPPK)(Player *p, Player *t, struct C2SPosition *pos, int *extralen);
} Appk;

Calling advisers


LinkedList advisers = LL_INITIALIZER;
Link *link;
Appk *ppkadviser;
/* consult the PPK advisers allow modules to modify this position packet before we send it to other players */
mm->GetAdviserList(A_PPK, arena, &advisers);
/* FOR EACH ppkadviser in advisers (iterate using link) */
FOR_EACH(&advisers, ppkadviser, link)
	if (ppkadviser->EditPPK)
		ppkadviser->EditPPK(p, pos);
/* at this point, the position packet has been modified by all modules that wanted to,
 * and we will work with it in this form from now on */

Implementing an adviser


/* not actually necessary for core modules, they are all included with asss.h */
#include "game.h"

/* function we will put in the adviser */
void EditPPK(Player *p, struct C2SPosition *pos)
	if (pos->weapon.type != W_NULL)
		/* remove all weapons coming from the player. they will not show up on other player's screens. */
		pos->weapon.type = W_NULL;

/* define the adviser, notice we are not implementing the second function */
local Appk ppkadviser =

Registering an adviser


/* entry point for the 'pacifier' module */
EXPORT int MM_pacifier(int action, Imodman *mm, Arena *a)
	if (action == MM_LOAD)
		/* register our adviser */
		mm->RegAdviser(&ppkadviser, ALLARENAS);
		/* return success */
		return MM_OK;
	else if (action == MM_UNLOAD)
		mm->UnregAdviser(&ppkadviser, ALLARENAS);
		return MM_OK;
	return MM_FAIL;