Difference between revisions of "Writing Modules for Hyperspace"

Revision as of 11:59, 11 January 2005

Getting Started

The first thing you should do is check with Dr Brain to make sure someone else isn't already making a similar module. The best way to contact him is either in game (PM/?message) or via AIM/ICQ (check the Hyperspace news file).

General Info

In general, hard coding values is frowned upon. Please try to use the arena and global configs wherever possible. Put a sensable default into the GetInt so that not every config entry needs to be present for the module to work.

Naming

Because of module naming conflicts, all official Hyperspace related modules are prefixed with hs_. So, for example, a kill spree module becomes hs_spree. This is not required for module submissions. You are free to name your module whatever you wish.

Style

There is a Hyperspace standard style for formatting code, but it is completely optional. You should make your interface headers easy to read, though.

Here is an example of the Hyperspace official style:

hs_twowords.h:

#ifndef HS_TWOWORDS_H
#define HS_TWOWORDS_H

#define I_HS_TWOWORDS "hs_twowords-1"

typedef struct Ihstwowords
{
	INTERFACE_HEAD_DECL

	int (*interfaceFunction)(Player *p);
} Ihstwowords;

#endif //HS_TWOWORDS_H

hs_twowords.c:

#include <string.h> //optional. others added as needed

#include "asss.h"
#include "hscore.h"
#include "hs_twowords.h"

//modules
local Imodman *mm;
local Ilogman *lm;
local Ichat *chat;
local Iconfig *cfg;
local Icmdman *cmd;
local Iplayerdata *pd;

//interface prototypes
local int interfaceFunction(Player *p);

local helptext_t twoWordsHelp =
"Targets: player\n"
"Args: none\n"
"Who knows? This is just a template file.\n";

local void twoWordsCommand(const char *command, const char *params, Player *p, const Target *target)
{
	if (target->type == T_PLAYER) //private command
	{
		Player *t = target->u.p;

		//do something
	}
	else //not private
	{
		chat->SendMessage(p, "You must target a player.");
	}
}

local int interfaceFunction(Player *p)
{
	if (something) //space between if and ()
	{
		//do something
	}
}

local Ihstwowords interface =
{
	INTERFACE_HEAD_INIT(I_HS_TWOWORDS, "hs_twowords")
	interfaceFunction
};

EXPORT int MM_hs_twowords(int action, Imodman *_mm, Arena *arena)
{
	if (action == MM_LOAD)
	{
		mm = _mm;

		lm = mm->GetInterface(I_LOGMAN, ALLARENAS);
		chat = mm->GetInterface(I_CHAT, ALLARENAS);
		cfg = mm->GetInterface(I_CONFIG, ALLARENAS);
		cmd = mm->GetInterface(I_CMDMAN, ALLARENAS);
		pd = mm->GetInterface(I_PLAYERDATA, ALLARENAS);

		if (!lm || !chat || !cfg || !cmd || !pd)
		{
			mm->ReleaseInterface(lm);
			mm->ReleaseInterface(chat);
			mm->ReleaseInterface(cfg);
			mm->ReleaseInterface(cmd);
			mm->ReleaseInterface(pd);

			return MM_FAIL;
		}

		mm->RegInterface(&interface, ALLARENAS);

		cmd->AddCommand("twowords", twoWordsCommand, ALLARENAS, twoWordsHelp);

		return MM_OK;
	}
	else if (action == MM_UNLOAD)
	{
		if (mm->UnregInterface(&interface, ALLARENAS))
		{
			return MM_FAIL;
		}

		cmd->RemoveCommand("twowords", twoWordsCommand, ALLARENAS);

		mm->ReleaseInterface(lm);
		mm->ReleaseInterface(chat);
		mm->ReleaseInterface(cfg);
		mm->ReleaseInterface(cmd);
		mm->ReleaseInterface(pd);

		return MM_OK;
	}
	return MM_FAIL;
}

Money and Experience

Money and experience points (aka exp) are what make the Hyperspace world go 'round. Nearly every Hyperspace module has some dealings with money/exp transactions of some kind.

Here is the hscore_money.h contents:

#ifndef HSCORE_MONEY_H
#define HSCORE_MONEY_H

#define I_HSCORE_MONEY "hscore_money-1"

typedef enum MoneyType
{
	//for /?give
	MONEY_TYPE_GIVE = 0,

	//for /?grant
	MONEY_TYPE_GRANT,

	//for ?buy and ?sell
	MONEY_TYPE_BUYSELL,

	//for money from kills
	MONEY_TYPE_KILL,

	//for money from flag games
	MONEY_TYPE_FLAG,

	//for money from soccer games
	MONEY_TYPE_BALL,

	//for money from module driven events
	MONEY_TYPE_EVENT
} MoneyType;

#define MONEY_TYPE_COUNT 7

typedef struct Ihscoremoney
{
	INTERFACE_HEAD_DECL

	void (*giveMoney)(Player *p, int amount, MoneyType type);
	void (*setMoney)(Player *p, int amount, MoneyType type); //beware. know what you're doing

	int (*getMoney)(Player *p);
	int (*getMoneyType)(Player *p, MoneyType type); //used only for /?money -d

	void (*giveExp)(Player *p, int amount);
	void (*setExp)(Player *p, int amount); //beware. know what you're doing

	int (*getExp)(Player *p);
} Ihscoremoney;

#endif //HSCORE_MONEY_H

Giving exp

money->giveExp(p, 10); //gives player p 10 exp

Giving money

The first thing to decide is which money type to give. This is mainly used for tracking purposes. If in doubt, choose MONEY_TYPE_EVENT.

• MONEY_TYPE_GIVE is for money moving from one player to another.
• MONEY_TYPE_GRANT is for money coming from a grant command
• MONEY_TYPE_BUYSELL is for ?buying and ?selling.
• MONEY_TYPE_KILL is for money gained from kills.
• MONEY_TYPE_FLAG is for money earned from winning flag games or other flag rewards.
• MONEY_TYPE_BALL is for money received from goals.
• MONEY_TYPE_EVENT is for subarena events.

Then you can simply call:

money->giveMoney(p, 1000, MONEY_TYPE_EVENT); //gives player p $1000

Using Items

Items are the most important part of Hyperspace after money and exp. There are two parts of items that addon modules will use. These are checking for properties and calling events.

Here is a copy of hscore_item.h:

#ifndef HSCORE_ITEMS_H
#define HSCORE_ITEMS_H

#define I_HSCORE_ITEMS "hscore_items-3"

typedef struct Ihscoreitems
{
	INTERFACE_HEAD_DECL

	int (*getItemCount)(Player *p, Item *item, int ship);
	void (*addItem)(Player *p, Item *item, int ship, int amount);

	Item * (*getItemByName)(const char *name, Arena *arena);

	int (*getPropertySum)(Player *p, int ship, const char *prop); //properties ARE case sensitive

	void (*triggerEvent)(Player *p, int ship, const char *event);
	void (*triggerEventOnItem)(Player *p, Item *item, int ship, const char *event);

	int (*getFreeItemTypeSpots)(Player *p, ItemType *type, int ship);

	//more required, i'm sure
} Ihscoreitems;

#endif //HSCORE_ITEMS_H

Item properties

Most items define properties that are used to change the player's ship. Properties are totalled for each ship and are checked per ship rather than per item. Most properties are related to the spawning module. However, any item can define custom properties.

item->getPropertySum(p, p->p_ship, "someproperty"); //Beware of spectators.

Item events

Items define actions that happen on certain events. Any module can trigger an event. Some modules, for example, have actions on the death event. Triggering an event is as simple as making a function call to the hscore_item module. If no items have actions on the called event, nothing will happen (so make sure you don't typo the event name).

item->triggerEvent(p, p->p_ship, "someevent"); //Beware of spectators.

Submission

Once your module is working properly and seems to have no bugs, then you can submit the source to Dr Brain or MichaelG for a source check. Once that's completed, the module will be compiled for the Hyperspace server and installed.