Difference between revisions of "Module Creation FAQ"

Latest revision as of 02:53, 30 November 2005

This is a general FAQ and there are separate tutorials on writing modules in C and writing modules in Python.

What module and function do I use to send messages to players?

The chat interface, Ichat, is defined in chat.h and is used to send messages of all kinds.

Most of the chat interface functions use printf like syntax in their strings.

NOTE: You must get the I_CHAT interface from the ASSS Module Manager before using it, just like you must on every other interface.

To send a green message to a single player, you should use code similar to one of the following:

chat->SendMessage(p, "This is a message");
chat->SendMessage(p, "This is a message that displays an int. %i", someInt);
chat->SendMessage(p, "This is a message that displays a char array. %s", charArray);

To send a message to an entire arena, one should use code similar to one of the following:

chat->SendArenaMessage(arena, "This is an arena-wide message");
chat->SendArenaMessage(arena, "This is an arena-wide message that displays an int. %i", someInt);
chat->SendArenaMessage(arena, "This is an arena-wide message that displays a char array. %s", charArray);

How do I log events?

The log manager's interface, Ilogman, is defined in logman.h and aids in debugging and notifying zone staff of unusual activity.

There are three log functions that are defined. Log, LogP and LogA. All three have printf like syntaxes (just like the chat interfaces's functions) for easy addition of variable values to add in debugging.

There are five log levels that can be used when calling a log function.

• L_DRIVEL is for meaningless log entries. Things that no sysop will ever care about. Use this level for printing out statements to help in debugging.
• L_INFO is for things that people might care about.
• L_MALICIOUS is for events that shouldn't happen unless someone is trying to hack/cheat. This is sent to online sysops as soon as it is logged (under default settings).
• L_WARN is for things that probably shouldn't happen, but don't make a big difference.
• L_ERROR is for events that are really bad. It is sent to online sysops as soon as it is logged (under default settings).

LogP is the most commonly used logging function. It should be used when you have access to a player pointer and the event relates to that player's actions.

lm->LogP(L_DRIVEL, "my_module_name", p, "A log message attached to Player *p");

LogA is attached to an arena rather than a player. This should be used whenever an event happens inside an arena but is tied to no specific player.

lm->LogA(L_DRIVEL, "my_module_name", arena, "A log message attached to Arena *arena");

Log is attached to neither an arena nor a player.

lm->Log(L_DRIVEL, "<my_module_name> A log message");

How do I warp a player somewhere?

The game interface, Igame defines the function WarpTo that takes a player, an x tile and a y tile.

game->WarpTo(p, 512, 512); //will warp a player to the center of the map

How do I give a player prizes?

The game interface, Igame defines the function GivePrize that takes a Target, a prize type and a prize count.

Target t;
t.type = T_PLAYER;
t.u.p = p;

game->GivePrize(&t, 21, 5); /* give Player p 5 repels (prize #21) */

How do I set a player's ship?

extract from defs.h

/** ship names */
enum
{
	/* pyconst: enum, "SHIP_*" */
	SHIP_WARBIRD = 0,
	SHIP_JAVELIN,
	SHIP_SPIDER,
	SHIP_LEVIATHAN,
	SHIP_TERRIER,
	SHIP_WEASEL,
	SHIP_LANCASTER,
	SHIP_SHARK,
	SHIP_SPEC
};

Replace ship with one of the enum's, fx: SHIP_WARBIRD.

game->SetShip(p, ship);

How do I set a player's freq?

game->SetFreq(p, freq); /* Player *p, int freq (typically in the range 0-9999) */

See game.h

How do I check when a player has entered a region?

ASSS has a callback for when an ASSS Region action(player enterence or exit) occurs. This callback is CB_REGION and the function is defined as

local void region_cb(Player *p, Region *rgn, int x, int y, int entering)

For information on how to write and use callbacks, see Writing Modules.