Writing Modules for Hyperspace

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 sensible 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;
}

Required Files

Here is hscore.h:

#include "hscore_types.h"

#include "hscore_money.h"
#include "hscore_items.h"

Here is hscore_types.h:

#ifndef HSCORE_TYPES_H
#define HSCORE_TYPES_H

typedef enum EventAction
{
	//removes event->data amount of the items from the ship's inventory
	ACTION_REMOVE_ITEM = 0,

	//removes event->data amount of the item's ammo type from inventory
	ACTION_REMOVE_ITEM_AMMO,

	//sends prize #event->data to the player
	ACTION_PRIZE,

	//sets the item's inventory data to event->data. This is useful with
	//the "purchace" event.
	ACTION_SET_INVENTORY_DATA,

	//does a ++ on inventory data.
	ACTION_INCREMENT_INVENTORY_DATA,

	//does a -- on inventory data. A "datazero" event may be generated as a result.
	ACTION_DECREMENT_INVENTORY_DATA,

	//Specs the player.
	ACTION_SPEC,

	//sends a shipreset packet and reprizes all items (antideath, really)
	ACTION_SHIP_RESET

	//we need a lot more
} EventAction;

typedef struct Event
{
	char event[16]; //something like "death" or "datazero"
	EventAction action;

	int data; //action dependent

	char message[200]; //if == to "" then nothing will be sent.
} Event;

typedef struct Property
{
	char name[16];
	int value;
} Property;

typedef struct ItemType
{
	char name[32];
	int max; //maximum total of this item type on a ship before ?buy denies purchace

	int id; //MySQL use only
} ItemType;

typedef struct Item
{
	char name[16];
	char shortDesc[32]; //displayed inline in the ?buy menu
	char longDesc[200]; //displayed as part of ?iteminfo
	int buyPrice;
	int sellPrice;

	int expRequired; //requirement to own

	int shipsAllowed; //bit positions represent each ship. bit 0 = warbird.

	LinkedList propertyList;

	LinkedList eventList;

	ItemType *type1, *type2;
	int typeDelta1, typeDelta2;

	int max;

	//if changes to this item should be delayed until a complete save (like on exit).
	//This is a necessity when dealing with ammo. We don't want to update MySQL every
	//time a gun is fired.
	int delayStatusWrite;

	struct Item *ammo; //can be NULL, only for use by events.
	int ammoID; //used for post processing ONLY

	int id; //MySQL use only
} Item;

typedef struct InventoryEntry
{
	Item *item;
	int count;

	int data; //persistent int for use by the event system.
} InventoryEntry;

typedef struct ShipHull
{
	LinkedList inventoryEntryList;

	//NOTE: no need for ship #, as it's defined by the array index (when loaded by hscore_database)

	//if we compile a hashmap of properties, it can go in here.

	int id; //MySQL use only
} ShipHull;

typedef struct Category
{
	char name[32]; //displayed on ?buy
	char description[64]; //displayed inline on the ?buy menu

	LinkedList itemList; //a list of member items that are displayed

	int id; //mysql use
} Category;

typedef struct Store
{
	char name[32]; //displayed in ?buysell location errors
	char description[200]; //displayed in ?storeinfo
	char region[16]; //region that defines the store

	LinkedList itemList; //a list of items that can be purchaced here

	int id; //mysql use
} Store;

#endif //HSCORE_TYPES_H

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.