ASSS Wiki - User contributions [en]

Writing Advanced Modules In C

2010-12-29T21:33:36Z

BaK: /* Passing Multiple Arguments To Commands */ fixed a bug, a memory leak, and made it cross platform

This tutorial explains how to write advanced modules in C. It is assumed you know how to code and are familiar with how the ASSS code works.

This tutorial is a continuation of [[Writing Modules In C]].

Some useful references:

http://qnxcs.unomaha.edu/help/product/neutrino/lib_ref/summary.html

http://www.cplusplus.com/reference/

== Passing Data To Timers ==

<pre>
typedef struct ThisIsData
{
Player *p;
int number;
} ThisIsData;

local int timerfunc(void *vp) //vp is void pointer, just an address that can point anywhere
{
ThisIsData *tid=(ThisIsData*)vp; //we know it points to our data

if(tid->number == 10)
{
//if it worked anything in here will work too
}

//return 1 if you want timer to run again, or 0 if you want it to be removed
int returnValue = 0;

if (returnValue == 0)
afree(tid); // free the data we have previously allocated

return returnValue;
}

anotherfunction()
{
ThisIsData *tid=amalloc(sizeof(ThisIsData)); //we must allocate memory because anything in this function is destroyed when it ends

tid->number=10

//now set timer to activate in 1000 centiseconds, then repeat every 100.
//we are also sending the address of the memory we just allocated.
ml->SetTimer(timerfunc,1000,100,tid,0);
}
</pre>

== Passing Multiple Arguments To Commands ==

Since the words are read one by one, then checked against the whole list, they can be in any order!

<pre>
// define macros for comparing strings that work for both linux and windows
#ifdef WIN32
#define STRCASECMP stricmp
#define STRNCASECMP strnicmp
#else
#define STRCASECMP strcasecmp
#define STRNCASECMP strncasecmp
#endif

local void examplecommand(const char *command, const char *params, Player *p, const Target *t)
{
char *sentence=strdup(params); //strdup clones a string because strtok replaces " " with a \0
char *word=strtok(sentence," "); //strtok reads everything until first \0 into word

while(word) //while word != null
{
if(!STRNCASECMP(word,"a=",2)) //STRNCASECMP is a case insensitive comparison that returns 0 if the same, with a number
{
//do stuff if first 2 letters of word are 'a' then '='

word+=2; //like move start of word 2 letters forward
int check=atoi(word); //then read a number
}
else if(!STRNCASECMP(word,"bc=",3))
{
//do stuff if first 3 letters of word are 'b' then 'c' then '='

word+=3; //make sure you move it 3 letters and not 2
int check=atoi(word); //then read a number
}
else if(!STRCASECMP(word,"-de")) //thats STRCASECMPwith no N, it checks the whole thing
{
//do stuff if word is "-de"
}
word=strtok(NULL," "); //advance to next word, or set word to null if none left
}

afree(sentence); // since we allocated a string with strdup, we must free the associated memory manually
}
</pre>

== Creating Callbacks ==

Write me!

<pre>
//example code goes here
</pre>

== Creating Interfaces ==

Cover overwriting existing interfaces to replace old modules.
Write me!

<pre>
//example code goes here
</pre>

== Sending Packets To Players ==

Cover position packets, weapon packets, clientset stuff, etc.
Write me!

<pre>
//example code goes here
</pre>

== Using Advisors ==

Write me!

<pre>
//example code goes here
</pre>

== Creating Advisors ==

Write me!

<pre>
//example code goes here
</pre>

[[Category:Module]]
[[Category:Guides]]

Writing Advanced Modules In C

2010-12-29T21:25:06Z

BaK: /* Passing Data To Timers */ let's not have memory leaks in sample code

This tutorial explains how to write advanced modules in C. It is assumed you know how to code and are familiar with how the ASSS code works.

This tutorial is a continuation of [[Writing Modules In C]].

Some useful references:

http://qnxcs.unomaha.edu/help/product/neutrino/lib_ref/summary.html

http://www.cplusplus.com/reference/

== Passing Data To Timers ==

<pre>
typedef struct ThisIsData
{
Player *p;
int number;
} ThisIsData;

local int timerfunc(void *vp) //vp is void pointer, just an address that can point anywhere
{
ThisIsData *tid=(ThisIsData*)vp; //we know it points to our data

if(tid->number == 10)
{
//if it worked anything in here will work too
}

//return 1 if you want timer to run again, or 0 if you want it to be removed
int returnValue = 0;

if (returnValue == 0)
afree(tid); // free the data we have previously allocated

return returnValue;
}

anotherfunction()
{
ThisIsData *tid=amalloc(sizeof(ThisIsData)); //we must allocate memory because anything in this function is destroyed when it ends

tid->number=10

//now set timer to activate in 1000 centiseconds, then repeat every 100.
//we are also sending the address of the memory we just allocated.
ml->SetTimer(timerfunc,1000,100,tid,0);
}
</pre>

== Passing Multiple Arguments To Commands ==

Since the words are read one by one, then checked against the whole list, they can be in any order!

<pre>
local void examplecommand(const char *command, const char *params, Player *p, const Target *t)
{
char *sentence=strdup(params); //strdup clones a string because strtok replaces " " with a \0
char *word=strtok(params," "); //strtok reads everything until first \0 into word

while(word) //while word != null
{
if(!strnicmp(word,"a=",2)) //strnicmp is a case insensitive comparison that returns 0 if the same, with a number
{
//do stuff if first 2 letters of word are 'a' then '='

word+=2; //like move start of word 2 letters forward
int check=atoi(word); //then read a number
}
else if(!strnicmp(word,"bc=",3))
{
//do stuff if first 3 letters of word are 'b' then 'c' then '='

word+=3; //make sure you move it 3 letters and not 2
int check=atoi(word); //then read a number
}
else if(!stricmp(word,"-de")) //thats stricmp with no N, it checks the whole thing
{
//do stuff if word is "-de"
}
word=strtok(NULL," "); //advance to next word, or set word to null if none left
}
}
</pre>

== Creating Callbacks ==

Write me!

<pre>
//example code goes here
</pre>

== Creating Interfaces ==

Cover overwriting existing interfaces to replace old modules.
Write me!

<pre>
//example code goes here
</pre>

== Sending Packets To Players ==

Cover position packets, weapon packets, clientset stuff, etc.
Write me!

<pre>
//example code goes here
</pre>

== Using Advisors ==

Write me!

<pre>
//example code goes here
</pre>

== Creating Advisors ==

Write me!

<pre>
//example code goes here
</pre>

[[Category:Module]]
[[Category:Guides]]

Payday Loans - How to Get a Bad- Credit personal Loan

2010-12-29T21:13:41Z

BaK: Payday Loans - How to Get a Bad- Credit personal Loan moved to Spam page del me: spam page, i dont know how to delete

#REDIRECT [[Spam page del me]]

MERVBot Tutorial

2009-08-01T07:25:40Z

BaK: /* File stream input */ typo in comment

This tutorial is based on the ever-popular MERVBot Tutorial by Underlord. It has since been updated to reflect new changes with MervBot. To see examples of how to use this instruction, see [[MERVBot Example Code]].

This tutorial also assumes that you have a basic knowledge of C++. If you don't, check out cplusplus.com's great [http://www.cplusplus.com/doc documentation].

==Setting up a MERVBot (plugin)==

[http://mervbot.com MERVBot download site]

===Obtaining MERVBot===

* Download the [http://mervbot.com/files/MERVBot.rar latest build].
* Unrar MERVBot.rar into a new folder. (example c:\program files\continuum\mervbot)
* Unzip src.zip into "src" subfolder of that new folder (example c:\program files\continuum\mervbot\src)

===Preparing to write a plugin===

''Note:'' if you only want to execute someone's premade plugin (.dll), skip to [[MERVBot Tutorial#Run your bot dll|step 4]], otherwise continue to learn how to make your own bot

Download [http://catid.sscontinuum.com/files/Tutorial.rar DLL-plugin Tutorial] and unzip Tutorial.zip (containing spawn.h, spawn.cpp, and command.cpp) into a "tutorial" subfolder of that new folder. (example c:\program files\continuum\mervbot\src\tutorial).

''File descriptions:''
* spawn.h = declare/initialize globals
* command.cpp = code for commands coming into bot (ie /!help, /!play, etc)
* spawn.cpp = code that interacts with bot spawns

===Microsoft Visual c++===

<ol>
<li>Start Visual Studios 6.0.
<li>Click the Drop Down Menu labeled "File" at the top left of your screen.
<li>Click "New".
<li>On the next screen that comes up, choose from the Project tab, then Win32 Dynamic-Link Library
<li>Select the "/src" folder as the base folder (example c:\program files\continuum\mervbot\src)
<li>Name your project "mybot". This will make a "mybot" subfolder in your "src" folder. Click OK. (example creates c:\program files\continuum\mervbot\src\mybot)
<li>Choose to create an "Empty DLL project".
<li>Click "Finish".
<li>Click the Drop Down Menu labbled "Project".
<li>Click "Add To Project Files"
<li>Copy only spawn.h, spawn.cpp, and command.cpp from the "tutorial" folder into the this new folder. (example from c:\program files\continuum\mervbot\src\tutorial to c:\program files\continuum\mervbot\src\mybot)
<li>Click the Drop Down Menu labelled "Build".
<li>Click "Build (dll name)" - where (dll name) is "mybot"
<li>Go into your "mybot" folder and look for a folder named "Debug"
(example c:\program files\continuum\mervbot\src\mybot\debug)
<li>Your new DLL will be in that folder. (example mybot.dll)
<li>Copy mybot.dll to your base folder that has mervbot.exe in it (example c:\program files\continuum\mervbot)
</ol>

===Run your bot dll===

To run your bot you need your DLL (mybot.dll), Commands.txt, MERVBot.exe, MERVBot.ini, Operators.txt, Spawns.txt, and zlib.dll all in one folder (example c:\program files\continuum\mervbot).

<ol>
<li>Edit spawns.txt. '''Read every word of spawns.txt to find out what needs to go in there.'''

 
''Example:''
<pre>2v2-Bot-League : botpw : 2v2a : 2v2league : staffpw</pre>

''Note:'' The bot will attempt to create the name if it doesn't exist already.

<li>Edit MERVBot.ini
 
 
<pre>[Login]
Zone=216.33.98.254:21000 // your zone IP:PORT available from zone.dat in Continuum dir
</pre>

<li>Edit operators.txt. '''Read every word of operators.txt to find out what needs to go in there.''' 

''Example:''
<pre>
4:my_name:
4:another_sysop:
3:other_person:
</pre>

<li>Make sure the bot is on vip.txt or has smod+ access, then run MERVBot.exe.

<li>You can now edit your plugin code by opening "mybot.dsw" (example c:\program files\continuum\mervbot\src\mybot\mybot.dsw) in Microsoft Visual C++. Edit the spawn.h, spawn.cpp, and command.cpp to create your plugin, then build, copy your updated DLL to your MERVBot.exe folder and then execute the bot. Use the tutorial to get ideas on how to implement certain types of features into the bot.

</ol>

==Player Commands - (command.cpp)==

This section describes how to implement player commands into your plugin. Commands are sent to the botInfo::gotCommand function in command.cpp.

Example (makes bot reply to !test with "hi"):
<pre>
void botInfo::gotCommand(Player *p, Command *c) {
switch (p->access)
{
case OP_Moderator:
{
// handle moderator-operator commands here.
}
case OP_Player: //appropriate staff rank here.
{
if (c->check("test")) //replace "test" with whatever command you want
{
//put your command code here
sendPrivate(p,"hi"); //example
}
}
</pre>

===How to have commands with numerical parameters===
Example (!test #):
<pre>
if (c->check("test")) { // reads in test #, default to 1 if invalid number input
int temp = 1;

if (isNumeric(c->final))
temp = atoi(c->final);
</pre>

===How to have player name as input===
Example (!rank player):
<pre>
if (c->check("rank"))
{
String player_name = c->final;

if (player_name.IsEmpty()) // default name to self if invalid name
player_name = p->name;
</pre>

===How to have multi-parameter input===

Use the CRT function sscanf() to scan the string for the values.

Example (!squads squadA vs squadB ''or'' !squads teamA:squadA:teamB:squadB):
<pre>
else if (c->check("squads"))
{
char squadA[20], squadB[20];
int teamA, teamB;

strncpy(squadA, "", 20);
strncpy(squadB, "", 20);

int n_found;

//Note: %[A-Za-z ] is equivalent to %s, but allows an internal space.

//scan the string for the two squads separated by " vs "
n_found = sscanf(c->final, "%[A-Za-z ] vs %[A-Za-z ]", squadA, squadB);

//if that fails, scan the string for freqA:squadA:freqB:squadB
if (n_found < 2)
sscanf(c->final, "%d:%[A-Za-z ]:%d:%[A-Za-z ]", &teamA, squadA, &teamB, squadB);
}
</pre>

===Help Menu===
When a player sends !help to the bot, MERVBot calls botInfo::gotHelp() in each plugin loaded.
<pre>
void botInfo::gotHelp(Player *p, Command *c)
{
if (!*c->final)
{
sendPrivate(p, "4v4 Bot General Commands:");
sendPrivate(p, "------------------------");
sendPrivate(p, "!caps - get captain names");
sendPrivate(p, "!roster <squad> - get roster of a squad");
sendPrivate(p, "!schedule- get current schedule");
sendPrivate(p, "!score - get current score");
</pre>

==Event Calls==

MERVBot is event based, so when making a bot you need to decide what will happen at certain events. Normal plugins need to consider what happens when bot enters arena, player enters arena, player leaves arena, player events like kill, shipchange, teamchange, spec, move then any other relevant events to your bot. Just worry about events that are relevant to the tasks your bot is doing.

MERVBot sends events to botInfo::gotEvent() in spawn.cpp. Each supported event is already present and categorized in gotEvent(), along with the paramters that MERVBot sends with the event. When a plugin wants the bot to do something, it sends tell(event) to the bot.

See dllcore.h for a list of current events and their descriptions. Dllcore.h also contains functions (like makeFollowing) to make events to send back to the bot via tell().

<pre>tell(makeFollowing(false));</pre>

==The Messaging System==

Private message - void sendPrivate(Player *player, char *msg);

''Examples:''

<pre>
sendPrivate(p,"hi");

String s="test";
sendPrivate(p,s);

String s="test";
s += "ing";
sendPrivate(p,s);

char captain1[20];
char captain2[20];
strncpy(captain1,"",20);
strncpy(captain2,"",20);
sendPrivate(p,(String) captain1 + " and " + (String) captain2 + " are the captains.");
</pre>

Team message - void sendTeamPrivate(Uint16 team, char *msg); 
<blockquote>Examples: 
a) sendTeamPrivate(8025,"hi spec freq"); 
b) Uint16 test=0; sendTeamPrivate(test,"hi freq 0"); 
</blockquote>

Public message - void sendPublic(char *msg); 
<blockquote>Example: sendPublic("*arena " + (String) p->name + " is now a captain"); 
</blockquote>
Chat channel message - void sendChannel(char *msg); 
<blockquote>Example: sendChannel("hi chat channel"); 
</blockquote>
Remote private message - void sendRemotePrivate(char *name, char *msg); 
<blockquote>Example: sendRemotePrivate("Player01", "hi"); 
</blockquote>

Note: to have bot print several lines of text fast it needs sysop in the
arena (sysop in arena bot first spawns to also) otherwise it'll print slow to avoid being
kicked for spam

===Output of data in messages===
An example of using normal strings to output data/messages.
<pre>
// does *arena X pilots left in game
// NOTE: variable temp needs to be defined with some value

String s = "*arena ";
s += temp;
s += " pilots left in the game.";

sendPublic(s);
</pre>
Or,
<pre>
//NOTE: this can be considered inefficient.

sendPublic("*arena " + (String)temp + " pilots left in the game");
</pre>

An example using sprintf to align/space data, where output data will be in this approximate format.
<pre>
// output data will be in this approximate format (not lined up perfectly because of html)
// --------------------------------------------------------------------------------------
// Squad: squadname PTS FPTS K D DMG DEALT TAKEN F FK FLT
// --------------------------------------------------------------------------------------
// PlayerA 10000 500 116 101 9999 99999 10 150 980:55
// PlayerB 500 200 7 5 9999 99999 5 3 0:04

char str[255];
sendPublic("*arena--------------------------------------------------------------------------------");

sprintf(str, "*arena Squad: %-20s PTS FPTS K D DMG DEALT TAKEN F FK FLT",
freqs[freq].freqname
);

sendPublic(str);

sendPublic("*arena--------------------------------------------------------------------------------");

// assuming existing freqs struct with data
for (pilot=freqs[freq].playercount-1; pilot>=0; pilot--)
{
// on freq squad so print stats
char outString[255];

sprintf(outString, "*arena %-20s %12d %8d %3d %3d %10d %6d %2d %3d %3d:%02d",
freqs[freq].pilots[pilot].name,
freqs[freq].pilots[pilot].points,
freqs[freq].pilots[pilot].flagpoints,
freqs[freq].pilots[pilot].kills,
freqs[freq].pilots[pilot].deaths,
freqs[freq].pilots[pilot].dmgdealt,
freqs[freq].pilots[pilot].dmgtaken,
freqs[freq].pilots[pilot].flags,
freqs[freq].pilots[pilot].flagkills,
freqs[freq].pilots[pilot].flagtime /60,
freqs[freq].pilots[pilot].flagtime %60
);

sendPublic(outString);
}

// Notes: sprintf format = sprintf(output char string, spacing, variables)
// Notes: s = chars, d = integer, - = left align, right align default
// Notes: doing %02d = put 0 in front if not 2 digits, %3d:%02d makes 0:04 format
</pre>

==Time==

Each time MERVBot sends an EVENT_Tick to a plugin (once a second), the default handler code decrements each value in an array of countdowns. You can modify the number of countdowns and add code to occur at a specific value for one of the countdowns.

Setup number of timers and initialize in spawn.h:
<pre>
class botInfo
{
#define COUNTDOWNS 10 // how many countdowns you want
int countdown[COUNTDOWNS]; // this gives you 10 timers

// unrelated code

public:
botInfo(CALL_HANDLE given)
{
countdown[0] = 0;
countdown[1] = 60; // 60 seconds
//
// initialize values
//
countdown[9] = 5*60; // 5 minutes
</pre>
Using timer functions in spawn.cpp:
<pre>
case EVENT_Tick:
{
for (int i = 0; i < COUNTDOWNS; ++i) //cycles through each countdown you have
--countdown[i]; //note that countdowns will continue decrementing past 0.

if (countdown[1] == 2) // when timer #1 hits two seconds
{
// do stuff here when timer #1 hits 2 seconds
// example: sendPublic("two seconds left, setting timer to 1 minute");
// example: countdown[1] = 60; // change timer #1 value
}
</pre>

You can then have events (such as EVENT_PlayerDeath) change the value of a countdown to make the bot do something a set time after an event occurs.

=== Tracking time not using countdown[n] ===

This is a solution to a common problem of determining the amount of time it takes for something to occur. Using basic math, we record a start-time B, and an end-time E, both in the unit of seconds, we calculate the time elapsed by E-B.

Lucky for us, Windows provides a function called GetTickCount() that is a measurement of time (milliseconds) that we can use for such cases.

So:
<pre>
int begin = GetTickCount();

// do some code here.

int end = GetTickCount();

int delta = (end - begin) / 1000; // elapsed time converted to seconds from milliseconds
</pre>

=== Obtaining the current time ===

''Requirements:'' Include <time.h>.

Use:
<pre>
char u[100];
time_t t=time(NULL);
tm *tmp = localtime(&t);
strftime(u,99,"%c",tmp);
sendPublic("Current date and time: " + u);
</pre>

==Writing Functions==

For this example, we will take the function called closeto, which determines
if a player exists in an specific radius around a point. Now to apply this function to a MervBot plugin, you need to write it into the spawn.cpp - at the top of the file in the //////// DLL "import" //////// setion, as below:
<pre>
//////// DLL "import" ////////

bool closeto(Player *p, int x, int y, int tolerance)
{
// Requires the function abs() to be declared elsewhere.
// Return if player p is in area of square with center x, y
// and radius = tolerance
return (abs((p->tile.x) - x) - tolerance) && (abs((p->tile.y) - y) - tolerance);
}
</pre>

If you want your function to have access to the data from spawn.h botInfo class, you make the function apart of it. To do this, we add the '''botInfo::''' infront of the function name, in spawn.cpp.
<pre>
//////// DLL "import" ////////

bool botInfo::closeto(Player *p, int x, int y, int tolerance)
{
...
}
</pre>
In '''spawn.h''', add your method's prototype without botInfo::, it will look
like this:
<pre>
//...
botInfo(CALL_HANDLE given)
{
// ...
}
bool closeto(Player *p, int x, int y, int tolerance); // Your function prototype.

void clear_objects(); //provided by Catid, and already exists.
void object_target(Player *p); //provided by Catid, and already exists.
// ...
};
</pre>
If you're not familiar with prototypes, notice it is similar to that in your spawn.cpp, but without the botInfo::, and a trailing ;.

===Function notes===

Remember that you can pass variables [http://www.cplusplus.com/doc/tutorial/tut2-3.html by reference]. If variables are passed by reference, any changes a function makes to the variables will remain after the function returns.

From time to time you will need to pass an array to a function. An example illustrating this is:
<pre>
int freqs[5]; // declare our example data.

// call function - notice freqs and not freqs[5] or freqs[].
my_function(freqs); //You're not passing the array itself, just a pointer to the array.

// function - notice freqs[] and not freqs[5] or freqs
void my_function(int freqs[]) {} //You're specifying that the freqs parameter is an array
</pre>

==Cycling through players==

MERVBot stores player-related data in a linked list. A linked list is a datatype that stores its data in a series of structures linked to each other, hence the name.

To search through the players in the arena, just start at the first link, then continue through all the following links until you reach the end:
<pre>
_listnode <Player> *parse = playerlist->head; //set to first link of the player linked list

while (parse) //parse will be NULL when we reach the last link
{
Player *p = parse->item; //item is the actual data stored in the link

// do functionality here
// Example 1: sendPrivate(p,"*watchdamage"); // turns on all pilot's watchdamage
// Example 2: if (p->safety != 0) sendPrivate(p,"*spec"); // spec all pilots in safe zone

parse = parse->next; //set parse to the next link
}
</pre>

For example, assuming our bot has smod+ privilages, the following code will set all non-spectator players to a specific ship. First begin by adding the following function prototype to the spawn.h in the botInfo class:
<pre>
void handleCmdSetShip(enum Ship_Types ship);
</pre>

In spawn.cpp add:
<pre>
void botInfo::handleCmdSetShip(enum Ship_Types ship)
{
//Note that the parameter ship is of the Ship_Types enum,
//so its value is hopefully restricted to the proper types.

_listnode <Player> *parse = playerlist->head;
while (parse)
{
Player *p = parse->item;

if ( p->ship != ship && p->ship != SHIP_Spectator )
sendPrivate(p, "*setship " + (String)ship);

parse = parse->next;
}
}
</pre>

To use, just call the function with the appropriate Ship_Type from the enum in clientprot.h:
<pre>
handleCmdSetShip(SHIP_Warbird);
</pre>

==Random numbers==

===Generating a random number===

To use this method, these two includes must be used:
<pre>
#include "time.h" //provides time() function.
#include "stdlib.h" //provides srand() and rand() functions.
</pre>

Use:
<pre>
srand(time(NULL)); // seed random number generator.

rand(); // randomize.

int temp = (int) (51 * ((float)rand()/RAND_MAX));
// the above line returns a random integer between 0 and 51.
// Note: RAND_MAX is a global constant defined in stdlib.h
</pre>

===Picking a random pilot===

''Note:'' A required user-defined function, getInGame(), must be created for this example to work.

<pre>
int temp = GetTickCount() % getInGame(); // getInGame() = how many pilots in arena

Player *rabbit = NULL;

_listnode <Player> *parse = playerlist->head;
while (parse)
{
Player *p = parse->item;

if (p->ship != SHIP_Spectator) // if player is not a spectator
if ( !(--temp) ) // and if we've hit the randomly-selected pilot
{
rabbit = p;
break;
}
parse = parse->next;
}
</pre>

==Storing data for pilots==

There are several ways to store data for pilots (ie tracking flagtime or kills in a period of time). Note that these methods are all purely internal to the bot, and don't effect anything beyond the plugin in any way.

# Built-in get/setTag: Tracks data until player leaves the arena, then automatically deletes data.
# Modified perm get/setTag: Tracks data until bot leaves arena, then automatically deletes data. (Advantage: easier to sort by player)
# Custom Structs: Tracks data until plugin deletes it. (Advantage: easier to sort by freqs)

''Note:'' 2 and 3 are similar in effect, mostly the difference is in how you are able to search through data you need to decide which method of storing data is best for each bot depending on what it does.

===Built-in get/setTag method===

Player tags simply tag a player with a number. Define the wanted values in '''spawn.h''' at the top:
<pre>
#define DMG_DEALT 0
#define DMG_TAKEN 1
</pre>

In spawn.cpp, initialize the values on ArenaEnter and PlayerEnter:
<pre>
case EVENT_ArenaEnter:
{
// ...

// do for all pilots in arena when bot enters
_listnode <Player> *parse = playerlist->head;
while (parse)
{
Player *p = parse->item; // get pilot

set_tag(p, DMG_DEALT, 0); // initialize to 0
set_tag(p, DMG_TAKEN, 0);
sendPrivate(p, "*watchdamage"); // optionally turn on player *watchdamage

parse = parse->next; // get next pilot
}
}
</pre>
<pre>
case EVENT_PlayerEntering:
{
// ...
set_tag(p, DMG_DEALT, 0); // initialize to 0
set_tag(p, DMG_TAKEN, 0);
sendPrivate(p,"*watchdamage");
}
</pre>

Then somewhere edit the tag values:
<pre>
case EVENT_WatchDamage:
{
// sets tag for k (shooter) to be old value plus damage currently dealt

int old_damage = get_tag(k, DMG_BOMB_DEALT);
set_tag(k, DMG_BOMB_DEALT, old_damage + damage);
}
</pre>

The following demonstrates how to retrieve the tag values as a command in command.cpp:
<pre>
if (c->check("showstats"))
{
int temp = get_tag(p, DMG_TOTAL_DEALT);

String s = "You've done ";
s += temp;
s += " damage so far!";

sendPrivate(p,s);
}
</pre>

===Modified permanent get/setTag method===

This method is the same as get/setTag with some modifications to the tag code to retain them after the player leaves. Beware of using this method if bot is in an arena for long periods of time, linkedlist could get huge.

// spawn.h, add char name[20]; into struct PlayerTag
<pre>
struct PlayerTag
{
Player *p;
char name[20];
int index;
int data;
};
</pre>

In spawn.cpp:
<pre>
case EVENT_PlayerLeaving:
{
Player *p = (Player*)event.p[0];

// killTags(p); // remove so tag not deleted on arena exit

// ...
</pre>

Locate in spawn.cpp and modify accordingly:
<pre>
int botInfo::get_tag(Player *p, int index)
{
_listnode <PlayerTag> *parse = taglist.head;
PlayerTag *tag;

while (parse)
{
tag = parse->item;

// if (tag->p == p)
if (strcmp(tag->name,p->name)==0) // now tracking by player name, not pointer
if (tag->index == index)
return tag->data;

parse = parse->next;
}
return 0;
}

void botInfo::set_tag(Player *p, int index, int data)
{
_listnode <PlayerTag> *parse = taglist.head;
PlayerTag *tag;

while (parse)
{
tag = parse->item;

//if (tag->p == p)
if (strcmp(tag->name,p->name)==0) // now tracking by player name, not pointer
if (tag->index == index)
{
tag->data = data;
return;
}
parse = parse->next;
}

tag = new PlayerTag;
// tag->p = p; // not tracking by pointer anymore
strncpy(tag->name, p->name, 20); // tracking by player name
tag->index = index;
tag->data = data;
taglist.append(tag);
}
</pre>

===Using structs===

In '''spawn.h''':
<pre>
class botInfo
{
struct freqdata
{
int kills, deaths;
};
// ...
};
</pre>

To make use of this structure, implement accordingly:
<pre>
freqdata freqs[100]; // 100 of those structs
</pre>
Access the data in spawn.cpp using
<pre>
freqs[56].kills = 1;
</pre>

See CPlusPlus.com's [http://www.cplusplus.com/doc/tutorial/tut3-5.html Structures] tutorial for a more comprehensive guide. Note that, as shown on the bottom of the page, you can have structures within structures. Thus, for example, you could have a structure for each freq with a structure for each player nested within them.

==Input/Output to files==

For reading and/or writing to files with C++ you must have the required include statement as follows:
<pre>
#include <fstream>
using namespace std;
</pre>

===File stream input===
The following example will show you how to read a file, duel.ini, line by line.

<pre>#include "stdlib.h" // for atoi()</pre>

<pre>
ifstream file("duel.ini");

if (!file.good()) // if there was an error opening the file
sendPublic("*arena Error opening file for reading"); // or add your own error handler
else
{
char line[256];

// read in MaxBoxes=X
while (file.getline(line, 256))
{

if (CMPSTART("MaxBoxes=", line)) //Does the line begin with MaxBoxes= ?
{
MAX_BOXES = atoi(&(line[9])); //If so, read the value into an integer, using atoi.
break;
}
}

file.close();
}
</pre>

===File stream output===
The following code example will demonstrate how to append to a file, duelleaguestat.inc.
<pre>
ofstream file("duelleaguestat.inc", ios::app); // app = put all data at end of file

if (!file.good()) // if there was an error opening the file
sendPublic("*arena Error opening file.");
else
{
file << squad1<< endl; // squad1 = char[20]
file << " vs "<< endl;
file << squad2<< endl; // squad2 = char[20]
file.close();
}
</pre>

Similarly, you are able to write an output of a String to a file:
<pre>
// key is converting String to (char*) to file write
String str = freqs[freq].slotname[slot];
str += ", Repels: " + (String)(int) t->repel;
file << endl;
file << (char*) str;
</pre>

===Input with GetPrivateProfileString===

GetPrivateProfileString(), a function provided by Windows for reading INI files, will automatically find an INI key (like "MaxBoxes=") in a file for you. See the [http://msdn.microsoft.com/library MSDN Library] for help on this function. This next example will show how to read input using GetPrivateProfileString() based on the rampage plugin.

The file format for rampage.ini is like this:
<pre>
7=is on a killing spree! (6:0)
10=is opening a can of booya! (9:0)
</pre>

In '''rampageini.cpp''':
<pre>
#include "rampageini.h"
#define WIN32_LEAN_AND_MEAN
#include <windows.h>

#define NUM_RANKS 10
#define BUFFER_LEN 256

struct RampageSettings
{
char quotes[NUM_RANKS][BUFFER_LEN];
};

void LoadSettings(RampageSettings &setts);

static char path[BUFFER_LEN];

char *rank_type[NUM_RANKS] = { "7", "10" };

void LoadSettings(RampageSettings &setts)
{
GetCurrentDirectory(BUFFER_LEN - 64, path);
strcat(path, "\rampage.ini");

for (int i = 0; i < NUM_RANKS; ++i)
{
GetPrivateProfileString("Comments", rank_type[i], "-ERROR-",
setts.quotes[i], BUFFER_LEN, path);
}
}
</pre>

==Player data==

As stated earlier in the tutorial, MervBot stores useful player data internally as Player objects, see player.h for implementation details.

* p->name = player name stored as char[20] (''Note:'' SubSpace protocol allows for usernames to be 19+ in length, do not rely on this for player-name comparisions.)
* p->squad = player squad stored as char[20]
* p->ship = ship (0-9) enumerated as SHIP_Warbird, SHIP_Spectator, etc..
* p->safety = whether ship is in safety zone (boolean)
* p->bounty = player bounty
* p->energy = player energy (have bot with *energy on to get accurate readings)
* p->flagCount = how many flags player is holding
* p->team = player frequency
* p->(burst, repel, thor, brick, decoy, rocket, portal) = how many items of that type player has
* p->(stealth, cloak, xradar, awarp, ufo, flash, safety, shields, supers) = if player has that item on (boolean)
* p->score.killPoints = player kill points
* p->score.flagPoints = player flag points
* p->score.wins = player kills from f2
* p->score.losses = player deaths from f2

Just access the respective member of the Player class to check the player's property.

For example, in spawn.cpp, to check whether a player is in a safety zone:
<pre>
EVENT_PlayerMove:
{
Player *p = (Player*)event.p[0];

if ( p->safety ) // player is in safe zone.
{
// do something.
}

if ( !p->safety ) // player NOT in safe zone.
{
// do something.
}
}
</pre>

=== Obtaining a player pointer using name comparison ===

Since Player pointers are internal to MERVBot, it is necessary to find a way of obtaining a Player pointer from the identifying information given by the game. One of the simpler ways is just to compare the names after converting to lowercase.

''Note'': Using pilot names as vital comparisions should be used with caution. See [http://cypherjf.sscentral.com/articles/bots-as-clients/ Bot-Issues] by CypherJF.

<pre>
// return Player* info (or NULL if not found) from p->name info
Player * botInfo::GetPilot(char *name)
{
// get pilot from a name, return as TempPlayer
_listnode <Player> *parse = playerlist->head;

//convert search name to lowercase
char nname[20], pname[20];
strncpy(nname, name, 20);
tolower(nname);

while (parse)
{
Player *p = parse->item;

// convert to lowercase to compare
strncpy(pname,p->name,20);
tolower(pname);
if (strcmp(pname,nname)==0)
return p;

parse = parse->next;
}

return NULL; //player not found
}
</pre>

==Bot built in functions==

Here are some useful MervBot commands to control what the bot is doing.

Player.cpp:
* Player::move(Sint32 x, Sint32 y) moves a player to the coordinates specified by x and y
* Player::clone(Player *p) clones a player into a player class

Look in Commands.txt , command.cpp (core), or /!help to bot to see all bot external commands (example /!go <arena>).

''LVZ Object toggling commands in plugins are to go here.''

[[Category:Guides]]

Creating and Testing a Simple Discretion Module in Eclipse

2009-04-06T10:39:53Z

BaK: and apparently I did too :/

This tutorial is a '''video''' tutorial describing how anyone can using minGW (and probably g++) and Eclipse to compile a simple module and put get it to run on [[Discretion]]. It assumes you're using Windows (although g++ may work) and you don't have any tools installed. However, you should have already gotten the source code (if not see the [[Obtaining the Discretion Source using Subversion]] tutorial). This tutorial is part of a series of tutorials consisting of the [[Discretion Module Tutorial]].

minGW stands for minimalistic Gnu for Windows. It is an open source complier almost identical to gcc and g++, which are the compilers used for linux, among other things. The compiler produces native Windows exectuables, and best of all it's free! However, its interface isn't the best for the novice user. Thus, we use eclipse to help manage the minGW compiler for us.

Eclipse, is an integrated development environment (IDE) which is also open-source and free. It is basically a program that makes it easier to make other programs. It was originally designed for Java development, but people made plugins to allow C++ development. These extensions are called the CDT (C/C++ Development Tooling). The CDT integrates nicely with minGW so these two make a good match. Discretion's modules come with Eclipse Projects when you get the source so modifications are easy to make. Eclipse is implemented in Java, so in order to use it you need the Java Runtime Environment. The good news is you probably already have this installed. Nonetheless, the tutorial covers downloading it if you don't already have it installed.

==Videos==

This tutorial is divided a few parts:
* [[Media:Disc_mingw.wmv|Obtaining and Testing minGW]]
* [[Media:Disc_jre.wmv|Getting the Java Runtime Environment]] (90% of people can skip this step)
* [[Media:Disc_eclipse.wmv|Downloading Eclipse with CDT]]
* [[Media:Disc_simplemod.wmv|Creating and Testing a Simple Module within Discretion]]
* [[Media:Disc_tricks.wmv|Discretion with Eclipse Tricks and Tips]]

==Links==

minGW: [http://sourceforge.net/project/showfiles.php?group_id=2435 Sourceforge File List]

java runtime environment: [http://java.sun.com/javase/downloads/?intcmp=1281 Downloads]

eclipse: [http://www.eclipse.org/downloads/ Eclipse Downloads]

Creating and Testing a Simple Discretion Module in Eclipse

2009-04-06T10:38:52Z

BaK: mgb messed up one of the video links :/

This tutorial is a '''video''' tutorial describing how anyone can using minGW (and probably g++) and Eclipse to compile a simple module and put get it to run on [[Discretion]]. It assumes you're using Windows (although g++ may work) and you don't have any tools installed. However, you should have already gotten the source code (if not see the [[Obtaining the Discretion Source using Subversion]] tutorial). This tutorial is part of a series of tutorials consisting of the [[Discretion Module Tutorial]].

minGW stands for minimalistic Gnu for Windows. It is an open source complier almost identical to gcc and g++, which are the compilers used for linux, among other things. The compiler produces native Windows exectuables, and best of all it's free! However, its interface isn't the best for the novice user. Thus, we use eclipse to help manage the minGW compiler for us.

Eclipse, is an integrated development environment (IDE) which is also open-source and free. It is basically a program that makes it easier to make other programs. It was originally designed for Java development, but people made plugins to allow C++ development. These extensions are called the CDT (C/C++ Development Tooling). The CDT integrates nicely with minGW so these two make a good match. Discretion's modules come with Eclipse Projects when you get the source so modifications are easy to make. Eclipse is implemented in Java, so in order to use it you need the Java Runtime Environment. The good news is you probably already have this installed. Nonetheless, the tutorial covers downloading it if you don't already have it installed.

==Videos==

This tutorial is divided a few parts:
* [[Media:Disc_disc_mingw.wmv|Obtaining and Testing minGW]]
* [[Media:Disc_jre.wmv|Getting the Java Runtime Environment]] (90% of people can skip this step)
* [[Media:Disc_eclipse.wmv|Downloading Eclipse with CDT]]
* [[Media:Disc_simplemod.wmv|Creating and Testing a Simple Module within Discretion]]
* [[Media:Disc_tricks.wmv|Discretion with Eclipse Tricks and Tips]]

==Links==

minGW: [http://sourceforge.net/project/showfiles.php?group_id=2435 Sourceforge File List]

java runtime environment: [http://java.sun.com/javase/downloads/?intcmp=1281 Downloads]

eclipse: [http://www.eclipse.org/downloads/ Eclipse Downloads]

Discretion

2008-10-01T02:58:52Z

BaK: /* Weapons */ removed bouncing bullet business

[[Image:discretionss.PNG|thumb|A Screenshot of SubSpace Discretion.]]

Discretion[http://ss-discretion.sf.net] is a [[SubSpace]] client created by [[User:BaK|BaK]]. It is open source, like [[ASSS]], and is released under the [http://en.wikipedia.org/wiki/GPL GPL]. Discretion was developed because of the limitations of the in-use client, [[Continuum]]. Furthermore, the lack of development of Continuum led to a situation where limitations in the client would never be overcome. Making heavy use of [http://en.wikipedia.org/wiki/Simple_DirectMedia_Layer SDL], Discretion is cross-platform, and is currently supported under Windows, Linux, and Mac OS X. Discretion is intended to be secure through design, rather than through obscurity like Continuum. It is designed to make cheating is impossible, rather than just difficult. There is also an extensive [[Discretion Module Tutorial]] on this wiki for those interested in helping out.

Since cheating is to be made impossible, the server must check the data players send it for cheating. This requires modifying the server, which rules out using [[Subgame]]. There is, however, a modified ASSS Server that allows Discretion clients to connect.

In order to encourage client development, Discretion is designed with a modular system similar to ASSS. There are interfaces which define actions for modules (such as "draw ship at 50,50"), and callbacks which signal when events occur (such as "player has been killed"). Where ever possible, magic values have been removed and are instead loaded from plain-text settings files. The goal of this is to eliminate any built-in constraints present in VIE SubSpace and Continuum. These magic values include the location / color of the FPS counter, 1024x1024 tiles in maps, each tile being 16x16 pixels, each ship image having 40 frames thus 9 degree turns, the number of fly over tiles, two sets of doors four tiles each per map, the 0x01 type packet corresponding to an arena login, friendly players showing up yellow in the stat box, the colors in the font file, the number of frames in the wormhole animation, the text that shows up when you press ESC, the number of ships, as well as all the settings Continuum does allow you to change such as the ship images, the game play settings, and the controls. The server is intended to be able to modify most of these, thus giving [[Zone]] developers maximum creativity and flexibility.

==Modules==
Discretion is divided up into several modules, dynamically linked into the main program much like ASSS. These modules are desired to be as generic as possible, with their Continuum-like actions coming from the settings, rather than the modules themselves. Thus Discretion is like a 2D grid game engine, with settings and graphics which make it look like SubSpace. The module interfaces are documented in the corresponding header files using Javadoc-style documentation. There are currently over 30 modules in the Discretion release. Some of the main ones are discussed below.

===Settings Handler===
The '''SettingsHandler''' modules loads the settings from ini-like plain text files. The main settings file is located in conf/MAIN.CONF, which #includes many other settings files. All these settings files are plain text, meaning they can be edited using a utility like pico or notepad. Individual settings can be specified in several formats, depending on how they should be interpreted. Supported types include integers (''50'', ''0x30'', ''0777''), strings (''hello person''), points/vectors/dimensions (''(100,200)''), rgb colors (''(255,255,255)'', ''(0,128,128)''), and [[LVZ]]-style screen locations (''(C+50,50)'', ''(B-10,C+25)''). There also exists a helper function to parse comma separated a list of strings from a single sting in shared/StringManip.h. This module interface also allows modules to load their own conf files, or save a group of settings to a file which the program can then read out of.

The front end program, '''cskinviewer''' uses the saving capability of '''SettingsHandler''' to keep track of zone data between program executions.

===Module Manager===
The '''Module Manger''' itself is a module which is loaded by the program, which then proceeds to load any other modules. This uses the setting Modules::Names which is a comma separated list of strings to figure out which modules to load. It loads module files, '.dll's in Windows and '.so's in Linux, from the bin/ directory. Modules are loaded in stages. During the first stage, LOADMODE_Init, modules register their interface, if any, with the '''Module Manager''' and register any callbacks they want to listen for. During the next stage, LOADMODE_LoadInterfaces, modules load any interfaces they plan to use. Finally, during LOADMODE_PostLoadInterfaces, modules can use their loaded interfaces to other modules to initialize themselves. Upon successful program termination, LOADMODE_Unload is invoked which allows the module to free any data or resources it's using. The module manager also facilitates callbacks. Where possible, C++ exception handling is used to aid in catching errors in a non-fatal way and reports the cause of the problem.

Note that some initialization tasks should not be done in LOADMODE_PostLoadInterfaces since they require modules be initialized in a specific order. For example, the '''Text''' module, which writes text to the screen should not be initialized before the ''Graphics'' module is, since it would be unable to load the text image. Thus some initialization tasks are be done in callbacks, CB_LOADIMAGES in this instance.

===Graphics===
The '''Graphics''' module allows one to load images and draw them to the screen or map. When an image is loaded through the interface, an image handle is given to the calling module which is used to refer to the image. This handle can also be used to get the image size (taking into account that some images are framed animations), or free the image when it's no longer needed. Blank images can also be created and drawn on, thus allowing one to predraw complex images instead of redrawing them every frame. Images, when drawn to the screen, are drawn in layers. This allows several modules to queue up images to be drawn out of order and still result in a correct drawing. Some layers include L_Tiles, L_Weapons, L_AfterWeapons, L_Gauges, L_Chat and L_TopMost. Images can be drawn relative to the screen, or relative to the map. Images can also be blended such that they appear translucent, as long as the user has Graphics::UseBlending set to 1. Rectangles of a constant color can also be drawn to the screen or on to another image. The images are queued up to be drawn during the CB_PRERENDER callback.

Although providing a basic interface, it is uncommon to '''Graphics''' module directly for loading images. Instead the '''UniqueImage''' module allows one to specify an image in the settings and refer to it in code by a name. This is much easier than loading the image yourself, and easily allows a single graphic to contain many different images, which is not uncommon in SubSpace images (the bullets image, for example, contains images for all sorts of bullets rather than just a single type). The '''UniqueImage''' module makes sure to only keep a single copy of the image in memory at all times. The '''UniqueImage''' module, in turn, is used by the '''Animations''' module to provide simple access to SubSpace-style animations. Thus, a programmer can code something like 'draw animation "bullet explosion" at 512,512' and it will handle loading the image, figuring out how many frames there are, the speed of the animation, and how long to display it for.

===Controls===
The '''Controls''' module permits the programmer to provide actions("move forward"), while the settings specify exactly what keyboard or joystick input they correspond to("up arrow key"). Controls should be registered in the CB_CONTROLSLOADED callback. Also, since this a generic module it does not capture any of the physical controls itself, instead relying on other modules to handle that aspect.

The '''SDL Key Controls''' module handles capturing keyboard input and sending it to the '''Controls''' module. The '''Mouse''' module does not use the '''Controls''' module directly, instead providing its own interface which allows one to create mouse hotspots and be notified of mouse clicks or movements within these hotspots.

===Timers===
Similar to how ASSS has timers implemented in the mainloop module, Discretion has a '''Timers''' module that provides a timer functionality. One can register a function to be called in X milliseconds, or every X milliseconds until it's canceled. Discretion is currently not multithreaded beyond SDL, so that a timer in an infinite loop (or any piece of code that gets to run, for that matter), will result in the program freezing up. Thus you should not use blocking calls in timers or take up too much processing time which will degrade performance.

The '''Net''' module uses a timer to send and receive packets.

===Text===
The '''Text''' module provides an easy way to draw text on the screen. This is the standard subspace text and can be specfied by color. This module draws the text on one line for a single frame. Therefore, you must call the appropriate functions in this interface during CB_PRERENDER every frame for however long you wish to display the text. There is support for drawing text relative to the screen or to the map, as well as blending text and drawing on any layer.

The '''Textbox''' module uses '''Text''' to draw its text, but provides additional features such as drawing textbox borders and allowing easy textbox loading from files. '''EscapeBox''' and '''PlayerList''', in turn, use '''Textbox'''. '''Chat''' also makes use of the '''Text''' module when it draws player chat to the screen. The '''Flash''' module, which handles messages similar to SubSpace's kill and prize messages, also uses the '''Text''' module. Pretty much anywhere you see text, the '''Text''' module is at work.

===Physics===
The '''Physics''' module provides functions which can give you a particle's new position given its initial position, velocity, and time elapsed. This is used for ships as well as weapons. The position can be advanced in such a way that is affected by the map (such as bombs going around a wormhole), or not. Particles can bounce off the level or explode on contact.

The '''SelfShip''' module uses '''Physics''' to compute the new position of the player over time. '''SS_Items''' uses '''Physics''' to find the position of a bullet after a certain amount of time.

===PerPlayerData===
The '''PerPlayerData''' module provides a simple way to have data that is common to every player. This is similar to ASSS' PlayerData module in that a struct of memory can be allocated for every player and referred to using a key. The module also facilitates simple sharing of per player data between module such as "name", "x", or "y".

The '''PlayerList''' module uses the sharing facility of '''PerPlayerData''' to get the names of the players on the player list.

===Level===
The '''Level''' module provides a simple interface to possibly many different types of level formats. Modules can load levels through the interface, as well as get the map or tile size. Furthermore, forces on the level, such as wormholes, friction, or gravity can be applied through the interface.

Currently, the only map format implemented is '''oldlvl''' which supports regular SubSpace [[LVL]] files. This provides a somewhat more generic implementation, which a customizable amount of doors or custom animation tiles (wormholes, space station, and asteriods), as well as having wormholes with different properties on the same map.

===Front End===
The front end, not exactly a module, is implemented as its own program, '''cskinviewer''', contributed by [[User:Smong|Smong]]. This program allows one to download a list of ASSS servers from a [[Directory Server]], and choose one and login. It uses the '''SettingsHandler''' to save the current zone list to the settings. Custom zones can not be added through the interface yet, but can be added by hand by editing conf/profiles/ZoneList.conf.

The front end executes '''in_game''', which in turn loads the '''Module Manager''' which runs '''Main SDL''' which runs callbacks to load the various SDL Subsystems and starts the program's main loop.

==Contribute==
Development for Discretion is ongoing and everyone is encouraged to contribute. Graphics are always helpful, and if you have an idea feel free to make it. In the spirit of free software, it would be best if eventually all VIE owned graphics were replaced, as their copyright status is unknown. This includes the ships, bullets, default tileset, and all other graphics from VIE SubSpace or Continuum. Also, a Discretion [[skin]] is yet to be made for the front end (the format follows that of Continuum's, see the skins directory in your Continuum folder). Additionally, many features are in development or unimplemented. If one wanted to help out, just contact [[User:BaK|BaK]], or start working on graphics or a module. There is also a [[Discretion Module Tutorial]] which shows you how to create a simple module. Some planned modules include:

====Star Background====
A '''StarBackground''' module that draws stars and planets similar to how Continuum does it. It would be great it this looked better than Continuum as it would really lead to the immersion necessary for a fun experience. This could also be used to draw all sorts of backgrounds, such as grass for earth-based zones, to provide an alternate to tiling LVZ all over the map. This would be a good module to make to get introduced to Discretion development.

====LVZ====
A reverse compatible LVZ module is desired to allow current zones to easily switch over to Discretion without remaking their lvz files. This could provide additional functionality not present in current lvz such as lvz that depend on ship locations to allow animations within shipsets. The easier way to make this is probably to make a static image/animation module which uses the settings and '''UniqueImage''' and '''Animations''' to draw images on the map and screen. Then, an lvz compatibility layer module would be made which translates an lvz file into a .conf file and uses '''SettingsHandler''' to load in the images from the generated file.

====Radar====
Subspace and Continuum include a radar for locating enemies. This will have to be implemented in Discretion. The users should also be able to make the radar bigger by pressing a key (alt).

====Sound====
Sound provides immersion in video games and gives them an authentic feel. We need a way to play sounds when certain actions occur such as a bullet being fired or player bouncing off a wall. WAV sounds will have to be implemented for reverse compatibility, but mp3 is not out of the question for longer sounds such as victory music or just music in general. After this is done, a built in mp3 player could be made to allow players to change songs from within the game. SDL_mixer[http://www.libsdl.org/projects/SDL_mixer/] provides mp3 capabilities and may be used.

====Weapons====
There are many items SubSpace uses which must be implemented. Care must be taken here to prevent cheating. For example, it would not be difficult to write a program to detect right before a player is about to get hit and automatically portal out or repel. Thus, these items may have to be modified to be on a timer, so that using a portal might require your ship to take a second to "charge up" instead of instantly warping. Also, it would be great if weapons didn't have to follow boring straight lines and instead could turn. Thus I could specify in the settings the direction a weapon would travel if the ship were facing straight up and it would happen. So a straight line would be (0,t), a curvy shot may be (sin(t),t), a shot that speeds up over time may be (0,2^t).

====Custom Client Side Code====
The server should be able to provide code that can be executed client side. There are two types of code that will be provided: updated versions of modules, and game play related code. This is especially dangerous since a malicious server owner should not be permitted to compromise players' computers. The module updates can be done by providing a RSA signature with the binary .dll or .so which can be checked before executing any downloaded files. As for game play related code, a Java virtual machine could be used with a Security Manager that allows nothing beyond basic functions. Then, an interface could be provided to the game code that could be used by the code. Thus, binary .class file could be distributed for an arena that aren't allowed to delete files off your computer, but are allowed to access the game play relayed interface thus permitting graphics to be drawn or players to be warped around.

==External links==
*[http://ss-discretion.sf.net Main Discretion Website]

[[Category: Clients]]
[[Category: Discretion]]

SubSpace

2008-06-01T19:12:47Z

BaK: fucking spammer, ban that guy

[[Image:SS_screen.png|thumb|VIE SubSpace]] SubSpace is a massively multiplayer online game of death. Specifically, it is a top-down shooter much like Asteroids, in which a player chooses between 8 [[Ships]] to fly around and shoot other players with. Over time, other game types were developed for SubSpace such as Rabbit, [[Flag|Flagging]], [[Soccer]], Speed, [[King of the Hill]], and more.

Currently, SubSpace is run by its playerbase and distributed as a player-made client, [[Continuum]]. Also, some servers are running a player-made and Open Source server software, [[ASSS]].

Some SubSpace dates can be found in [http://wiki.aswz.com/index.php/SubSpace%20History here].

===History===

[[SubSpace]] began as a massively multiplayer (before that term existed) combat game dubbed '[[Sniper]]' in 1995 (later reincarnated as [http://infantry.station.sony.com/en/main.jsp Infantry]) but was quickly renamed and re-themed; it was made by Virgin Interactive Entertainment (VIE) and was one of the earliest action multiplayer online games, possibly the first semi-successful one.

For two years the game was in open beta and several [[zone]]s were hosted by the VIE servers. The problems started when the game went retail. The servers were still free, but you had to buy the game CD to play on them. The game wasn't advertised well (very small marketing budget) and in spite of a severely addicted, albeit small, player community VIE pulled out in 1997 and a year later turned their servers off with little more than a shrug.

The server software was included with the CD due to the foresight of one of the main programmers, so user-made and hosted [[zone]]s continued to be made, but without VIE there was no central control or client code updates and cheating was rampant. In 1998, a West European company based in [http://en.wikipedia.org/wiki/Finland Finland] had purchased distribution rights just before VIE pulled the plug and their servers were initially used as a crutch while the American community regrouped. Slowly the community came together as strong servers were set up on the east and west coast of the US. The cheating was still choking the game to death, but a loyal legion of volunteers kept the torches lit while a handful of programmers began a new project in secret.

In 2001 these programmers unveiled a brand new client for [[SubSpace]] that had been reverse-engineered from the ground up to replace the aging VIE client. This new client was programmed by [[Mr Ekted]] and [[PriitK]] (aka Priit Kasesalu, one of the creators of [http://kazaa.com Kazaa]). It was called [[Continuum]] and allowed the community to arrest cheating and continue the development of the game.

Although now roughly nine years old, [[SubSpace]] is as popular and addicting as it's ever been. Some of the old VIE [[zone]]s are still there, now known as [[SVS]] zones, and many more new kinds of different [[zone]]s and settings have emerged. The recent updates to [[Continuum]] as well as extensive [[bot]] & scripting development throughout individual zones has allowed the entire community to constantly develop and evolve the gameplay and graphics.

For a little taste of nostalgia for vets and a glimpse into history for new players, there is [http://subspace.legendzones.com/history/vie/ a mirror of the official VIE website] from 1997.

==Links==
*[http://www.subspacehq.com SubspaceHQ.com]
*[http://beginners.subspace.net Subspace.net]
*[http://www.ssdownloads.com SSDownloads]
*[http://www.ssforum.net SSForum.net]
[[Category: Clients]]

MERVBot Tutorial

2008-04-26T00:04:50Z

BaK: /* Setting up a MERVBot (plugin) */ fixed link to mervbot site

This tutorial is based on the ever-popular MERVBot Tutorial by Underlord. It has since been updated to reflect new changes with MervBot. To see examples of how to use this instruction, see [[MERVBot Example Code]].

This tutorial also assumes that you have a basic knowledge of C++. If you don't, check out cplusplus.com's great [http://www.cplusplus.com/doc documentation].

==Setting up a MERVBot (plugin)==

[http://mervbot.com MERVBot download site]

===Obtaining MERVBot===

* Download the [http://mervbot.com/files/MERVBot.rar latest build].
* Unrar MERVBot.rar into a new folder. (example c:\program files\continuum\mervbot)
* Unzip src.zip into "src" subfolder of that new folder (example c:\program files\continuum\mervbot\src)

===Preparing to write a plugin===

''Note:'' if you only want to execute someone's premade plugin (.dll), skip to [[MERVBot Tutorial#Run your bot dll|step 4]], otherwise continue to learn how to make your own bot

Download [http://catid.sscontinuum.com/files/Tutorial.rar DLL-plugin Tutorial] and unzip Tutorial.zip (containing spawn.h, spawn.cpp, and command.cpp) into a "tutorial" subfolder of that new folder. (example c:\program files\continuum\mervbot\src\tutorial).

''File descriptions:''
* spawn.h = declare/initialize globals
* command.cpp = code for commands coming into bot (ie /!help, /!play, etc)
* spawn.cpp = code that interacts with bot spawns

===Microsoft Visual c++===

<ol>
<li>Start Visual Studios 6.0.
<li>Click the Drop Down Menu labeled "File" at the top left of your screen.
<li>Click "New".
<li>On the next screen that comes up, choose from the Project tab, then Win32 Dynamic-Link Library
<li>Select the "/src" folder as the base folder (example c:\program files\continuum\mervbot\src)
<li>Name your project "mybot". This will make a "mybot" subfolder in your "src" folder. Click OK. (example creates c:\program files\continuum\mervbot\src\mybot)
<li>Choose to create an "Empty DLL project".
<li>Click "Finish".
<li>Click the Drop Down Menu labbled "Project".
<li>Click "Add To Project Files"
<li>Copy only spawn.h, spawn.cpp, and command.cpp from the "tutorial" folder into the this new folder. (example from c:\program files\continuum\mervbot\src\tutorial to c:\program files\continuum\mervbot\src\mybot)
<li>Click the Drop Down Menu labelled "Build".
<li>Click "Build (dll name)" - where (dll name) is "mybot"
<li>Go into your "mybot" folder and look for a folder named "Debug"
(example c:\program files\continuum\mervbot\src\mybot\debug)
<li>Your new DLL will be in that folder. (example mybot.dll)
<li>Copy mybot.dll to your base folder that has mervbot.exe in it (example c:\program files\continuum\mervbot)
</ol>

===Run your bot dll===

To run your bot you need your DLL (mybot.dll), Commands.txt, MERVBot.exe, MERVBot.ini, Operators.txt, Spawns.txt, and zlib.dll all in one folder (example c:\program files\continuum\mervbot).

<ol>
<li>Edit spawns.txt. '''Read every word of spawns.txt to find out what needs to go in there.'''

 
''Example:''
<pre>2v2-Bot-League : botpw : 2v2a : 2v2league : staffpw</pre>

''Note:'' The bot will attempt to create the name if it doesn't exist already.

<li>Edit MERVBot.ini
 
 
<pre>[Login]
Zone=216.33.98.254:21000 // your zone IP:PORT available from zone.dat in Continuum dir
</pre>

<li>Edit operators.txt. '''Read every word of operators.txt to find out what needs to go in there.''' 

''Example:''
<pre>
4:my_name:
4:another_sysop:
3:other_person:
</pre>

<li>Make sure the bot is on vip.txt or has smod+ access, then run MERVBot.exe.

<li>You can now edit your plugin code by opening "mybot.dsw" (example c:\program files\continuum\mervbot\src\mybot\mybot.dsw) in Microsoft Visual C++. Edit the spawn.h, spawn.cpp, and command.cpp to create your plugin, then build, copy your updated DLL to your MERVBot.exe folder and then execute the bot. Use the tutorial to get ideas on how to implement certain types of features into the bot.

</ol>

==Player Commands - (command.cpp)==

This section describes how to implement player commands into your plugin. Commands are sent to the botInfo::gotCommand function in command.cpp.

Example (makes bot reply to !test with "hi"):
<pre>
void botInfo::gotCommand(Player *p, Command *c) {
switch (p->access)
{
case OP_Moderator:
{
// handle moderator-operator commands here.
}
case OP_Player: //appropriate staff rank here.
{
if (c->check("test")) //replace "test" with whatever command you want
{
//put your command code here
sendPrivate(p,"hi"); //example
}
}
</pre>

===How to have commands with numerical parameters===
Example (!test #):
<pre>
if (c->check("test")) { // reads in test #, default to 1 if invalid number input
int temp = 1;

if (isNumeric(c->final))
temp = atoi(c->final);
</pre>

===How to have player name as input===
Example (!rank player):
<pre>
if (c->check("rank"))
{
String player_name = c->final;

if (player_name.IsEmpty()) // default name to self if invalid name
player_name = p->name;
</pre>

===How to have multi-parameter input===

Use the CRT function sscanf() to scan the string for the values.

Example (!squads squadA vs squadB ''or'' !squads teamA:squadA:teamB:squadB):
<pre>
else if (c->check("squads"))
{
char squadA[20], squadB[20];
int teamA, teamB;

strncpy(squadA, "", 20);
strncpy(squadB, "", 20);

int n_found;

//Note: %[A-Za-z ] is equivalent to %s, but allows an internal space.

//scan the string for the two squads separated by " vs "
n_found = sscanf(c->final, "%[A-Za-z ] vs %[A-Za-z ]", squadA, squadB);

//if that fails, scan the string for freqA:squadA:freqB:squadB
if (n_found < 2)
sscanf(c->final, "%d:%[A-Za-z ]:%d:%[A-Za-z ]", &teamA, squadA, &teamB, squadB);
}
</pre>

===Help Menu===
When a player sends !help to the bot, MERVBot calls botInfo::gotHelp() in each plugin loaded.
<pre>
void botInfo::gotHelp(Player *p, Command *c)
{
if (!*c->final)
{
sendPrivate(p, "4v4 Bot General Commands:");
sendPrivate(p, "------------------------");
sendPrivate(p, "!caps - get captain names");
sendPrivate(p, "!roster <squad> - get roster of a squad");
sendPrivate(p, "!schedule- get current schedule");
sendPrivate(p, "!score - get current score");
</pre>

==Event Calls==

MERVBot is event based, so when making a bot you need to decide what will happen at certain events. Normal plugins need to consider what happens when bot enters arena, player enters arena, player leaves arena, player events like kill, shipchange, teamchange, spec, move then any other relevant events to your bot. Just worry about events that are relevant to the tasks your bot is doing.

MERVBot sends events to botInfo::gotEvent() in spawn.cpp. Each supported event is already present and categorized in gotEvent(), along with the paramters that MERVBot sends with the event. When a plugin wants the bot to do something, it sends tell(event) to the bot.

See dllcore.h for a list of current events and their descriptions. Dllcore.h also contains functions (like makeFollowing) to make events to send back to the bot via tell().

<pre>tell(makeFollowing(false));</pre>

==The Messaging System==

Private message - void sendPrivate(Player *player, char *msg);

''Examples:''

<pre>
sendPrivate(p,"hi");

String s="test";
sendPrivate(p,s);

String s="test";
s += "ing";
sendPrivate(p,s);

char captain1[20];
char captain2[20];
strncpy(captain1,"",20);
strncpy(captain2,"",20);
sendPrivate(p,(String) captain1 + " and " + (String) captain2 + " are the captains.");
</pre>

Team message - void sendTeamPrivate(Uint16 team, char *msg); 
<blockquote>Examples: 
a) sendTeamPrivate(8025,"hi spec freq"); 
b) Uint16 test=0; sendTeamPrivate(test,"hi freq 0"); 
</blockquote>

Public message - void sendPublic(char *msg); 
<blockquote>Example: sendPublic("*arena " + (String) p->name + " is now a captain"); 
</blockquote>
Chat channel message - void sendChannel(char *msg); 
<blockquote>Example: sendChannel("hi chat channel"); 
</blockquote>
Remote private message - void sendRemotePrivate(char *name, char *msg); 
<blockquote>Example: sendRemotePrivate("Player01", "hi"); 
</blockquote>

Note: to have bot print several lines of text fast it needs sysop in the
arena (sysop in arena bot first spawns to also) otherwise it'll print slow to avoid being
kicked for spam

===Output of data in messages===
An example of using normal strings to output data/messages.
<pre>
// does *arena X pilots left in game
// NOTE: variable temp needs to be defined with some value

String s = "*arena ";
s += temp;
s += " pilots left in the game.";

sendPublic(s);
</pre>
Or,
<pre>
//NOTE: this can be considered inefficient.

sendPublic("*arena " + (String)temp + " pilots left in the game");
</pre>

An example using sprintf to align/space data, where output data will be in this approximate format.
<pre>
// output data will be in this approximate format (not lined up perfectly because of html)
// --------------------------------------------------------------------------------------
// Squad: squadname PTS FPTS K D DMG DEALT TAKEN F FK FLT
// --------------------------------------------------------------------------------------
// PlayerA 10000 500 116 101 9999 99999 10 150 980:55
// PlayerB 500 200 7 5 9999 99999 5 3 0:04

char str[255];
sendPublic("*arena--------------------------------------------------------------------------------");

sprintf(str, "*arena Squad: %-20s PTS FPTS K D DMG DEALT TAKEN F FK FLT",
freqs[freq].freqname
);

sendPublic(str);

sendPublic("*arena--------------------------------------------------------------------------------");

// assuming existing freqs struct with data
for (pilot=freqs[freq].playercount-1; pilot>=0; pilot--)
{
// on freq squad so print stats
char outString[255];

sprintf(outString, "*arena %-20s %12d %8d %3d %3d %10d %6d %2d %3d %3d:%02d",
freqs[freq].pilots[pilot].name,
freqs[freq].pilots[pilot].points,
freqs[freq].pilots[pilot].flagpoints,
freqs[freq].pilots[pilot].kills,
freqs[freq].pilots[pilot].deaths,
freqs[freq].pilots[pilot].dmgdealt,
freqs[freq].pilots[pilot].dmgtaken,
freqs[freq].pilots[pilot].flags,
freqs[freq].pilots[pilot].flagkills,
freqs[freq].pilots[pilot].flagtime /60,
freqs[freq].pilots[pilot].flagtime %60
);

sendPublic(outString);
}

// Notes: sprintf format = sprintf(output char string, spacing, variables)
// Notes: s = chars, d = integer, - = left align, right align default
// Notes: doing %02d = put 0 in front if not 2 digits, %3d:%02d makes 0:04 format
</pre>

==Time==

Each time MERVBot sends an EVENT_Tick to a plugin (once a second), the default handler code decrements each value in an array of countdowns. You can modify the number of countdowns and add code to occur at a specific value for one of the countdowns.

Setup number of timers and initialize in spawn.h:
<pre>
class botInfo
{
#define COUNTDOWNS 10 // how many countdowns you want
int countdown[COUNTDOWNS]; // this gives you 10 timers

// unrelated code

public:
botInfo(CALL_HANDLE given)
{
countdown[0] = 0;
countdown[1] = 60; // 60 seconds
//
// initialize values
//
countdown[9] = 5*60; // 5 minutes
</pre>
Using timer functions in spawn.cpp:
<pre>
case EVENT_Tick:
{
for (int i = 0; i < COUNTDOWNS; ++i) //cycles through each countdown you have
--countdown[i]; //note that countdowns will continue decrementing past 0.

if (countdown[1] == 2) // when timer #1 hits two seconds
{
// do stuff here when timer #1 hits 2 seconds
// example: sendPublic("two seconds left, setting timer to 1 minute");
// example: countdown[1] = 60; // change timer #1 value
}
</pre>

You can then have events (such as EVENT_PlayerDeath) change the value of a countdown to make the bot do something a set time after an event occurs.

=== Tracking time not using countdown[n] ===

This is a solution to a common problem of determining the amount of time it takes for something to occur. Using basic math, we record a start-time B, and an end-time E, both in the unit of seconds, we calculate the time elapsed by E-B.

Lucky for us, Windows provides a function called GetTickCount() that is a measurement of time (milliseconds) that we can use for such cases.

So:
<pre>
int begin = GetTickCount();

// do some code here.

int end = GetTickCount();

int delta = (end - begin) / 1000; // elapsed time converted to seconds from milliseconds
</pre>

=== Obtaining the current time ===

''Requirements:'' Include <time.h>.

Use:
<pre>
char u[100];
time_t t=time(NULL);
tm *tmp = localtime(&t);
strftime(u,99,"%c",tmp);
sendPublic("Current date and time: " + u);
</pre>

==Writing Functions==

For this example, we will take the function called closeto, which determines
if a player exists in an specific radius around a point. Now to apply this function to a MervBot plugin, you need to write it into the spawn.cpp - at the top of the file in the //////// DLL "import" //////// setion, as below:
<pre>
//////// DLL "import" ////////

bool closeto(Player *p, int x, int y, int tolerance)
{
// Requires the function abs() to be declared elsewhere.
// Return if player p is in area of square with center x, y
// and radius = tolerance
return (abs((p->tile.x) - x) - tolerance) && (abs((p->tile.y) - y) - tolerance);
}
</pre>

If you want your function to have access to the data from spawn.h botInfo class, you make the function apart of it. To do this, we add the '''botInfo::''' infront of the function name, in spawn.cpp.
<pre>
//////// DLL "import" ////////

bool botInfo::closeto(Player *p, int x, int y, int tolerance)
{
...
}
</pre>
In '''spawn.h''', add your method's prototype without botInfo::, it will look
like this:
<pre>
//...
botInfo(CALL_HANDLE given)
{
// ...
}
bool closeto(Player *p, int x, int y, int tolerance); // Your function prototype.

void clear_objects(); //provided by Catid, and already exists.
void object_target(Player *p); //provided by Catid, and already exists.
// ...
};
</pre>
If you're not familiar with prototypes, notice it is similar to that in your spawn.cpp, but without the botInfo::, and a trailing ;.

===Function notes===

Remember that you can pass variables [http://www.cplusplus.com/doc/tutorial/tut2-3.html by reference]. If variables are passed by reference, any changes a function makes to the variables will remain after the function returns.

From time to time you will need to pass an array to a function. An example illustrating this is:
<pre>
int freqs[5]; // declare our example data.

// call function - notice freqs and not freqs[5] or freqs[].
my_function(freqs); //You're not passing the array itself, just a pointer to the array.

// function - notice freqs[] and not freqs[5] or freqs
void my_function(int freqs[]) {} //You're specifying that the freqs parameter is an array
</pre>

==Cycling through players==

MERVBot stores player-related data in a linked list. A linked list is a datatype that stores its data in a series of structures linked to each other, hence the name.

To search through the players in the arena, just start at the first link, then continue through all the following links until you reach the end:
<pre>
_listnode <Player> *parse = playerlist->head; //set to first link of the player linked list

while (parse) //parse will be NULL when we reach the last link
{
Player *p = parse->item; //item is the actual data stored in the link

// do functionality here
// Example 1: sendPrivate(p,"*watchdamage"); // turns on all pilot's watchdamage
// Example 2: if (p->safety != 0) sendPrivate(p,"*spec"); // spec all pilots in safe zone

parse = parse->next; //set parse to the next link
}
</pre>

For example, assuming our bot has smod+ privilages, the following code will set all non-spectator players to a specific ship. First begin by adding the following function prototype to the spawn.h in the botInfo class:
<pre>
void handleCmdSetShip(enum Ship_Types ship);
</pre>

In spawn.cpp add:
<pre>
void botInfo::handleCmdSetShip(enum Ship_Types ship)
{
//Note that the parameter ship is of the Ship_Types enum,
//so its value is hopefully restricted to the proper types.

_listnode <Player> *parse = playerlist->head;
while (parse)
{
Player *p = parse->item;

if ( p->ship != ship && p->ship != SHIP_Spectator )
sendPrivate(p, "*setship " + (String)ship);

parse = parse->next;
}
}
</pre>

To use, just call the function with the appropriate Ship_Type from the enum in clientprot.h:
<pre>
handleCmdSetShip(SHIP_Warbird);
</pre>

==Random numbers==

===Generating a random number===

To use this method, these two includes must be used:
<pre>
#include "time.h" //provides time() function.
#include "stdlib.h" //provides srand() and rand() functions.
</pre>

Use:
<pre>
srand(time(NULL)); // seed random number generator.

rand(); // randomize.

int temp = (int) (51 * ((float)rand()/RAND_MAX));
// the above line returns a random integer between 0 and 51.
// Note: RAND_MAX is a global constant defined in stdlib.h
</pre>

===Picking a random pilot===

''Note:'' A required user-defined function, getInGame(), must be created for this example to work.

<pre>
int temp = GetTickCount() % getInGame(); // getInGame() = how many pilots in arena

Player *rabbit = NULL;

_listnode <Player> *parse = playerlist->head;
while (parse)
{
Player *p = parse->item;

if (p->ship != SHIP_Spectator) // if player is not a spectator
if ( !(--temp) ) // and if we've hit the randomly-selected pilot
{
rabbit = p;
break;
}
parse = parse->next;
}
</pre>

==Storing data for pilots==

There are several ways to store data for pilots (ie tracking flagtime or kills in a period of time). Note that these methods are all purely internal to the bot, and don't effect anything beyond the plugin in any way.

# Built-in get/setTag: Tracks data until player leaves the arena, then automatically deletes data.
# Modified perm get/setTag: Tracks data until bot leaves arena, then automatically deletes data. (Advantage: easier to sort by player)
# Custom Structs: Tracks data until plugin deletes it. (Advantage: easier to sort by freqs)

''Note:'' 2 and 3 are similar in effect, mostly the difference is in how you are able to search through data you need to decide which method of storing data is best for each bot depending on what it does.

===Built-in get/setTag method===

Player tags simply tag a player with a number. Define the wanted values in '''spawn.h''' at the top:
<pre>
#define DMG_DEALT 0
#define DMG_TAKEN 1
</pre>

In spawn.cpp, initialize the values on ArenaEnter and PlayerEnter:
<pre>
case EVENT_ArenaEnter:
{
// ...

// do for all pilots in arena when bot enters
_listnode <Player> *parse = playerlist->head;
while (parse)
{
Player *p = parse->item; // get pilot

set_tag(p, DMG_DEALT, 0); // initialize to 0
set_tag(p, DMG_TAKEN, 0);
sendPrivate(p, "*watchdamage"); // optionally turn on player *watchdamage

parse = parse->next; // get next pilot
}
}
</pre>
<pre>
case EVENT_PlayerEntering:
{
// ...
set_tag(p, DMG_DEALT, 0); // initialize to 0
set_tag(p, DMG_TAKEN, 0);
sendPrivate(p,"*watchdamage");
}
</pre>

Then somewhere edit the tag values:
<pre>
case EVENT_WatchDamage:
{
// sets tag for k (shooter) to be old value plus damage currently dealt

int old_damage = get_tag(k, DMG_BOMB_DEALT);
set_tag(k, DMG_BOMB_DEALT, old_damage + damage);
}
</pre>

The following demonstrates how to retrieve the tag values as a command in command.cpp:
<pre>
if (c->check("showstats"))
{
int temp = get_tag(p, DMG_TOTAL_DEALT);

String s = "You've done ";
s += temp;
s += " damage so far!";

sendPrivate(p,s);
}
</pre>

===Modified permanent get/setTag method===

This method is the same as get/setTag with some modifications to the tag code to retain them after the player leaves. Beware of using this method if bot is in an arena for long periods of time, linkedlist could get huge.

// spawn.h, add char name[20]; into struct PlayerTag
<pre>
struct PlayerTag
{
Player *p;
char name[20];
int index;
int data;
};
</pre>

In spawn.cpp:
<pre>
case EVENT_PlayerLeaving:
{
Player *p = (Player*)event.p[0];

// killTags(p); // remove so tag not deleted on arena exit

// ...
</pre>

Locate in spawn.cpp and modify accordingly:
<pre>
int botInfo::get_tag(Player *p, int index)
{
_listnode <PlayerTag> *parse = taglist.head;
PlayerTag *tag;

while (parse)
{
tag = parse->item;

// if (tag->p == p)
if (strcmp(tag->name,p->name)==0) // now tracking by player name, not pointer
if (tag->index == index)
return tag->data;

parse = parse->next;
}
return 0;
}

void botInfo::set_tag(Player *p, int index, int data)
{
_listnode <PlayerTag> *parse = taglist.head;
PlayerTag *tag;

while (parse)
{
tag = parse->item;

//if (tag->p == p)
if (strcmp(tag->name,p->name)==0) // now tracking by player name, not pointer
if (tag->index == index)
{
tag->data = data;
return;
}
parse = parse->next;
}

tag = new PlayerTag;
// tag->p = p; // not tracking by pointer anymore
strncpy(tag->name, p->name, 20); // tracking by player name
tag->index = index;
tag->data = data;
taglist.append(tag);
}
</pre>

===Using structs===

In '''spawn.h''':
<pre>
class botInfo
{
struct freqdata
{
int kills, deaths;
};
// ...
};
</pre>

To make use of this structure, implement accordingly:
<pre>
freqdata freqs[100]; // 100 of those structs
</pre>
Access the data in spawn.cpp using
<pre>
freqs[56].kills = 1;
</pre>

See CPlusPlus.com's [http://www.cplusplus.com/doc/tutorial/tut3-5.html Structures] tutorial for a more comprehensive guide. Note that, as shown on the bottom of the page, you can have structures within structures. Thus, for example, you could have a structure for each freq with a structure for each player nested within them.

==Input/Output to files==

For reading and/or writing to files with C++ you must have the required include statement as follows:
<pre>
#include <fstream>
using namespace std;
</pre>

===File stream input===
The following example will show you how to read a file, duel.ini, line by line.

<pre>#include "stdlib.h" // for atoi()</pre>

<pre>
ifstream file("duel.ini");

if (!file.good()) // if there was an error opening the file
sendPublic("*arena Error opening file for reading"); // or add your own error handler
else
{
char line[256];

// read in MaxBoxes=X
while (file.getline(line, 256))
{

if (CMPSTART("MaxBoxes=", line)) //Does the line begin with MaxBoxes= ?
{
MAX_BOXES = atoi(&(line[9])); //If so, read the value into an integer, using atio.
break;
}
}

file.close();
}
</pre>

===File stream output===
The following code example will demonstrate how to append to a file, duelleaguestat.inc.
<pre>
ofstream file("duelleaguestat.inc", ios::app); // app = put all data at end of file

if (!file.good()) // if there was an error opening the file
sendPublic("*arena Error opening file.");
else
{
file << squad1<< endl; // squad1 = char[20]
file << " vs "<< endl;
file << squad2<< endl; // squad2 = char[20]
file.close();
}
</pre>

Similarly, you are able to write an output of a String to a file:
<pre>
// key is converting String to (char*) to file write
String str = freqs[freq].slotname[slot];
str += ", Repels: " + (String)(int) t->repel;
file << endl;
file << (char*) str;
</pre>

===Input with GetPrivateProfileString===

GetPrivateProfileString(), a function provided by Windows for reading INI files, will automatically find an INI key (like "MaxBoxes=") in a file for you. See the [http://msdn.microsoft.com/library MSDN Library] for help on this function. This next example will show how to read input using GetPrivateProfileString() based on the rampage plugin.

The file format for rampage.ini is like this:
<pre>
7=is on a killing spree! (6:0)
10=is opening a can of booya! (9:0)
</pre>

In '''rampageini.cpp''':
<pre>
#include "rampageini.h"
#define WIN32_LEAN_AND_MEAN
#include <windows.h>

#define NUM_RANKS 10
#define BUFFER_LEN 256

struct RampageSettings
{
char quotes[NUM_RANKS][BUFFER_LEN];
};

void LoadSettings(RampageSettings &setts);

static char path[BUFFER_LEN];

char *rank_type[NUM_RANKS] = { "7", "10" };

void LoadSettings(RampageSettings &setts)
{
GetCurrentDirectory(BUFFER_LEN - 64, path);
strcat(path, "\rampage.ini");

for (int i = 0; i < NUM_RANKS; ++i)
{
GetPrivateProfileString("Comments", rank_type[i], "-ERROR-",
setts.quotes[i], BUFFER_LEN, path);
}
}
</pre>

==Player data==

As stated earlier in the tutorial, MervBot stores useful player data internally as Player objects, see player.h for implementation details.

* p->name = player name stored as char[20] (''Note:'' SubSpace protocol allows for usernames to be 19+ in length, do not rely on this for player-name comparisions.)
* p->squad = player squad stored as char[20]
* p->ship = ship (0-9) enumerated as SHIP_Warbird, SHIP_Spectator, etc..
* p->safety = whether ship is in safety zone (boolean)
* p->bounty = player bounty
* p->energy = player energy (have bot with *energy on to get accurate readings)
* p->flagCount = how many flags player is holding
* p->team = player frequency
* p->(burst, repel, thor, brick, decoy, rocket, portal) = how many items of that type player has
* p->(stealth, cloak, xradar, awarp, ufo, flash, safety, shields, supers) = if player has that item on (boolean)
* p->score.killPoints = player kill points
* p->score.flagPoints = player flag points
* p->score.wins = player kills from f2
* p->score.losses = player deaths from f2

Just access the respective member of the Player class to check the player's property.

For example, in spawn.cpp, to check whether a player is in a safety zone:
<pre>
EVENT_PlayerMove:
{
Player *p = (Player*)event.p[0];

if ( p->safety ) // player is in safe zone.
{
// do something.
}

if ( !p->safety ) // player NOT in safe zone.
{
// do something.
}
}
</pre>

=== Obtaining a player pointer using name comparison ===

Since Player pointers are internal to MERVBot, it is necessary to find a way of obtaining a Player pointer from the identifying information given by the game. One of the simpler ways is just to compare the names after converting to lowercase.

''Note'': Using pilot names as vital comparisions should be used with caution. See [http://cypherjf.sscentral.com/articles/bots-as-clients/ Bot-Issues] by CypherJF.

<pre>
// return Player* info (or NULL if not found) from p->name info
Player * botInfo::GetPilot(char *name)
{
// get pilot from a name, return as TempPlayer
_listnode <Player> *parse = playerlist->head;

//convert search name to lowercase
char nname[20], pname[20];
strncpy(nname, name, 20);
tolower(nname);

while (parse)
{
Player *p = parse->item;

// convert to lowercase to compare
strncpy(pname,p->name,20);
tolower(pname);
if (strcmp(pname,nname)==0)
return p;

parse = parse->next;
}

return NULL; //player not found
}
</pre>

==Bot built in functions==

Here are some useful MervBot commands to control what the bot is doing.

Player.cpp:
* Player::move(Sint32 x, Sint32 y) moves a player to the coordinates specified by x and y
* Player::clone(Player *p) clones a player into a player class

Look in Commands.txt , command.cpp (core), or /!help to bot to see all bot external commands (example /!go <arena>).

''LVZ Object toggling commands in plugins are to go here.''

[[Category:Guides]]

Obtaining the Discretion Source using Subversion

2008-04-24T08:31:05Z

BaK: /* Links */ added server link

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically it is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

==Video==
The tutorial video can be obtained [[Media:disc_svn.wmv|here]].

==Links==
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

Discretion client repository: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Discretion server repository: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/server/trunk

[[Category:Discretion]]
[[Category:Guides]]

Discretion

2008-03-22T13:17:58Z

BaK: updates

[[Image:discretionss.PNG|thumb|A Screenshot of SubSpace Discretion.]]

Discretion[http://ss-discretion.sf.net] is a [[SubSpace]] client created by [[User:BaK|BaK]]. It is open source, like [[ASSS]], and is released under the [http://en.wikipedia.org/wiki/GPL GPL]. Discretion was developed because of the limitations of the in-use client, [[Continuum]]. Furthermore, the lack of development of Continuum led to a situation where limitations in the client would never be overcome. Making heavy use of [http://en.wikipedia.org/wiki/Simple_DirectMedia_Layer SDL], Discretion is cross-platform, and is currently supported under Windows, Linux, and Mac OS X. Discretion is intended to be secure through design, rather than through obscurity like Continuum. It is designed to make cheating is impossible, rather than just difficult. There is also an extensive [[Discretion Module Tutorial]] on this wiki for those interested in helping out.

Since cheating is to be made impossible, the server must check the data players send it for cheating. This requires modifying the server, which rules out using [[Subgame]]. There is, however, a modified ASSS Server that allows Discretion clients to connect.

In order to encourage client development, Discretion is designed with a modular system similar to ASSS. There are interfaces which define actions for modules (such as "draw ship at 50,50"), and callbacks which signal when events occur (such as "player has been killed"). Where ever possible, magic values have been removed and are instead loaded from plain-text settings files. The goal of this is to eliminate any built-in constraints present in VIE SubSpace and Continuum. These magic values include the location / color of the FPS counter, 1024x1024 tiles in maps, each tile being 16x16 pixels, each ship image having 40 frames thus 9 degree turns, the number of fly over tiles, two sets of doors four tiles each per map, the 0x01 type packet corresponding to an arena login, friendly players showing up yellow in the stat box, the colors in the font file, the number of frames in the wormhole animation, the text that shows up when you press ESC, the number of ships, as well as all the settings Continuum does allow you to change such as the ship images, the game play settings, and the controls. The server is intended to be able to modify most of these, thus giving [[Zone]] developers maximum creativity and flexibility.

==Modules==
Discretion is divided up into several modules, dynamically linked into the main program much like ASSS. These modules are desired to be as generic as possible, with their Continuum-like actions coming from the settings, rather than the modules themselves. Thus Discretion is like a 2D grid game engine, with settings and graphics which make it look like SubSpace. The module interfaces are documented in the corresponding header files using Javadoc-style documentation. There are currently over 30 modules in the Discretion release. Some of the main ones are discussed below.

===Settings Handler===
The '''SettingsHandler''' modules loads the settings from ini-like plain text files. The main settings file is located in conf/MAIN.CONF, which #includes many other settings files. All these settings files are plain text, meaning they can be edited using a utility like pico or notepad. Individual settings can be specified in several formats, depending on how they should be interpreted. Supported types include integers (''50'', ''0x30'', ''0777''), strings (''hello person''), points/vectors/dimensions (''(100,200)''), rgb colors (''(255,255,255)'', ''(0,128,128)''), and [[LVZ]]-style screen locations (''(C+50,50)'', ''(B-10,C+25)''). There also exists a helper function to parse comma separated a list of strings from a single sting in shared/StringManip.h. This module interface also allows modules to load their own conf files, or save a group of settings to a file which the program can then read out of.

The front end program, '''cskinviewer''' uses the saving capability of '''SettingsHandler''' to keep track of zone data between program executions.

===Module Manager===
The '''Module Manger''' itself is a module which is loaded by the program, which then proceeds to load any other modules. This uses the setting Modules::Names which is a comma separated list of strings to figure out which modules to load. It loads module files, '.dll's in Windows and '.so's in Linux, from the bin/ directory. Modules are loaded in stages. During the first stage, LOADMODE_Init, modules register their interface, if any, with the '''Module Manager''' and register any callbacks they want to listen for. During the next stage, LOADMODE_LoadInterfaces, modules load any interfaces they plan to use. Finally, during LOADMODE_PostLoadInterfaces, modules can use their loaded interfaces to other modules to initialize themselves. Upon successful program termination, LOADMODE_Unload is invoked which allows the module to free any data or resources it's using. The module manager also facilitates callbacks. Where possible, C++ exception handling is used to aid in catching errors in a non-fatal way and reports the cause of the problem.

Note that some initialization tasks should not be done in LOADMODE_PostLoadInterfaces since they require modules be initialized in a specific order. For example, the '''Text''' module, which writes text to the screen should not be initialized before the ''Graphics'' module is, since it would be unable to load the text image. Thus some initialization tasks are be done in callbacks, CB_LOADIMAGES in this instance.

===Graphics===
The '''Graphics''' module allows one to load images and draw them to the screen or map. When an image is loaded through the interface, an image handle is given to the calling module which is used to refer to the image. This handle can also be used to get the image size (taking into account that some images are framed animations), or free the image when it's no longer needed. Blank images can also be created and drawn on, thus allowing one to predraw complex images instead of redrawing them every frame. Images, when drawn to the screen, are drawn in layers. This allows several modules to queue up images to be drawn out of order and still result in a correct drawing. Some layers include L_Tiles, L_Weapons, L_AfterWeapons, L_Gauges, L_Chat and L_TopMost. Images can be drawn relative to the screen, or relative to the map. Images can also be blended such that they appear translucent, as long as the user has Graphics::UseBlending set to 1. Rectangles of a constant color can also be drawn to the screen or on to another image. The images are queued up to be drawn during the CB_PRERENDER callback.

Although providing a basic interface, it is uncommon to '''Graphics''' module directly for loading images. Instead the '''UniqueImage''' module allows one to specify an image in the settings and refer to it in code by a name. This is much easier than loading the image yourself, and easily allows a single graphic to contain many different images, which is not uncommon in SubSpace images (the bullets image, for example, contains images for all sorts of bullets rather than just a single type). The '''UniqueImage''' module makes sure to only keep a single copy of the image in memory at all times. The '''UniqueImage''' module, in turn, is used by the '''Animations''' module to provide simple access to SubSpace-style animations. Thus, a programmer can code something like 'draw animation "bullet explosion" at 512,512' and it will handle loading the image, figuring out how many frames there are, the speed of the animation, and how long to display it for.

===Controls===
The '''Controls''' module permits the programmer to provide actions("move forward"), while the settings specify exactly what keyboard or joystick input they correspond to("up arrow key"). Controls should be registered in the CB_CONTROLSLOADED callback. Also, since this a generic module it does not capture any of the physical controls itself, instead relying on other modules to handle that aspect.

The '''SDL Key Controls''' module handles capturing keyboard input and sending it to the '''Controls''' module. The '''Mouse''' module does not use the '''Controls''' module directly, instead providing its own interface which allows one to create mouse hotspots and be notified of mouse clicks or movements within these hotspots.

===Timers===
Similar to how ASSS has timers implemented in the mainloop module, Discretion has a '''Timers''' module that provides a timer functionality. One can register a function to be called in X milliseconds, or every X milliseconds until it's canceled. Discretion is currently not multithreaded beyond SDL, so that a timer in an infinite loop (or any piece of code that gets to run, for that matter), will result in the program freezing up. Thus you should not use blocking calls in timers or take up too much processing time which will degrade performance.

The '''Net''' module uses a timer to send and receive packets.

===Text===
The '''Text''' module provides an easy way to draw text on the screen. This is the standard subspace text and can be specfied by color. This module draws the text on one line for a single frame. Therefore, you must call the appropriate functions in this interface during CB_PRERENDER every frame for however long you wish to display the text. There is support for drawing text relative to the screen or to the map, as well as blending text and drawing on any layer.

The '''Textbox''' module uses '''Text''' to draw its text, but provides additional features such as drawing textbox borders and allowing easy textbox loading from files. '''EscapeBox''' and '''PlayerList''', in turn, use '''Textbox'''. '''Chat''' also makes use of the '''Text''' module when it draws player chat to the screen. The '''Flash''' module, which handles messages similar to SubSpace's kill and prize messages, also uses the '''Text''' module. Pretty much anywhere you see text, the '''Text''' module is at work.

===Physics===
The '''Physics''' module provides functions which can give you a particle's new position given its initial position, velocity, and time elapsed. This is used for ships as well as weapons. The position can be advanced in such a way that is affected by the map (such as bombs going around a wormhole), or not. Particles can bounce off the level or explode on contact.

The '''SelfShip''' module uses '''Physics''' to compute the new position of the player over time. '''SS_Items''' uses '''Physics''' to find the position of a bullet after a certain amount of time.

===PerPlayerData===
The '''PerPlayerData''' module provides a simple way to have data that is common to every player. This is similar to ASSS' PlayerData module in that a struct of memory can be allocated for every player and referred to using a key. The module also facilitates simple sharing of per player data between module such as "name", "x", or "y".

The '''PlayerList''' module uses the sharing facility of '''PerPlayerData''' to get the names of the players on the player list.

===Level===
The '''Level''' module provides a simple interface to possibly many different types of level formats. Modules can load levels through the interface, as well as get the map or tile size. Furthermore, forces on the level, such as wormholes, friction, or gravity can be applied through the interface.

Currently, the only map format implemented is '''oldlvl''' which supports regular SubSpace [[LVL]] files. This provides a somewhat more generic implementation, which a customizable amount of doors or custom animation tiles (wormholes, space station, and asteriods), as well as having wormholes with different properties on the same map.

===Front End===
The front end, not exactly a module, is implemented as its own program, '''cskinviewer''', contributed by [[User:Smong|Smong]]. This program allows one to download a list of ASSS servers from a [[Directory Server]], and choose one and login. It uses the '''SettingsHandler''' to save the current zone list to the settings. Custom zones can not be added through the interface yet, but can be added by hand by editing conf/profiles/ZoneList.conf.

The front end executes '''in_game''', which in turn loads the '''Module Manager''' which runs '''Main SDL''' which runs callbacks to load the various SDL Subsystems and starts the program's main loop.

==Contribute==
Development for Discretion is ongoing and everyone is encouraged to contribute. Graphics are always helpful, and if you have an idea feel free to make it. In the spirit of free software, it would be best if eventually all VIE owned graphics were replaced, as their copyright status is unknown. This includes the ships, bullets, default tileset, and all other graphics from VIE SubSpace or Continuum. Also, a Discretion [[skin]] is yet to be made for the front end (the format follows that of Continuum's, see the skins directory in your Continuum folder). Additionally, many features are in development or unimplemented. If one wanted to help out, just contact [[User:BaK|BaK]], or start working on graphics or a module. There is also a [[Discretion Module Tutorial]] which shows you how to create a simple module. Some planned modules include:

====Star Background====
A '''StarBackground''' module that draws stars and planets similar to how Continuum does it. It would be great it this looked better than Continuum as it would really lead to the immersion necessary for a fun experience. This could also be used to draw all sorts of backgrounds, such as grass for earth-based zones, to provide an alternate to tiling LVZ all over the map. This would be a good module to make to get introduced to Discretion development.

====LVZ====
A reverse compatible LVZ module is desired to allow current zones to easily switch over to Discretion without remaking their lvz files. This could provide additional functionality not present in current lvz such as lvz that depend on ship locations to allow animations within shipsets. The easier way to make this is probably to make a static image/animation module which uses the settings and '''UniqueImage''' and '''Animations''' to draw images on the map and screen. Then, an lvz compatibility layer module would be made which translates an lvz file into a .conf file and uses '''SettingsHandler''' to load in the images from the generated file.

====Radar====
Subspace and Continuum include a radar for locating enemies. This will have to be implemented in Discretion. The users should also be able to make the radar bigger by pressing a key (alt).

====Sound====
Sound provides immersion in video games and gives them an authentic feel. We need a way to play sounds when certain actions occur such as a bullet being fired or player bouncing off a wall. WAV sounds will have to be implemented for reverse compatibility, but mp3 is not out of the question for longer sounds such as victory music or just music in general. After this is done, a built in mp3 player could be made to allow players to change songs from within the game. SDL_mixer[http://www.libsdl.org/projects/SDL_mixer/] provides mp3 capabilities and may be used.

====Weapons====
Currently, only non-bouncing bullets are implemented. There are many items SubSpace uses which must be implemented. Care must be taken here to prevent cheating. For example, it would not be difficult to write a program to detect right before a player is about to get hit and automatically portal out or repel. Thus, these items may have to be modified to be on a timer, so that using a portal might require your ship to take a second to "charge up" instead of instantly warping. Also, it would be great if weapons didn't have to follow boring straight lines and instead could turn. Thus I could specify in the settings the direction a weapon would travel if the ship were facing straight up and it would happen. So a straight line would be (0,t), a curvy shot may be (sin(t),t), a shot that speeds up over time may be (0,2^t).

====Custom Client Side Code====
The server should be able to provide code that can be executed client side. There are two types of code that will be provided: updated versions of modules, and game play related code. This is especially dangerous since a malicious server owner should not be permitted to compromise players' computers. The module updates can be done by providing a RSA signature with the binary .dll or .so which can be checked before executing any downloaded files. As for game play related code, a Java virtual machine could be used with a Security Manager that allows nothing beyond basic functions. Then, an interface could be provided to the game code that could be used by the code. Thus, binary .class file could be distributed for an arena that aren't allowed to delete files off your computer, but are allowed to access the game play relayed interface thus permitting graphics to be drawn or players to be warped around.

==External links==
*[http://ss-discretion.sf.net Main Discretion Website]

[[Category: Clients]]
[[Category: Discretion]]

Core Protocol

2008-03-18T05:39:20Z

BaK: spacing

This protocol is UDP and bi-directional. It can be thought of as another layer within an application's network layer. [[Subgame]], [[ASSS]], [[Continuum]], VIE's [[SubSpace]] client, the [[Directory server]], and some [[Billing Server|Billing Servers]] utilize this protocol.

There is support for reliable ordered packets, large packets and cluster packets.

*The maximum packet size is 520 bytes
*All integers are little endian
*All core packets begin with the type byte 0x00
*Packets can be nested (They are usually processed recursively)

<pre>
0x01 login
offset size comment
0 1 type 0x00
1 1 type 0x01
2 4 client key
6 2 protocol version (vie = 0x01, ctm = 0x11)

0x02 login response
offset size comment
0 1 type 0x00
1 1 type 0x02
2 4 ~client key (negative)

0x03 reliable header
offset size comment
0 1 type 0x00
1 1 type 0x03
2 4 packet id
6 ? payload (514 max)

0x04 reliable acknowledge
offset size comment
0 1 type 0x00
1 1 type 0x04
2 4 packet id

0x05 sync
offset size comment
0 1 type 0x00
1 1 type 0x05
2 4 local time
6 4 packets sent
10 4 packets received

0x06 sync response
offset size comment
0 1 type 0x00
1 1 type 0x06
2 4 time from last received 0x05 packet
6 4 server time

0x07 disconnect
offset size comment
0 1 type 0x00
1 1 type 0x07

0x08 small chunk
offset size comment
0 1 type 0x00
1 1 type 0x08
2 ? payload (expect 472 max)
keep appending payloads until 0x09 chunk tail is received

0x09 chunk tail
offset size comment
0 1 type 0x00
1 1 type 0x09
2 ? payload (expect 472 or less)
append this payload then process contents as a non-core packet

0x0A stream
offset size comment
0 1 type 0x00
1 1 type 0x0A
2 4 total length of all segments
6 ? payload
keep appending payloads until total length is reached then process contents as
a non-core packet.

0x0B cancel stream request
offset size comment
0 1 type 0x00
1 1 type 0x0B

0x0C cancel stream acknowledge
offset size comment
0 1 type 0x00
1 1 type 0x0C

0x0E cluster
offset size comment
0 1 type 0x00
1 1 type 0x0E
2 1 length
3 ? payload with length as above
packet repeats from offset 2 until end, process contents as arbitrary packet

0x10 Continuum alternate encryption response (s2c)?
offset size comment
0 1 type 0x00
1 1 type 0x10
2 10 ??

0x11 Continuum alternate encryption response response (c2s)?
offset size comment
0 1 type 0x00
1 1 type 0x11
2 6 ??
</pre>

[[Category: Protocol]]

Core Protocol

2008-03-18T05:38:56Z

BaK: observed some undocumented packets "in the wild" so I'd figure I'd add them

This protocol is UDP and bi-directional. It can be thought of as another layer within an application's network layer. [[Subgame]], [[ASSS]], [[Continuum]], VIE's [[SubSpace]] client, the [[Directory server]], and some [[Billing Server|Billing Servers]] utilize this protocol.

There is support for reliable ordered packets, large packets and cluster packets.

*The maximum packet size is 520 bytes
*All integers are little endian
*All core packets begin with the type byte 0x00
*Packets can be nested (They are usually processed recursively)

<pre>
0x01 login
offset size comment
0 1 type 0x00
1 1 type 0x01
2 4 client key
6 2 protocol version (vie = 0x01, ctm = 0x11)

0x02 login response
offset size comment
0 1 type 0x00
1 1 type 0x02
2 4 ~client key (negative)

0x03 reliable header
offset size comment
0 1 type 0x00
1 1 type 0x03
2 4 packet id
6 ? payload (514 max)

0x04 reliable acknowledge
offset size comment
0 1 type 0x00
1 1 type 0x04
2 4 packet id

0x05 sync
offset size comment
0 1 type 0x00
1 1 type 0x05
2 4 local time
6 4 packets sent
10 4 packets received

0x06 sync response
offset size comment
0 1 type 0x00
1 1 type 0x06
2 4 time from last received 0x05 packet
6 4 server time

0x07 disconnect
offset size comment
0 1 type 0x00
1 1 type 0x07

0x08 small chunk
offset size comment
0 1 type 0x00
1 1 type 0x08
2 ? payload (expect 472 max)
keep appending payloads until 0x09 chunk tail is received

0x09 chunk tail
offset size comment
0 1 type 0x00
1 1 type 0x09
2 ? payload (expect 472 or less)
append this payload then process contents as a non-core packet

0x0A stream
offset size comment
0 1 type 0x00
1 1 type 0x0A
2 4 total length of all segments
6 ? payload
keep appending payloads until total length is reached then process contents as
a non-core packet.

0x0B cancel stream request
offset size comment
0 1 type 0x00
1 1 type 0x0B

0x0C cancel stream acknowledge
offset size comment
0 1 type 0x00
1 1 type 0x0C

0x0E cluster
offset size comment
0 1 type 0x00
1 1 type 0x0E
2 1 length
3 ? payload with length as above
packet repeats from offset 2 until end, process contents as arbitrary packet

0x10 Continuum alternate encryption response(s2c)?
offset size comment
0 1 type 0x00
1 1 type 0x10
2 10 ??

0x11 Continuum alternate encryption response response (c2s)?
offset size comment
0 1 type 0x00
1 1 type 0x11
2 6 ??
</pre>

[[Category: Protocol]]

User talk:Mine GO BOOM

2008-03-18T04:13:17Z

BaK: yeah..

I was cutting my wiki teeth on here yesterday- I apologize for the unneccesary updates. 
Was the formatting and content ok?

[[User:I88gerbils|i88gerbils]]: Where's rollback? I'm trying to look up that functionality but can't find it on the Wiki help site. update: I see, it's an admin. command. :)

[[User:I88gerbils|i88gerbils]]: Please delete the dumbass duplicate page I created today. Thanks.

== mineplowers.com ==

[[User:Mine GO BOOM|Mine GO BOOM]] 23:35, 30 May 2006 (EDT): This is the wiki running off mineplowers.com.

awesome, thanks [[User:BaK|BaK]] 21:13, March 17, 2008 (PDT)

Talk:MERVBot Tutorial

2008-03-17T05:43:53Z

BaK: yea.. .mem leak

==hmm==
Modified permanent get/setTag method = memory leak... boo
telling them to beware is eh... i dunno [[User:BaK|BaK]]

==General Convo==
D1s: Anybody wanna format this int a table of contents? I'm lazy

[[User:Smong|Smong]]: That is sick. Maybe split into more pages? Says it is over 160k.

[[User:Pests|Pests]]: There is already pages defined. You could just split them up into that.

OK, I'm working on converting it to real HTML (using <pre>) instead of the &nbsp; crap. --[[User:Cyan~Fire|Cyan~Fire]]

[[User:CypherJF|CypherJF]]: Should we just call this "the bot tutorial" based on the tutorial by Underlord? Then update it accordingly? -- And also, the link to MervBot w/e 37 is now 45; should we just comment that this tutorial was writen for the 37 -- or... comments! lol.

[[User:CypherJF|CypherJF]]: I'd like to say that all sections appear to have been updated for the Wiki; time to go through edit, and catch mistakes. Add to the wiki itself - perhaps more example code.

[[User:CypherJF|CypherJF]]: Cyan and I were talking about the section "Checking if pilot is in a safe zone"; whether or not to just remove it. I remarked that it's a nice section for those to the whole plugin deal. But, I was just noticing how it'd make more sense to put the "Useful Player data" before hand... So i guess the next step is to go through and try to address the logical-aspect of ordering of the content? What's your guys' take?

[[User:Smong|Smong]]: Uh yeah.. so why are there so many major edits to just one page? I can't see anything in recent changes but edits to the mervbot tutorial.

[[User:CypherJF|CypherJF]]: See my other notes: "CypherJF: Well I've been doing the edits from all around campus. Like yesterday I did 4-6 things from the MathLab; and the rest from the dorm, etc. lol. I don't think it really matters, since there isn't much other activity going on.. on the wiki." So, I'd make edits and just post em. It happened to be the only activity and sooo it looks worse than it is.

== sscanf ==

Well, I'm using sscanf() for parsing player input. Yes, an advanced function, but maybe it will discourage C++ newbs from making bot plugins. Any comments? --[[User:Cyan~Fire|Cyan~Fire]]

D1st0rt: Cool beans. I learned something new :D

== Event list ==

Removed event list because it was redundant with dllcore.h, less descriptive, and too easy to get out-of-date. Anybody who wants it back, please post here so I can ignore you. :-D --[[User:Cyan~Fire|Cyan~Fire]]

[[User:CypherJF|CypherJF]]: Like people are really going to read through the dllcore.h file.. on a webpage tutorial. hmm i think not. I still say keep it there.

If someone doesn't make the effort to look up events in dllcore.h, they shouldn't be making plugins. I think of this tutorial as more of a "here are the basics and intricacies of making a MERVBot plugin" more than "here is how to follow step-by-step instructions and call it programming". --[[User:Cyan~Fire|Cyan~Fire]]

D1s: Even ''I'' look up things in dllcore.h, its a very useful resource. As long as it says to look in it, I don't think we'd need the full list here

== Extra Code Samples ==
[[User:CypherJF|CypherJF]]: I'd like to somehow split these up better; and make them linkable, what do you guy's think?

[[User:CypherJF|CypherJF]]: I made sub-headers, and so they'll be added into the table of contents. Let me know what you guys think of it.

Alrighty, looks good. One thing I would ask is to try to save up a bunch of edits in a text editor or something, than have the myriad edits you do now. Thanks for sharing the burden with me! --[[User:Cyan~Fire|Cyan~Fire]]

[[User:CypherJF|CypherJF]]: Well I've been doing the edits from all around campus. Like yesterday I did 4-6 things from the MathLab; and the rest from the dorm, etc. lol. I don't think it really matters, since there isn't much other activity going on.. on the wiki.

Oh, OK, that's fine. Also, do remember that the wiki will automatically do your ing for you as long as you leave a blank line in-between "paragraphs". --[[User:Cyan~Fire|Cyan~Fire]]

== Example Code commenting system ==

What's the use of it? --[[User:Cyan~Fire|Cyan~Fire]]

[[User:Smong|Smong]]: So if people don't understand the examples they can request help or a clarification. Also people that do understand an example might want to post a better/alternative solution. I suppose since you need an account to edit a page, maybe the wiki can be setup so you don't need an account to edit the discussion page so people can put comments in there.

I think I wasn't being very clear, Cypher didn't understand me either. I was talking about his  stuff. Anyway, I've gotten permission from him to remove it, it was only supposed to be temporary. The idea of anonymous talk posts is a good idea, but I'm not sure if its possible. --[[User:Cyan~Fire|Cyan~Fire]]

== Make bot spectate specific coordinates Section ==
--[[User:50% Packetloss|50% Packetloss]] 14:34, Feb 21, 2005 (EST)

This is what is currently there.
<pre>
tell(makeFollowing(false));
tell(makeFlying(true));
me->move(512 * 16, 600 * 16);
tell(makeSendPosition(true));
</pre>

Now when you tell the bot tell(makeFlying(true)); the core makes DLLFlying= true; Thus in the core's function void Host::doEvents() instead of the bot sending position packets, the job is left to the dll.
<pre>
//...
if (DLLFlying)
{
Uint32 limit = settings.SendPositionDelay;

if (time - lastPosition > limit)
{
imports->talk(makePositionHook());
}
}
else if (Me->ship == SHIP_Spectator)
{ // Spectating
Uint32 limit = settings.SendPositionDelay;

if (time - lastPosition > limit)
{
// Cycle player spectated
if (Me->ship == SHIP_Spectator)
spectateNext();

sendPosition(false);
}
}
else if //...
</pre>
So in the dll, in the positionhook event, you need to add tell(sendPosition(false));. Im not sure if it will have a dramatic effect if the bot is in spec (never tested it), but if the bot is in a ship it will disappear from the screen. I don't know a lot about this wiki stuff so Ill leave it up to you ladies to edit.

== Random Number Selection ==

When picking a random number, the code for [[MERVBot_Tutorial#Picking_a_random_pilot|Picking a random pilot]] works off GetTickCount, which is very bad. GTC does not have single digit accuracy, and you can see this by running a loop for a couple of seconds and 'bucketing' the return values module X. If X is something like 25 or 50, you'll see very obvious patterns, where certain numbers are skipped completely. Even modulo something smaller like 10, and the distribution is horrible. The section right above this uses rand() correctly. In a simple tutorial, even rand() % X is much better than GTC() % X.

== About recent code changes ==

[[User:Mine GO BOOM|Mine GO BOOM]] 22:42, Jun 8, 2006 (EDT): Instead of using numbers in the code, such as '9' in atoi and 256 for str, you should use sizeof. If you change the size of str in the future, makes it easier to handle, and is also less prone to errors when you are coding, as you '''know''' it won't overflow the variable (unless it doesn't tack on '\0' at the end, check documentation on that function?).

Obtaining the Discretion Source using Subversion

2008-03-17T05:33:22Z

BaK: category'd

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically it is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

==Video==
The tutorial video can be obtained [http://ews.uiuc.edu/~sbak2/disc/disc_svn.wmv here].

==Links==
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

[[Category:Discretion]]
[[Category:Guides]]

Discretion Commands and Displaying Images

2008-03-17T05:11:51Z

BaK: format

This is a tutorial for module creation in [[Discretion]]. For other tutorials, see the [[Discretion Module Tutorial]].

In this tutorial, you wil learn how to listen for chat commands using Discretion's Chat Module as well as how to load and display images on the screen using UniqueImage and Graphics.

Topics covered: Listening for Callbacks, Using Interfaces, UniqueImage, Graphics

We will make two commands, ?show and ?hide which will cause a graphic to appear and disappear on the screen.

The first thing we'll do is make the graphic we want to display and put it in our Discretion/graphics folder. This can be done in a progam such as Paint. Here we saved the file as my_testimage.png.

[[Image:cg_1.PNG]]

Now onto the code, make a module as specified in the [[Creating and Testing a Simple Discretion Module]] tutorial. The first thing we're going to do is listen to the callback when commands are sent through the chat. Callbacks in Discretion are similar to callbacks in AS3. They represent events that occur that you can react to. Callbacks are registered through the module manager.

<pre>
/**
* - tells the module manager that you want to receive a callback
* @param myVersion the version of the module requresting this callback, this is useful in
* debugging if we were to cause a crash while we're in a callback
* @param callbackName is a name string that will tell the module manager which callback you want
* to receive
* @param callbackVersion is the version string for the callback. If you use an antiquated version,
* and a different version of the callback is called, an error will be recorded
* @param func is a function pointer to a function that should be called when the callback occurs,
* note that all callback functions are of the same form, but you can cast the parameter to a more
* usable form. Donâ€™t change the param, as it must be used to call the other functions too
*/
void (*regCallback)(const char* myVersion, const char* callbackName, const char* callbackVersion, callbackFunc func);
</pre>

Here we pass in myVersion, which is used only if there's a problem with your callback handler, so make it something that you will be able to recognise when it's printed to the console, such as "show-hide graphic module" or the interface handle if you have an interface defined, or even the C preprocessor macro __FILE__ will work. callbackName and callbackVersion are unique to the callback, more on that in a moment, func is the function to call when the callback occurs. callbackFunc is typedefed to a function pointer:

<pre>
typedef void (*callbackFunc)(void* param);
</pre>

In general, you can figure out information about the callback in the file where it's defined. For the command callback we're interested in, we look in Chat.h:

<pre>
// occurs when a possible internal command is sent, if you're processing this command set processed to TRUE
#define CB_INTERNALCOMMAND "InternalCommand"
#define CB_INTERNALCOMMAND_VERSION "1"
// the parameter is as follows, set processed to TRUE if you process it
struct InternalCommandParam
{
const char* command; // the entire command line, with parameters and everything, but no command character
BOOL processed; // set this to true if you process the command

// you can use this function to check if this command is yours, sets processed for you
// setToParams points to whatever's after the command if successful, can be NULL if you don't care
BOOL isCommand(const char* what, const char** setToParams)
{
...
}
};
</pre>

Here the callback name is defined to CB_INTERNALCOMMAND and callback version is defined to CB_INTERNALCOMMAND_VERSION. The parameter to the callback, which is a anonymous pointer (void*) can be cast to a InternalCommandParam*. We then use the isCommand to check if this is the command we're interested in.

So now to register the internal command callback with the module manager and print out a message to the console when we receive "?show" or "?hide". Note that we have to #include "Chat/Chat.h" because that's where the callback is defined.

<pre>
// Commands - Graphics Tutorial Discretion Module
#include "Module.h"
#include "Chat/Chat.h"

ModuleManager* mm = 0;

void gotInternalCommand(void* param)
{
InternalCommandParam* icp = (InternalCommandParam*)param;

if (icp->isCommand("show",0))
{
printf("Received Command: show\n");
}
else if (icp->isCommand("hide",0))
{
printf("Received Command: hide\n");
}

}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_Init)
{
mm->regCallback(__FILE__, CB_INTERNALCOMMAND, CB_INTERNALCOMMAND_VERSION, gotInternalCommand);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

We should be able to make this module and see the effect when we type ?show and ?hide and press enter in the chat.

[[Image:cg_2.PNG]]

Now onto making an image display on the screen. There are two steps to this, loading the image, and drawing the image on the screen. Loading the image can be done in a few ways, the easiest is to use the UniqueImage module. The UniqueImage module loads settings from conf files, so you can refer to the image by name in the code. UniqueImage also ensures the image is only loaded once (it's unique), so that you can use the same image in different modules without worrying about wasting memory. Unique image will give you an image handle from an image name. An image handle is just an int, which we can pass to Graphics when we're drawing the image. First we'll define the image in the conf files. Open up Image.conf in conf/visual/ and add <Image Name>Path = <path to image> and <Image Name>Frames = (1, 1) to the bottom of the file. In the picture we use CommandsGraphicsTutorial as the name of our image... this is what we'll refer to the image in the code, just make sure it isn't the same as any of the other names. The Frams setting defines how many frames are in the image, for example ships are typcially defined in a single file with 40 images aranged 10 wide and 4 tall, so we'd use (10,4) for the frames if we had such an image. For our image though, we only use a single frame so (1, 1) is correct.

[[Image:cg_3.PNG]]

Now we have to get the UniqueImage interface and use it. Interfaces are generally loaded during LOADMODE_LoadInterfaces in getClassInstance. They are gotten using the interface identifier and the module manager. The interface identifier is defined in UniqueImage.h

<pre>
#define I_UNIQUEIMAGE "UniqueImage-1"
</pre>

To use this constant we need to #include "UniqueImage/UniqueImage.h". In getClassInstance, if lm is LOADMODE_LoadInterfaces, we use the module manager to load the interface using the getInterface function.

<pre>
/**
* - tells the module manager that you want an interface. If the interface is not loaded by the
module manager, an error will result which the module manager takes care of
* - this should be called when getInstance(MODE_LoadInterfaces) is called
* @param myVersion the version of the module calling this function
* @param getVersion the version of the module we want to load
* @return a void* pointing to the class interface of the loaded module
*/
void* (*getInterface)(const char* myVersion, const char *getVersion);
</pre>

Here getVersion is I_UNIQUEIMAGE, myVersion, as in callbacks, is only used in case of errors. We can use __FILE__ or an identfying string like "commands-graphics tutorial". We save the pointer returned by getInterface. The question now is when should we call UniqueImage's getImageHandle function. We want to make sure that we do not call it too early, because the image loading system may not be initialized. This problem is solved through callbacks. For loading images, there is a callback that says "the image loading system is initialized, load your images now". This callback is in Graphics.h, CB_LoadImages.

<pre>
/*
This LoadImage callback will be called when the images are to be loaded, there is no parameter
This is guarenteed to be in POSTLOAD_Interfaces
*/

#define CB_LOADIMAGES "LoadImages"
#define CB_LOADIMAGES_VERSION "1"
</pre>

So we register a callback for this function (and #include "Graphics/Graphics.h"), and load our image and save the image handle UniqueImage gives us.

<pre>
// Commands - Graphics Tutorial Discretion Module
#include "Module.h"
#include "Chat/Chat.h"
#include "UniqueImage/UniqueImage.h"
#include "Graphics/Graphics.h"

ModuleManager* mm = 0;
UniqueImage* ui = 0;

int imageHandle = 0;

void gotInternalCommand(void* param)
{
InternalCommandParam* icp = (InternalCommandParam*)param;

if (icp->isCommand("show",0))
{
printf("Received Command: show\n");
}
else if (icp->isCommand("hide",0))
{
printf("Received Command: hide\n");
}
}

void loadImages(void* param)
{
imageHandle = ui->getImageHandle("CommandsGraphicsTutorial");
}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_Init)
{
mm->regCallback(__FILE__, CB_INTERNALCOMMAND, CB_INTERNALCOMMAND_VERSION, gotInternalCommand);
mm->regCallback(__FILE__, CB_LOADIMAGES, CB_LOADIMAGES_VERSION, loadImages);
}
else if (lm == LOADMODE_LoadInterfaces)
{
ui = (UniqueImage*)mm->getInterface(__FILE__,I_UNIQUEIMAGE);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

Now that we have the image, we need to draw it on the screen. This is done using the Graphics interface. We get this interface similar to how we got the UniqueImage interface (in getClassInstance where lm == LOADMODE_LoadInterfaces). The function we're interested is one that draws images on the screen:

<pre>
/** Draw an image in the next frame, this is to be done in the prerender callback
* This one draws relative to screen coordinates, rather than absolute coordinates, no bounds checking is done
* @param imageHandle an image handle from the loadImage function
* @param frame the frame of the image to draw on, for example the rotated ship graphic is 0-39
* @param xPixel the xPixel to draw with, this in screen coordinates
* @param yPixel the yPixel to draw with, this in screen coordinates
* @param Layer the layer to draw on, probably from the enum Layer
* @blend a number between 0 and 100 to determine how much blending is to be done for this image,
* so 0 is completely transparent and 100 is opaque
*/
void (*drawScreenImage)(int imageHandle, int xPixel, int yPixel, int frame, int layer, int blend);
void (*drawScreenImage2)(int imageHandle, int xPixel, int yPixel, int layer);
</pre>

imageHandle is the handle we got from UniqueImage, xPixel is the x pixel to use for the left part of the image, yPixel is the y pixel for the top of the image. (0, 0) is the upper left corner of the screen, with y increasing downward and x increasing rightward. Frame is the frame of the image to draw, for us this is 0 since we have only a single frame defined in our image. Layer is layer to draw on, some common ones are given in the enum Layer. Blend is the amount to blend the image, 100 for opaque images and fading to completely transparent when blend is 0. Here is the layer enum:

<pre>
// The layer enum, note you can define your own layers between these ones if you want
enum Layer
{
L_BelowAll = 50,
L_Background = 100,
L_AfterBackground = 150,
L_Tiles = 200,
L_AfterTiles = 250,
L_Weapons = 300,
L_AfterWeapons = 350,
L_Ships = 400,
L_AfterShips = 450,
L_Gauges = 500,
L_AfterGauges = 550,
L_Chat = 600,
L_AfterChat = 650,
L_TopMost = 700
};
</pre>

The question now is when we should call drawScreenImage. The answer is, once again, in a callback. The callback in this case is in Graphics.h, PreRender:

<pre>
// The parameter to the prerender callback
struct PrerenderParam
{
PrerenderParam(int m, Rect* s) : milDif(m) , screen(s) {}

int milDif; // milliseconds since last prerender callback, or 0 on the first one
Rect* screen; // the screen bounds, in pixels
};

// The prerender callback
#define CB_PRERENDER "Pre-render"
#define CB_PRERENDER_VERSION "2"
</pre>

This callback occurs every frame, when we call drawScreenImage, it will get drawn for a single frame. We register the callback like we did for LoadImages and InternalCommand. We then call drawScreenImage based on whether the user has used ?show or not. The final version the code is below:

<pre>
// Commands - Graphics Tutorial Discretion Module
#include "Module.h"
#include "Chat/Chat.h"
#include "UniqueImage/UniqueImage.h"
#include "Graphics/Graphics.h"

ModuleManager* mm = 0;
UniqueImage* ui = 0;
Graphics* g = 0;

int imageHandle = 0;
bool showImage = false;

void gotInternalCommand(void* param)
{
InternalCommandParam* icp = (InternalCommandParam*)param;

if (icp->isCommand("show",0))
{
showImage = true;
}
else if (icp->isCommand("hide",0))
{
showImage = false;
}
}

void loadImages(void* param)
{
imageHandle = ui->getImageHandle("CommandsGraphicsTutorial");
}

void preRender(void* param)
{
if (showImage)
{
g->drawScreenImage2(imageHandle, 200, 200, L_TopMost);
}
}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_Init)
{
mm->regCallback(__FILE__, CB_INTERNALCOMMAND, CB_INTERNALCOMMAND_VERSION, gotInternalCommand);
mm->regCallback(__FILE__, CB_LOADIMAGES, CB_LOADIMAGES_VERSION, loadImages);
mm->regCallback(__FILE__, CB_PRERENDER, CB_PRERENDER_VERSION, preRender);
}
else if (lm == LOADMODE_LoadInterfaces)
{
ui = (UniqueImage*)mm->getInterface(__FILE__,I_UNIQUEIMAGE);
g = (Graphics*)mm->getInterface(__FILE__,I_GRAPHICS);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

And when we run this module in Discretion we get the desired result:

[[Image:cg_4.PNG]]

Hopefully, by now you are comfortable with listening to callbacks and using interfaces as well as more familiar with the UniqueImage and Graphic modules. Here's a few things you can try to do:

- Instead of drawing the image on the screen, draw it on the map at pixel 8200,8200, and make it so that you can fly over it with your ship.

- Make your image have two frames instead of just a single one, and use a command "?switch" to change the frame of the image being displayed.

- Add a command "?blend <int>" where <int> is an integer specifying the blend amount to use. Observe the effects of different blend values.

[[Category:Discretion]]
[[Category:Guides]]

Discretion Commands and Displaying Images

2008-03-17T05:11:18Z

BaK: fixed internal link

This is a tutorial for module creation in [[Discretion]]. For other tutorials, see the [[Discretion Module Tutorial]].

In this tutorial, you wil learn how to listen for chat commands using Discretion's Chat Module as well as how to load and display images on the screen using UniqueImage and Graphics.

Topics covered: Listening for Callbacks, Using Interfaces, UniqueImage, Graphics

We will make two commands, ?show and ?hide which will cause a graphic to appear and disappear on the screen.

The first thing we'll do is make the graphic we want to display and put it in our Discretion/graphics folder. This can be done in a progam such as Paint. Here we saved the file as my_testimage.png.
[[Image:cg_1.PNG]]

Now onto the code, make a module as specified in the [[Creating and Testing a Simple Discretion Module]]. The first thing we're going to do is listen to the callback when commands are sent through the chat. Callbacks in Discretion are similar to callbacks in AS3. They represent events that occur that you can react to. Callbacks are registered through the module manager.

<pre>
/**
* - tells the module manager that you want to receive a callback
* @param myVersion the version of the module requresting this callback, this is useful in
* debugging if we were to cause a crash while we're in a callback
* @param callbackName is a name string that will tell the module manager which callback you want
* to receive
* @param callbackVersion is the version string for the callback. If you use an antiquated version,
* and a different version of the callback is called, an error will be recorded
* @param func is a function pointer to a function that should be called when the callback occurs,
* note that all callback functions are of the same form, but you can cast the parameter to a more
* usable form. Donâ€™t change the param, as it must be used to call the other functions too
*/
void (*regCallback)(const char* myVersion, const char* callbackName, const char* callbackVersion, callbackFunc func);
</pre>

Here we pass in myVersion, which is used only if there's a problem with your callback handler, so make it something that you will be able to recognise when it's printed to the console, such as "show-hide graphic module" or the interface handle if you have an interface defined, or even the C preprocessor macro __FILE__ will work. callbackName and callbackVersion are unique to the callback, more on that in a moment, func is the function to call when the callback occurs. callbackFunc is typedefed to a function pointer:

<pre>
typedef void (*callbackFunc)(void* param);
</pre>

In general, you can figure out information about the callback in the file where it's defined. For the command callback we're interested in, we look in Chat.h:

<pre>
// occurs when a possible internal command is sent, if you're processing this command set processed to TRUE
#define CB_INTERNALCOMMAND "InternalCommand"
#define CB_INTERNALCOMMAND_VERSION "1"
// the parameter is as follows, set processed to TRUE if you process it
struct InternalCommandParam
{
const char* command; // the entire command line, with parameters and everything, but no command character
BOOL processed; // set this to true if you process the command

// you can use this function to check if this command is yours, sets processed for you
// setToParams points to whatever's after the command if successful, can be NULL if you don't care
BOOL isCommand(const char* what, const char** setToParams)
{
...
}
};
</pre>

Here the callback name is defined to CB_INTERNALCOMMAND and callback version is defined to CB_INTERNALCOMMAND_VERSION. The parameter to the callback, which is a anonymous pointer (void*) can be cast to a InternalCommandParam*. We then use the isCommand to check if this is the command we're interested in.

So now to register the internal command callback with the module manager and print out a message to the console when we receive "?show" or "?hide". Note that we have to #include "Chat/Chat.h" because that's where the callback is defined.

<pre>
// Commands - Graphics Tutorial Discretion Module
#include "Module.h"
#include "Chat/Chat.h"

ModuleManager* mm = 0;

void gotInternalCommand(void* param)
{
InternalCommandParam* icp = (InternalCommandParam*)param;

if (icp->isCommand("show",0))
{
printf("Received Command: show\n");
}
else if (icp->isCommand("hide",0))
{
printf("Received Command: hide\n");
}

}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_Init)
{
mm->regCallback(__FILE__, CB_INTERNALCOMMAND, CB_INTERNALCOMMAND_VERSION, gotInternalCommand);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

We should be able to make this module and see the effect when we type ?show and ?hide and press enter in the chat.

[[Image:cg_2.PNG]]

Now onto making an image display on the screen. There are two steps to this, loading the image, and drawing the image on the screen. Loading the image can be done in a few ways, the easiest is to use the UniqueImage module. The UniqueImage module loads settings from conf files, so you can refer to the image by name in the code. UniqueImage also ensures the image is only loaded once (it's unique), so that you can use the same image in different modules without worrying about wasting memory. Unique image will give you an image handle from an image name. An image handle is just an int, which we can pass to Graphics when we're drawing the image. First we'll define the image in the conf files. Open up Image.conf in conf/visual/ and add <Image Name>Path = <path to image> and <Image Name>Frames = (1, 1) to the bottom of the file. In the picture we use CommandsGraphicsTutorial as the name of our image... this is what we'll refer to the image in the code, just make sure it isn't the same as any of the other names. The Frams setting defines how many frames are in the image, for example ships are typcially defined in a single file with 40 images aranged 10 wide and 4 tall, so we'd use (10,4) for the frames if we had such an image. For our image though, we only use a single frame so (1, 1) is correct.

[[Image:cg_3.PNG]]

Now we have to get the UniqueImage interface and use it. Interfaces are generally loaded during LOADMODE_LoadInterfaces in getClassInstance. They are gotten using the interface identifier and the module manager. The interface identifier is defined in UniqueImage.h

<pre>
#define I_UNIQUEIMAGE "UniqueImage-1"
</pre>

To use this constant we need to #include "UniqueImage/UniqueImage.h". In getClassInstance, if lm is LOADMODE_LoadInterfaces, we use the module manager to load the interface using the getInterface function.

<pre>
/**
* - tells the module manager that you want an interface. If the interface is not loaded by the
module manager, an error will result which the module manager takes care of
* - this should be called when getInstance(MODE_LoadInterfaces) is called
* @param myVersion the version of the module calling this function
* @param getVersion the version of the module we want to load
* @return a void* pointing to the class interface of the loaded module
*/
void* (*getInterface)(const char* myVersion, const char *getVersion);
</pre>

Here getVersion is I_UNIQUEIMAGE, myVersion, as in callbacks, is only used in case of errors. We can use __FILE__ or an identfying string like "commands-graphics tutorial". We save the pointer returned by getInterface. The question now is when should we call UniqueImage's getImageHandle function. We want to make sure that we do not call it too early, because the image loading system may not be initialized. This problem is solved through callbacks. For loading images, there is a callback that says "the image loading system is initialized, load your images now". This callback is in Graphics.h, CB_LoadImages.

<pre>
/*
This LoadImage callback will be called when the images are to be loaded, there is no parameter
This is guarenteed to be in POSTLOAD_Interfaces
*/

#define CB_LOADIMAGES "LoadImages"
#define CB_LOADIMAGES_VERSION "1"
</pre>

So we register a callback for this function (and #include "Graphics/Graphics.h"), and load our image and save the image handle UniqueImage gives us.

<pre>
// Commands - Graphics Tutorial Discretion Module
#include "Module.h"
#include "Chat/Chat.h"
#include "UniqueImage/UniqueImage.h"
#include "Graphics/Graphics.h"

ModuleManager* mm = 0;
UniqueImage* ui = 0;

int imageHandle = 0;

void gotInternalCommand(void* param)
{
InternalCommandParam* icp = (InternalCommandParam*)param;

if (icp->isCommand("show",0))
{
printf("Received Command: show\n");
}
else if (icp->isCommand("hide",0))
{
printf("Received Command: hide\n");
}
}

void loadImages(void* param)
{
imageHandle = ui->getImageHandle("CommandsGraphicsTutorial");
}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_Init)
{
mm->regCallback(__FILE__, CB_INTERNALCOMMAND, CB_INTERNALCOMMAND_VERSION, gotInternalCommand);
mm->regCallback(__FILE__, CB_LOADIMAGES, CB_LOADIMAGES_VERSION, loadImages);
}
else if (lm == LOADMODE_LoadInterfaces)
{
ui = (UniqueImage*)mm->getInterface(__FILE__,I_UNIQUEIMAGE);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

Now that we have the image, we need to draw it on the screen. This is done using the Graphics interface. We get this interface similar to how we got the UniqueImage interface (in getClassInstance where lm == LOADMODE_LoadInterfaces). The function we're interested is one that draws images on the screen:

<pre>
/** Draw an image in the next frame, this is to be done in the prerender callback
* This one draws relative to screen coordinates, rather than absolute coordinates, no bounds checking is done
* @param imageHandle an image handle from the loadImage function
* @param frame the frame of the image to draw on, for example the rotated ship graphic is 0-39
* @param xPixel the xPixel to draw with, this in screen coordinates
* @param yPixel the yPixel to draw with, this in screen coordinates
* @param Layer the layer to draw on, probably from the enum Layer
* @blend a number between 0 and 100 to determine how much blending is to be done for this image,
* so 0 is completely transparent and 100 is opaque
*/
void (*drawScreenImage)(int imageHandle, int xPixel, int yPixel, int frame, int layer, int blend);
void (*drawScreenImage2)(int imageHandle, int xPixel, int yPixel, int layer);
</pre>

imageHandle is the handle we got from UniqueImage, xPixel is the x pixel to use for the left part of the image, yPixel is the y pixel for the top of the image. (0, 0) is the upper left corner of the screen, with y increasing downward and x increasing rightward. Frame is the frame of the image to draw, for us this is 0 since we have only a single frame defined in our image. Layer is layer to draw on, some common ones are given in the enum Layer. Blend is the amount to blend the image, 100 for opaque images and fading to completely transparent when blend is 0. Here is the layer enum:

<pre>
// The layer enum, note you can define your own layers between these ones if you want
enum Layer
{
L_BelowAll = 50,
L_Background = 100,
L_AfterBackground = 150,
L_Tiles = 200,
L_AfterTiles = 250,
L_Weapons = 300,
L_AfterWeapons = 350,
L_Ships = 400,
L_AfterShips = 450,
L_Gauges = 500,
L_AfterGauges = 550,
L_Chat = 600,
L_AfterChat = 650,
L_TopMost = 700
};
</pre>

The question now is when we should call drawScreenImage. The answer is, once again, in a callback. The callback in this case is in Graphics.h, PreRender:

<pre>
// The parameter to the prerender callback
struct PrerenderParam
{
PrerenderParam(int m, Rect* s) : milDif(m) , screen(s) {}

int milDif; // milliseconds since last prerender callback, or 0 on the first one
Rect* screen; // the screen bounds, in pixels
};

// The prerender callback
#define CB_PRERENDER "Pre-render"
#define CB_PRERENDER_VERSION "2"
</pre>

This callback occurs every frame, when we call drawScreenImage, it will get drawn for a single frame. We register the callback like we did for LoadImages and InternalCommand. We then call drawScreenImage based on whether the user has used ?show or not. The final version the code is below:

<pre>
// Commands - Graphics Tutorial Discretion Module
#include "Module.h"
#include "Chat/Chat.h"
#include "UniqueImage/UniqueImage.h"
#include "Graphics/Graphics.h"

ModuleManager* mm = 0;
UniqueImage* ui = 0;
Graphics* g = 0;

int imageHandle = 0;
bool showImage = false;

void gotInternalCommand(void* param)
{
InternalCommandParam* icp = (InternalCommandParam*)param;

if (icp->isCommand("show",0))
{
showImage = true;
}
else if (icp->isCommand("hide",0))
{
showImage = false;
}
}

void loadImages(void* param)
{
imageHandle = ui->getImageHandle("CommandsGraphicsTutorial");
}

void preRender(void* param)
{
if (showImage)
{
g->drawScreenImage2(imageHandle, 200, 200, L_TopMost);
}
}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_Init)
{
mm->regCallback(__FILE__, CB_INTERNALCOMMAND, CB_INTERNALCOMMAND_VERSION, gotInternalCommand);
mm->regCallback(__FILE__, CB_LOADIMAGES, CB_LOADIMAGES_VERSION, loadImages);
mm->regCallback(__FILE__, CB_PRERENDER, CB_PRERENDER_VERSION, preRender);
}
else if (lm == LOADMODE_LoadInterfaces)
{
ui = (UniqueImage*)mm->getInterface(__FILE__,I_UNIQUEIMAGE);
g = (Graphics*)mm->getInterface(__FILE__,I_GRAPHICS);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

And when we run this module in Discretion we get the desired result:

[[Image:cg_4.PNG]]

Hopefully, by now you are comfortable with listening to callbacks and using interfaces as well as more familiar with the UniqueImage and Graphic modules. Here's a few things you can try to do:

- Instead of drawing the image on the screen, draw it on the map at pixel 8200,8200, and make it so that you can fly over it with your ship.

- Make your image have two frames instead of just a single one, and use a command "?switch" to change the frame of the image being displayed.

- Add a command "?blend <int>" where <int> is an integer specifying the blend amount to use. Observe the effects of different blend values.

[[Category:Discretion]]
[[Category:Guides]]

Creating and Testing a Simple Discretion Module in MS Visual Studio

2008-03-17T05:09:59Z

BaK: updates

This is a tutorial for module creation in [[Discretion]]. For other tutorials, see the [[Discretion Module Tutorial]].

Making a module is easy pie once you know what to do, so let's get to it.

==Windows with MSVC==

First step: make a new VS.net C++ Project.

1. File -> New Project

2. Win32 Console Project

3. Give your project a name ("TestModule" in the picture)

4. Press Ok

[[Image:disc_module1.PNG]]

5. Click on application settings on the left

6. Click DLL from the list of radio buttons

7. Press the Empty Project checkbox

8. Press Finish

[[Image:disc_module2.PNG]]

9. File -> Add New Item

10. Select C++ Source File (.cpp)

11. Name your source file ("testmodule.cpp" in the picture)

12. Press Open

[[Image:disc_module3.PNG]]

13. Paste the following code into your source file
<pre>// Sample Discretion Module Source File
#include "Module.h"

void* getClassInstance(void* _mm, LoadMode lm)
{
if (lm == LOADMODE_Init)
printf("Test Module Initialized\n");

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}</pre>

14. Right Click your project in the Solution Explorer and go to Properties (You can also access this through the Project Menu, Project -> Properties)

[[Image:disc_module4.PNG]]

15. In the properties window, from the drop down menu select "All Configurations"

16. Select C++, General from the tree view on the left

17. Type the directory to the Modules directory (the one with Module.h in it, not the one with only .dlls!) that comes with the full version of Discretion in the Additional Include Directory property ("E:/client/modules" in the picture)

18. Press Ok

[[Image:disc_module5.PNG]]

19. Go to Buld -> Build <project name> ("TestModule" in the pictue)

[[Image:disc_module6.PNG]]

If all goes well, you code should compile and a .dll should be produced that is a Discretion module! Now let's put the module into Discretion to see it at work.

20. Copy the produced .dll into your Discretion executable's Module folder (the one with the .dlls in it, not the one with Module.h in it).

[[Image:disc_module7.PNG]]

21. Edit conf/MAIN.CONF with a program such as Notepad

22. Add the name of your dll to the Modules::Names setting (it's a comma seperated list of module names, order doesn't matter)

23. Save the file

[[Image:disc_module8.PNG]]

24. Run Discretion through the terminal (start -> run -> cmd), Select "Single Player" (if you don't run it through the terminal you're likely to not see any console output, even though the module will be loaded).

25. Observe your modules initialization in the console window

[[Image:disc_module9.PNG]]

Now you might say, rightfully so, that this module doesn't do anything. The way to do real things in Discretion is by using other modules. Want to react to user key presses? Use the KeyControls module. Want to display some images? Use the Graphics module. I'll gladly write additional tutorials for how to use each of these as needed. Tell me what you want to do and I'll write a tutorial with how to use the existing modules to accomplish what you want to do.

[[Category:Discretion]]
[[Category:Guides]]

Creating and Testing a Simple Discretion Module

2008-03-17T05:07:41Z

BaK: /* Microsoft Visual Studio */ wording

Once you obtain the [[Discretion]] source, you are ready to make a module for Discretion. If you haven't gotten the source yet, follow the instructions in [[Obtaining the Discretion Source using Subversion]]. This tutorial is part of the [[Discretion Module Tutorial]].

There are three ways to make a module: 1. Eclipse with minGW, 2. MS Visual Studio, and 3. make. If you're new, the recommended way is to use minGW and Eclipse.

== minGW and Eclipse ==
The way [[User:BaK|BaK]] works on Discretion is using minGW and Eclipse. Both pieces of software are free, and minGW is a lot like gcc so this might even work for Linux development. Eclipse is also BaK's favorite Integrated Development Environment (IDE). Currently the tutorial is oriented towards Windows users. If you want to try this method see the [[Creating and Testing a Simple Discretion Module in Eclipse]] tutorial.

== Microsoft Visual Studio ==
Microsoft Visual Studio is an IDE produced by Microsoft that supports C++ development. I've used it for a few years and it's pretty good at what it does. Students also often get free licenses for Visual Studio from their school. Currently for Discretion, development is done in Eclipse so there aren't any visual studio projects for you to use. Nonetheless, setting one up is a snap and is covered in the [[Creating and Testing a Simple Discretion Module in MS Visual Studio]] tutorial.

== Make ==
Make is a tool that can build large projects. It relies on a compiler such as gcc. This one is typically used by the hardcore linux users, but it's also a very portable tool so it works great with multi-platform development. [[Goldeye]] is currently in charge of development using make (particularly interested in Mac OS X support), and may one day make (pun!) a [[Creating and Testing a Simple Discretion Module using Make]] tutorial. Send him a ?message in-game so he knows you appreciate him working on this and encourage him to write a tutorial for us!

== Others ==
Outside of these three standard ways there are countless compilers and IDEs you can use to make any C++ project, including Discretion. However, officially we won't help you with these. Unofficially we probably will if you bug us enough ;).

[[Category:Discretion]]
[[Category:Guides]]

Obtaining the Discretion Source using Subversion

2008-03-17T05:06:08Z

BaK: grammar

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically it is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

==Video==
The tutorial video can be obtained [http://ews.uiuc.edu/~sbak2/disc/disc_svn.wmv here].

==Links==
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Creating and Testing a Simple Discretion Module in Eclipse

2008-03-17T05:00:52Z

BaK: /* Videos */ video links added

This tutorial is a '''video''' tutorial describing how anyone can using minGW (and probably g++) and Eclipse to compile a simple module and put get it to run on [[Discretion]]. It assumes you're using Windows (although g++ may work) and you don't have any tools installed. However, you should have already gotten the source code (if not see the [[Obtaining the Discretion Source using Subversion]] tutorial). This tutorial is part of a series of tutorials consisting of the [[Discretion Module Tutorial]].

minGW stands for minimalistic Gnu for Windows. It is an open source complier almost identical to gcc and g++, which are the compilers used for linux, among other things. The compiler produces native Windows exectuables, and best of all it's free! However, its interface isn't the best for the novice user. Thus, we use eclipse to help manage the minGW compiler for us.

Eclipse, is an integrated development environment (IDE) which is also open-source and free. It is basically a program that makes it easier to make other programs. It was originally designed for Java development, but people made plugins to allow C++ development. These extensions are called the CDT (C/C++ Development Tooling). The CDT integrates nicely with minGW so these two make a good match. Discretion's modules come with Eclipse Projects when you get the source so modifications are easy to make. Eclipse is implemented in Java, so in order to use it you need the Java Runtime Environment. The good news is you probably already have this installed. Nonetheless, the tutorial covers downloading it if you don't already have it installed.

==Videos==

This tutorial is divided a few parts:
* [http://ews.uiuc.edu/~sbak2/disc/disc_mingw.wmv Obtaining and Testing minGW]
* [http://ews.uiuc.edu/~sbak2/disc/disc_jre.wmv Getting the Java Runtime Environment] (90% of people can skip this step)
* [http://ews.uiuc.edu/~sbak2/disc/disc_eclipse.wmv Downloading Eclipse with CDT]
* [http://ews.uiuc.edu/~sbak2/disc/disc_simplemod.wmv Creating and Testing a Simple Module within Discretion]
* [http://ews.uiuc.edu/~sbak2/disc/disc_tricks.wmv Discretion with Eclipse Tricks and Tips]

==Links==

minGW: [http://sourceforge.net/project/showfiles.php?group_id=2435 Sourceforge File List]

java runtime environment: [http://java.sun.com/javase/downloads/?intcmp=1281 Downloads]

eclipse: [http://www.eclipse.org/downloads/ Eclipse Downloads]

Obtaining the Discretion Source using Subversion

2008-03-17T04:58:51Z

BaK: wiki format

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

==Video==
The tutorial video can be obtained [http://ews.uiuc.edu/~sbak2/disc/disc_svn.wmv here].

==Links==
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-17T04:58:28Z

BaK: way to not allow .wmv uploads :( [changed to external link]

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

==Video==
The tutorial video can be obtained [http://ews.uiuc.edu/~sbak2/disc/disc_svn.wmv|here].

==Links==
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-17T04:40:15Z

BaK: /* Video */ added vid link

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

==Video==
The tutorial video can be obtained [[Media:Disc_svn.wmv|here]].

==Links==
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Creating and Testing a Simple Discretion Module in Eclipse

2008-03-16T19:11:13Z

BaK: /* Links */ fixed

This tutorial is a '''video''' tutorial describing how anyone can using minGW (and probably g++) and Eclipse to compile a simple module and put get it to run on [[Discretion]]. It assumes you're using Windows (although g++ may work) and you don't have any tools installed. However, you should have already gotten the source code (if not see the [[Obtaining the Discretion Source using Subversion]] tutorial). This tutorial is part of a series of tutorials consisting of the [[Discretion Module Tutorial]].

minGW stands for minimalistic Gnu for Windows. It is an open source complier almost identical to gcc and g++, which are the compilers used for linux, among other things. The compiler produces native Windows exectuables, and best of all it's free! However, its interface isn't the best for the novice user. Thus, we use eclipse to help manage the minGW compiler for us.

Eclipse, is an integrated development environment (IDE) which is also open-source and free. It is basically a program that makes it easier to make other programs. It was originally designed for Java development, but people made plugins to allow C++ development. These extensions are called the CDT (C/C++ Development Tooling). The CDT integrates nicely with minGW so these two make a good match. Discretion's modules come with Eclipse Projects when you get the source so modifications are easy to make. Eclipse is implemented in Java, so in order to use it you need the Java Runtime Environment. The good news is you probably already have this installed. Nonetheless, the tutorial covers downloading it if you don't already have it installed.

==Videos==

This tutorial is divided a few parts:
* Obtaining and Testing minGW
* Getting the Java Runtime Environment (90% of people can skip this step)
* Downloading Eclipse with CDT
* Creating and Testing a Simple Module within Discretion
* Discretion with Eclipse Tricks and Tips

==Links==

minGW: [http://sourceforge.net/project/showfiles.php?group_id=2435 Sourceforge File List]

java runtime environment: [http://java.sun.com/javase/downloads/?intcmp=1281 Downloads]

eclipse: [http://www.eclipse.org/downloads/ Eclipse Downloads]

Creating and Testing a Simple Discretion Module in Eclipse

2008-03-16T18:14:23Z

BaK: removed code

This tutorial is a '''video''' tutorial describing how anyone can using minGW (and probably g++) and Eclipse to compile a simple module and put get it to run on [[Discretion]]. It assumes you're using Windows (although g++ may work) and you don't have any tools installed. However, you should have already gotten the source code (if not see the [[Obtaining the Discretion Source using Subversion]] tutorial). This tutorial is part of a series of tutorials consisting of the [[Discretion Module Tutorial]].

minGW stands for minimalistic Gnu for Windows. It is an open source complier almost identical to gcc and g++, which are the compilers used for linux, among other things. The compiler produces native Windows exectuables, and best of all it's free! However, its interface isn't the best for the novice user. Thus, we use eclipse to help manage the minGW compiler for us.

Eclipse, is an integrated development environment (IDE) which is also open-source and free. It is basically a program that makes it easier to make other programs. It was originally designed for Java development, but people made plugins to allow C++ development. These extensions are called the CDT (C/C++ Development Tooling). The CDT integrates nicely with minGW so these two make a good match. Discretion's modules come with Eclipse Projects when you get the source so modifications are easy to make. Eclipse is implemented in Java, so in order to use it you need the Java Runtime Environment. The good news is you probably already have this installed. Nonetheless, the tutorial covers downloading it if you don't already have it installed.

==Videos==

This tutorial is divided a few parts:
* Obtaining and Testing minGW
* Getting the Java Runtime Environment (90% of people can skip this step)
* Downloading Eclipse with CDT
* Creating and Testing a Simple Module within Discretion
* Discretion with Eclipse Tricks and Tips

==Links==

minGW: [http://sourceforge.net/project/showfiles.php?group_id=2435|Sourceforge File List]

java runtime environment: [http://java.sun.com/javase/downloads/?intcmp=1281|Java Downloads]

eclipse: [http://www.eclipse.org/downloads/|Eclipse Downloads]

Creating and Testing a Simple Discretion Module in Eclipse

2008-03-16T18:13:59Z

BaK: added a step

This tutorial is a '''video''' tutorial describing how anyone can using minGW (and probably g++) and Eclipse to compile a simple module and put get it to run on [[Discretion]]. It assumes you're using Windows (although g++ may work) and you don't have any tools installed. However, you should have already gotten the source code (if not see the [[Obtaining the Discretion Source using Subversion]] tutorial). This tutorial is part of a series of tutorials consisting of the [[Discretion Module Tutorial]].

minGW stands for minimalistic Gnu for Windows. It is an open source complier almost identical to gcc and g++, which are the compilers used for linux, among other things. The compiler produces native Windows exectuables, and best of all it's free! However, its interface isn't the best for the novice user. Thus, we use eclipse to help manage the minGW compiler for us.

Eclipse, is an integrated development environment (IDE) which is also open-source and free. It is basically a program that makes it easier to make other programs. It was originally designed for Java development, but people made plugins to allow C++ development. These extensions are called the CDT (C/C++ Development Tooling). The CDT integrates nicely with minGW so these two make a good match. Discretion's modules come with Eclipse Projects when you get the source so modifications are easy to make. Eclipse is implemented in Java, so in order to use it you need the Java Runtime Environment. The good news is you probably already have this installed. Nonetheless, the tutorial covers downloading it if you don't already have it installed.

==Videos==

This tutorial is divided a few parts:
* Obtaining and Testing minGW
* Getting the Java Runtime Environment (90% of people can skip this step)
* Downloading Eclipse with CDT
* Creating and Testing a Simple Module within Discretion
* Discretion with Eclipse Tricks and Tips

==Links==

minGW: [http://sourceforge.net/project/showfiles.php?group_id=2435|Sourceforge File List]

java runtime environment: [http://java.sun.com/javase/downloads/?intcmp=1281|Java Downloads]

eclipse: [http://www.eclipse.org/downloads/|Eclipse Downloads]

==Code==
<pre>// Sample Discretion Module Source File
#include "Module.h"

void* getClassInstance(void* _mm, LoadMode lm)
{
if (lm == LOADMODE_Init)
printf("Test Module Initialized\n");

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}</pre>

Listening for Key Presses, Displaying Text, and Per Player Data

2008-03-16T07:10:56Z

BaK: added eclipse solution to linking problem

This is a tutorial for module creation in [[Discretion]]. For other tutorials, see the [[Discretion Module Tutorial]].

The purpose of this tutorial is to explain how to 1) display text on the screen with the Text module, 2) show how to access shared per player data, 3) listen and act upon key presses in Discretion, and 4) show how to register and use local per player data. You are assumed to know how to create and load a basic module, as well as how to use interfaces and callbacks. If you don't know how to do this, do the corresponding [[Discretion Module Tutorial]].

We shall construct a module that displays the currently ticked (in the playerlist) player's name, squad, or frequency. The user will be able to press the ALT key to cycle between these attributes. The module will also keep track of how many times the user has pressed alt for each player.

So for example, consider a case where there's two players in the arena, tux(the user) on freq 0 and squad "Killers", and BaK on freq 1 on squad "BakAttak". Initially the player himself is ticked. The screen will say "Name: tux (Switched 0 times)". The player can then select the next player on the playerlist using page down. After the user presses page down, the screen says "Name: BaK (Switched 0 times)". The user can then press the alt key and the screen switches to "Squad: BakAttak (Switched 1 time)". If the user than presses alt again it switched the text to "Freq: 1 (Switched 2 times)". If the user presses page up it goes back to "Name: tux (Switched 0 times)". Alt will then yield the text "Squad: Killers (Switched 1 time)". Page down will go back to "Freq: 1 (Switched 2 times)". Alt again will give us "Name: Bak (Switched 3 times)".

So let's work off a basic module template:

<pre>
// Discretion Tutorial, goals:
// 1) display text on the screen with the Text module
// 2) show how to access shared per player data
// 3) listen and act upon key presses in Discretion
// 4) show how to register and use local per player data.
// April 2007

#include "Module.h"

ModuleManager* mm = 0;

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_Init)
{

}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

Let's display some text on the screen using the Text module. The text module can display text on the screen or on the map, on any layer. These layers are the same layers that are used to display images. The function we are interested in is displayTextScreen:

<pre>
/**
* Display this text for one frame, call during prerender, this in is screen coordinates
* @param line the line of text to display
* @param color the color string to display
* @param layer the layer to display it on
* @param topLeft the top left corner of where we should start drawing
* @param blend how much to blend the text, 0 = transparent, 100 = opaque
*/
void (*displayTextScreen)(const char* line, const char* color, int layer, const Point* topLeft, int blend);
void (*displayTextScreen2)(const char* line, const char* color, int layer, const Point* topLeft);
</pre>

So as in the images tutorial, we register a callback to CB_PRERENDER, which is when we call displayTextScreen2 to display the actual text. We also get the Text interface. Then, during the prerender callback, we call displayTextScreen2, which will display the text we want on the screen.

<pre>
// Discretion Tutorial, goals:
// 1) display text on the screen with the Text module
// 2) show how to access shared per player data
// 3) listen and act upon key presses in Discretion
// 4) show how to register and use local per player data.
// April 2007

#include "Module.h"
#include "Text/Text.h"
#include "Graphics/Graphics.h"

ModuleManager* mm = 0;
Text* t = 0;

void preRender(void* param)
{
Point topLeft(400,200);

t->displayTextScreen2("test string", "yellow", L_Chat, &topLeft);
}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_LoadInterfaces)
{
t = (Text*)mm->getInterface(__FILE__, I_TEXT);

mm->regCallback(__FILE__,CB_PRERENDER, CB_PRERENDER_VERSION, &preRender);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

You can see how we could use the text module to display various strings at various layers. Running this code makes the module display the string "test string" at position 400, 200:

[[Image:Ss1.PNG]]

Next, we want to be able to get data about the players. This data is stored as shared Per Player Data. This is gotten using the PerPlayerData interface's getSharedData function:

<pre>
/**
* Get data that was shared by other modules with registerSharedData
* @param pid the player's id we're concerned with
* @param dataName the unique name of the data we want
* @return a void* to the data we want. See the module documentation for the correct name and type
*/
void* (*getSharedData)(int pid, const char* dataName);
</pre>

The parameter dataName refers to the name of the data, in this case "name", "squad", and "freq". There currently isn't a global list of common shared data anywhere, but such a list probably will be made at some point.

We can get the ticked player's id number using the PlayerList interface.

<pre>
/**
* Get the Pid of the currently targeted player
* @return the pid of the player currently "ticked" in the player list box
*/
int (*getTargetPID)();
</pre>

Now once we get the shared data, we receive a void*, which is a pointer that can point to any type of data. Again, a global list of common shared data types isn't yet available, so trust me that getting "name" will give you data of type char*, "squad" will get you data of type char*, and "freq" gets you data of type int*. With a pointer to the data you can modify the data, and this is the mechanism for doing that. You should cast the void* to the proper type of pointer, then use that pointer to get/set the data as one would with a normal pointer.

So in our tutorial, in our prerender callback, we get the ticked player's id from the playerlist, use that with PerPlayerData to get the name of the ticked player, and display that on the screen using the Text Module.

<pre>
// Discretion Tutorial, goals:
// 1) display text on the screen with the Text module
// 2) show how to access shared per player data
// 3) listen and act upon key presses in Discretion
// 4) show how to register and use local per player data.
// April 2007

#include "Module.h"
#include "Text/Text.h"
#include "Graphics/Graphics.h"
#include "PerPlayerData/PerPlayerData.h"
#include "PlayerList/PlayerList.h"

ModuleManager* mm = 0;
PerPlayerData* ppd = 0;
PlayerList* pl = 0;
Text* t = 0;

void preRender(void* param)
{
Point topLeft(400,200);
int ticked_pid = pl->getTargetPID();
char* playerName = (char*)ppd->getSharedData(ticked_pid, "name");

t->displayTextScreen2(playerName, "yellow", L_Chat, &topLeft);
}

void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_LoadInterfaces)
{
t = (Text*)mm->getInterface(__FILE__, I_TEXT);
pl = (PlayerList*)mm->getInterface(__FILE__, I_PLAYERLIST);
ppd = (PerPlayerData*)mm->getInterface(__FILE__, I_PERPLAYERDATA);

mm->regCallback(__FILE__,CB_PRERENDER, CB_PRERENDER_VERSION, &preRender);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

When we run this code (you'll need to run a Discretion-compatible ASSS server to get a name), we get the expected result:

[[Image:Ss2.PNG]]

Now, in the tutorial, we will react to when the user presses alt to cycle through the name, squad, and freq. First, we modify our conf file to specify what keys correspond to our action. Throughout the code (and conf files) we refer to our action with a string. Let's use "cycle_data" as the name for our action. Then, we use the Controls module to specify a function to call when the key(s) for "cycle_data" are pressed. In this function, we will change the type of data we're displaying about the player in prerender.

So first let's edit conf/modules/Controls.conf. Open this file (in notepad, for example), and add "cycle_data" to the list of controls in Controls::Name. Also, we set Controls::cycle_data to RALT. In general, the names of the controls (like "RALT" for us) are equal to the SDLK_ constants for the keys, which you can google for. Alternately, if you're curious, examine initKeys() at the bottom of Modules/KeyControls/SDL Key Controls/SDL_KeyControls.cpp. Usually they're pretty obvious, as was the case with "RALT". If you wanted to allow either alt key to be pressed you could use "RALT, LALT", or if you wanted both, "RALT + LALT". There will eventually be a nice visual interface where the user can rebind all these keys to whatever values they want to use. Proceed to add the mentioned settings to the conf/modules/Controls.conf.

[[Image:Ss3.PNG]]

Now to figure out when the key is pressed, we need to tell the Controls module we're interested in a particular action (cycle_data). We first need to get the controls interface, and then register the callback CB_CONTROLSLOADED, which is when we should register key events.

<pre>
// The controls loaded callback, parameter is null
// this callback occurs when we have loaded the controls bindings, at this point you can call regControlEvent
#define CB_CONTROLSLOADED "CB_CONTROLSLOADED"
#define CB_CONTROLSLOADED_VERSION "1"
</pre>

In that callback, we use regControlEvent from the Controls module to tell the Controls module what function to call when your action occurs (the user presses alt).

<pre>
/**
* tell the Controls modules you want a function to be called when a certain control is pressed,
* down is true iff we want the function to be called when the key is pressed down, if itâ€™s false it will be
* called iff the key combo is lifted up.
*
* call this function in your handler for the CB_CONTROLSLOADED callback
*
* @param keyString the keyString corresponding to the event, as defined in the settings (like "repel")
* @param funcToCall the function to call when the event occurs, down = true iff we're pressing the key combination
*/
void (*regControlEvent)(const char* controlString, void (*funcToCall)(bool down, const char* controlString));
</pre>

To do this, we need a function to call when the control is pressed down or released. The type of the function is void function taking parameters (bool down, const char* controlString), so we add such a function to our module (we named it cycleDataPressed). When this function is called, we change a global variable in our module which changes what we display.

Note that once we #include "Controls/Controls.h", we need to add Modules/Shared/StringManip.cpp to our project to avoid unresolved external symbol linker errors. This is done by going to File -> Add Existing Item, then selecting Modules/Shared/StringManip.cpp.

[[Image:Ss4.PNG]]

If you don't want to do that, or you're using Eclipse, you can include the following code at the top of our file:
<pre>
#ifdef HACK_EXTERNALS
#include "Shared/StringManip.cpp"
#endif HACK_EXTERNALS
</pre>
Notice that this relies on the preprocessor macro HACK_EXTERNALS to be defined (by discretion convention). This is automatically defined for the template module in eclipse, however you can do it manually (in Eclipse), by going to project -> properties -> C/C++ Build -> Settings -> GCC C++ Compiler -> Preprocessor and working with the Defined Symbols listbox.

The resultant code should now be:

<pre>

// Discretion Tutorial, goals:
// 1) display text on the screen with the Text module
// 2) show how to access shared per player data
// 3) listen and act upon key presses in Discretion
// 4) show how to register and use local per player data.
// April 2007

#include "Module.h"
#include "Text/Text.h"
#include "Graphics/Graphics.h"
#include "PerPlayerData/PerPlayerData.h"
#include "PlayerList/PlayerList.h"
#include "Controls/Controls.h"

ModuleManager* mm = 0;
PerPlayerData* ppd = 0;
PlayerList* pl = 0;
Text* t = 0;
Controls* c = 0;

// 0 = name, 1 = squad, 2 = freq
int dataState = 0;

void cycleDataPressed(bool down, const char* controlString)
{
// if the key is pressed down (rather than released)
if (down)
dataState = (dataState + 1) % 3;
}

// callback below
void keyControlsLoaded(void* param)
{
c->regControlEvent("cycle_data",cycleDataPressed);
}

void preRender(void* param)
{
Point topLeft(400,200);
int ticked_pid = pl->getTargetPID();

char buf[128];

if (dataState == 0)
{
char* playerName = (char*)ppd->getSharedData(ticked_pid, "name");
snprintf(buf,sizeof(buf),"Name: %s",playerName);
}
else if (dataState == 1)
{
char* squadName = (char*)ppd->getSharedData(ticked_pid, "squad");
snprintf(buf,sizeof(buf),"Squad: %s",squadName);
}
else
{
int freq = *(int*)ppd->getSharedData(ticked_pid, "freq");
snprintf(buf,sizeof(buf),"Freq: %i",freq);
}

t->displayTextScreen2(buf, "yellow", L_Chat, &topLeft);
}

// interface functions below
void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_LoadInterfaces)
{
t = (Text*)mm->getInterface(__FILE__, I_TEXT);
pl = (PlayerList*)mm->getInterface(__FILE__, I_PLAYERLIST);
ppd = (PerPlayerData*)mm->getInterface(__FILE__, I_PERPLAYERDATA);
c = (Controls*)mm->getInterface(__FILE__, I_CONTROLS);

mm->regCallback(__FILE__,CB_PRERENDER, CB_PRERENDER_VERSION, &preRender);
mm->regCallback(__FILE__,CB_CONTROLSLOADED, CB_CONTROLSLOADED_VERSION, &keyControlsLoaded);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}

</pre>

With this module, when we press the right alt key (assuming you used RALT in the conf file), it should cycle through the ticked player's data:

[[Image:Ss5.PNG]]

Finally, let's use some local per player data to count how many times we've toggled the state for each player. Our data will keep track of the current information we're displaying for each player, as well as how many times alt was pressed for the player.

Each module is allowed to allocate one structure of per player data for local use. We are interested in the number of times the player presses alt, as well as the current data we're displaying. We also provide the PerPlayerData module with two functions, one to initialize the data, and one to deinitialize the data. You can skip either of these functions. In our case, we want to set the initial number of times the user pressed alt to 0, and set the initial display to 0 (which is the name). The function we make has to accept a void* which we cast to be a pointer to our structure. Here is our structure and initialization function:

<pre>

struct MyPlayerData
{
int dataState;
int count;
};

void initMyPlayerData(void* param)
{
MyPlayerData* mpd = (MyPlayerData*)param;

mpd->count = 0;
mpd->dataState = 0;
}

</pre>

We now have to tell the PerPlayerData module we want it to keep track of data for us. This is done during CB_LOADPERPLAYERDATA, which we listen for.

<pre>
/*
When this callback occurs, you should register the per player data for your module
*/
#define CB_LOADPERPLAYERDATA "Load Per Player Data"
#define CB_LOADPERPLAYERDATA_VERSION "1"
</pre>

During this callback we want to call the interface function in PerPlayerData, reserveData. This allocates some space for every player.

<pre>
/**
* Call this during CB_LOADPERPLAYERDATA to reserve some per player data for your module.
* @param interfaceName the I_ interface name that you're using
* @param size the number of bytes to allocate, use sizeof(YourDataStruct)
* @param initer the function to call with the data as the argument after we allocate (can be null)
* @param deiniter the function to call with the data as the argument before we free (can be null)
* @return key the key to use in GetData when we want to change / use the data
*/
int (*reserveData)(const char* interfaceName, unsigned int size,
void (*initer)(void* data), void (*deiniter)(void* data));
</pre>

In this function, the interface name is the name of the interface, as when we're registering callbacks. Using __FILE__ like we have been will work. The size parameter should be set to the size of our data structure, we'll use sizeof(MyPlayerData) here. This function returns a key which we keep track of in order to get the data later on. To get the data, we use the GetData interface function from PerPlayerData:

<pre>
/**
* Get the Data which we've previously reserved with ReserveData for a particular player
* @param pid the player id of the player whose data we want (often sent in packets)
* @param key the key returned by ReserveData which we use to tell your data apart from a different module's
*/
void* (*getData)(int pid, int key);
</pre>

This returns a void* which we can cast to be a pointer to our structure. We put getData into our CB_PRERENDER to get the state and number of times alt was pressed for the targeted player, and display that. We also increment the number of times alt was pressed every time cycleDataPressed is called when a key is pressed down.

The final code is:

<pre>
// Discretion Tutorial, goals:
// 1) display text on the screen with the Text module
// 2) show how to access shared per player data
// 3) listen and act upon key presses in Discretion
// 4) show how to register and use local per player data.
// April 2007

#include "Module.h"
#include "Text/Text.h"
#include "Graphics/Graphics.h"
#include "PerPlayerData/PerPlayerData.h"
#include "PlayerList/PlayerList.h"
#include "Controls/Controls.h"

ModuleManager* mm = 0;
PerPlayerData* ppd = 0;
PlayerList* pl = 0;
Text* t = 0;
Controls* c = 0;

int myPlayerDataKey = 0;

struct MyPlayerData
{
// 0 = name, 1 = squad, 2 = freq
int dataState;
int count;
};

void initMyPlayerData(void* param)
{
MyPlayerData* mpd = (MyPlayerData*)param;

mpd->count = 0;
mpd->dataState = 0;
}

void cycleDataPressed(bool down, const char* controlString)
{
// if the key is pressed down (rather than released)
if (down)
{
int ticked_pid = pl->getTargetPID();

MyPlayerData* data = (MyPlayerData*)ppd->getData(ticked_pid, myPlayerDataKey);

data->dataState = (data->dataState + 1) % 3;
++(data->count);
}
}

// callbacks below
void keyControlsLoaded(void* param)
{
c->regControlEvent("cycle_data",cycleDataPressed);
}

void loadPerPlayerData(void* param)
{
myPlayerDataKey = ppd->reserveData(__FILE__, sizeof(MyPlayerData), initMyPlayerData, 0);
}

void preRender(void* param)
{
Point topLeft(400,200);
int ticked_pid = pl->getTargetPID();
MyPlayerData* data = (MyPlayerData*)ppd->getData(ticked_pid, myPlayerDataKey);

char buf[128];

if (data->dataState == 0)
{
char* playerName = (char*)ppd->getSharedData(ticked_pid, "name");
snprintf(buf,sizeof(buf),"Name: %s (Switched %i times)", playerName, data->count);
}
else if (data->dataState == 1)
{
char* squadName = (char*)ppd->getSharedData(ticked_pid, "squad");
snprintf(buf,sizeof(buf),"Squad: %s (Switched %i times)", squadName, data->count);
}
else
{
int freq = *(int*)ppd->getSharedData(ticked_pid, "freq");
snprintf(buf,sizeof(buf),"Freq: %i (Switched %i times)", freq, data->count);
}

t->displayTextScreen2(buf, "yellow", L_Chat, &topLeft);
}

// interface functions below
void* getClassInstance(void* _mm, LoadMode lm)
{
mm = (ModuleManager*)_mm;

if (lm == LOADMODE_LoadInterfaces)
{
t = (Text*)mm->getInterface(__FILE__, I_TEXT);
pl = (PlayerList*)mm->getInterface(__FILE__, I_PLAYERLIST);
ppd = (PerPlayerData*)mm->getInterface(__FILE__, I_PERPLAYERDATA);
c = (Controls*)mm->getInterface(__FILE__, I_CONTROLS);

mm->regCallback(__FILE__,CB_PRERENDER, CB_PRERENDER_VERSION, &preRender);
mm->regCallback(__FILE__,CB_CONTROLSLOADED, CB_CONTROLSLOADED_VERSION, &keyControlsLoaded);
mm->regCallback(__FILE__,CB_LOADPERPLAYERDATA, CB_LOADPERPLAYERDATA_VERSION, &loadPerPlayerData);
}

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}
</pre>

And we're done!

[[Image:Ss6.PNG]]

[[Category:Discretion]]
[[Category:Guides]]

Obtaining the Discretion Source using Subversion

2008-03-16T07:02:27Z

BaK: format

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

==Video==
The tutorial video can be obtained here.

==Links==
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Creating and Testing a Simple Discretion Module in Eclipse

2008-03-16T07:01:53Z

BaK: content

This tutorial is a '''video''' tutorial describing how anyone can using minGW (and probably g++) and Eclipse to compile a simple module and put get it to run on [[Discretion]]. It assumes you're using Windows (although g++ may work) and you don't have any tools installed. However, you should have already gotten the source code (if not see the [[Obtaining the Discretion Source using Subversion]] tutorial). This tutorial is part of a series of tutorials consisting of the [[Discretion Module Tutorial]].

minGW stands for minimalistic Gnu for Windows. It is an open source complier almost identical to gcc and g++, which are the compilers used for linux, among other things. The compiler produces native Windows exectuables, and best of all it's free! However, its interface isn't the best for the novice user. Thus, we use eclipse to help manage the minGW compiler for us.

Eclipse, is an integrated development environment (IDE) which is also open-source and free. It is basically a program that makes it easier to make other programs. It was originally designed for Java development, but people made plugins to allow C++ development. These extensions are called the CDT (C/C++ Development Tooling). The CDT integrates nicely with minGW so these two make a good match. Discretion's modules come with Eclipse Projects when you get the source so modifications are easy to make. Eclipse is implemented in Java, so in order to use it you need the Java Runtime Environment. The good news is you probably already have this installed. Nonetheless, the tutorial covers downloading it if you don't already have it installed.

==Videos==

This tutorial is divided into three parts:
* Obtaining and Testing minGW
* Getting the Java Runtime Environment (90% of people can skip this step)
* Downloading Eclipse with CDT
* Creating and Testing a Simple Module within Discretion

==Links==

minGW: [http://sourceforge.net/project/showfiles.php?group_id=2435|Sourceforge File List]

java runtime environment: [http://java.sun.com/javase/downloads/?intcmp=1281|Java Downloads]

eclipse: [http://www.eclipse.org/downloads/|Eclipse Downloads]

==Code==
<pre>// Sample Discretion Module Source File
#include "Module.h"

void* getClassInstance(void* _mm, LoadMode lm)
{
if (lm == LOADMODE_Init)
printf("Test Module Initialized\n");

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}</pre>

Creating and Testing a Simple Discretion Module

2008-03-16T06:22:53Z

BaK: wording

Once you obtain the [[Discretion]] source, you are ready to make a module for Discretion. If you haven't gotten the source yet, follow the instructions in [[Obtaining the Discretion Source using Subversion]]. This tutorial is part of the [[Discretion Module Tutorial]].

There are three ways to make a module: 1. Eclipse with minGW, 2. MS Visual Studio, and 3. make. If you're new, the recommended way is to use minGW and Eclipse.

== minGW and Eclipse ==
The way [[User:BaK|BaK]] works on Discretion is using minGW and Eclipse. Both pieces of software are free, and minGW is a lot like gcc so this might even work for Linux development. Eclipse is also BaK's favorite Integrated Development Environment (IDE). Currently the tutorial is oriented towards Windows users. If you want to try this method see the [[Creating and Testing a Simple Discretion Module in Eclipse]] tutorial.

== Microsoft Visual Studio ==
Microsoft Visual Studio is an IDE produced by Microsoft that supports C++ development. I've used it for a few years and it's pretty good at what it does. Students also often get free licenses for Visual Studio from their school. Currently for Discretion, development is done in Eclipse so there aren't any current visual studio projects for you to use. Nonetheless, setting one up is a snap and is covered in the [[Creating and Testing a Simple Discretion Module in MS Visual Studio]] tutorial.

== Make ==
Make is a tool that can build large projects. It relies on a compiler such as gcc. This one is typically used by the hardcore linux users, but it's also a very portable tool so it works great with multi-platform development. [[Goldeye]] is currently in charge of development using make (particularly interested in Mac OS X support), and may one day make (pun!) a [[Creating and Testing a Simple Discretion Module using Make]] tutorial. Send him a ?message in-game so he knows you appreciate him working on this and encourage him to write a tutorial for us!

== Others ==
Outside of these three standard ways there are countless compilers and IDEs you can use to make any C++ project, including Discretion. However, officially we won't help you with these. Unofficially we probably will if you bug us enough ;).

[[Category:Discretion]]
[[Category:Guides]]

Discretion Module Tutorial

2008-03-16T06:08:01Z

BaK: bullets!

This tutorial is divided into a few pieces. If you're completely new to [[Discretion]] development, you can view them in order, otherwise you can skip to the one you're interested in. If you go in order, they assume you have no knowledge and no tools installed.

* [[Obtaining the Discretion Source using Subversion]]
* [[Creating and Testing a Simple Discretion Module]]
* [[Discretion Commands and Displaying Images]] (Also covers listening for callbacks and using interfaces)
* [[Listening for Key Presses, Displaying Text, and Per Player Data]]

[[Category:Discretion]]
[[Category:Guides]]

Discretion Module Tutorial

2008-03-16T06:07:18Z

BaK: wording

This tutorial is divided into a few pieces. If you're completely new to [[Discretion]] development, you can view them in order, otherwise you can skip to the one you're interested in. If you go in order, they assume you have no knowledge and no tools installed.

[[Obtaining the Discretion Source using Subversion]]

[[Creating and Testing a Simple Discretion Module]]

[[Discretion Commands and Displaying Images]] (Also covers listening for callbacks and using interfaces)

[[Listening for Key Presses, Displaying Text, and Per Player Data]]

[[Category:Discretion]]
[[Category:Guides]]

Obtaining the Discretion Source using Subversion

2008-03-16T06:05:23Z

BaK: wiki'd

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

The tutorial video can be obtained here.

Links used within the tutorial:

svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91|download subversion]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-16T06:04:44Z

BaK: link

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

The tutorial video can be obtained here.

Links used within the tutorial:

svn link: [download subversion|http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-16T06:04:05Z

BaK: spacing

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

The tutorial video can be obtained here.

Links used within the tutorial:

svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91]

discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-16T06:03:42Z

BaK: spacing

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

The tutorial video can be obtained here.

Links used within the tutorial:
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91]
discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-16T06:03:16Z

BaK: wording

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have no tools already installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

The tutorial video can be obtained here.

Links used within the tutorial:
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91]
discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-16T06:02:45Z

BaK: bold'd (or would it be bold'?)

This tutorial is a '''video''' tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have nothing installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

The tutorial video can be obtained here.

Links used within the tutorial:
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91]
discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Obtaining the Discretion Source using Subversion

2008-03-16T06:02:04Z

BaK: content

This tutorial is a video tutorial describing how to obtain the Discretion source code using subversion. It assumes you know nothing and have nothing installed. It is part of the [[Discretion Module Tutorial]]. It assumes you are using Windows, although the process for other operating systems is very similar.

Subversion is a version control system which allows many programmers to incrementally and concurrently work on a project. Basically is a common way of organizing large projects superior to the "e-mail your changes to everyone" method. It also has lots of other nifty tricks which aren't important for right now.

The tutorial video can be obtained here.

Links used within the tutorial:
svn link: [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91]
discretion repository link: https://ss-discretion.svn.sourceforge.net/svnroot/ss-discretion/client/trunk

Creating and Testing a Simple Discretion Module

2008-03-16T05:54:39Z

BaK: added link to main tutorial at top

Once you obtain the [[Discretion]] source, you are ready to make a module for Discretion. If you haven't gotten the source yet, follow the instructions in [[Obtaining the Discretion Source using Subversion]]. This tutorial is part of the [[Discretion Module Tutorial]].

There are three ways to make a module: 1. Eclipse with minGW, 2. MS Visual Studio, and 3. make. If you're new, the recommended way is to use minGW and Eclipse.

== minGW and Eclipse ==
The way [[User:BaK|BaK]] works on Discretion is using minGW and Eclipse. Both pieces of software are free, and minGW is a lot like gcc so this might even work for Linux development. Eclipse is also BaK's favorite Integrated Development Environment (IDE). Currently the tutorial is oriented towards Windows users. If you want to try this method see the [[Creating and Testing a Simple Discretion Module in Eclipse]] tutorial.

== Microsoft Visual Studio ==
Microsoft Visual Studio is an IDE produced by Microsoft that supports C++ development. I've used it for a few years and it's pretty good at what it does. Students also often get free licenses for Visual Studio from their school. Currently for Discretion, development is done in Eclipse so there aren't any current visual studio projects for you to use. Nonetheless, setting one up is a snap and is covered in the [[Creating and Testing a Simple Discretion Module in MS Visual Studio]] tutorial.

== Make ==
Make is a tool that can build large projects. It relies on a compiler such as gcc. This one is typically used by the hardcore linux users, but it's also a very portable tool so it works great with cross platform development. [[Goldeye]] is currently in charge of development using make (particularly interested in Mac OS X support), and may one day make (pun!) a [[Creating and Testing a Simple Discretion Module using Make]] tutorial. Send him a ?message in-game so he knows you appreciate him working on this and encourage him to write a tutorial for us!

== Others ==
Outside of these three standard ways there are countless compilers and IDEs you can use to make any C++ project, including Discretion. However, officially we won't help you with these. Unofficially we probably will if you bug us enough ;).

[[Category:Discretion]]
[[Category:Guides]]

Discretion Module Tutorial

2008-03-16T05:53:50Z

BaK: added svn link

This tutorial is divided into a few pieces. If you're completely new to Discretion, you can view them in order, otherwise you can skip to the one you're interested in. It assumes you have no knowledge and nothing installed.

[[Obtaining the Discretion Source using Subversion]]

[[Creating and Testing a Simple Discretion Module]]

[[Discretion Commands and Displaying Images]] (Also covers listening for callbacks and using interfaces)

[[Listening for Key Presses, Displaying Text, and Per Player Data]]

[[Category:Discretion]]
[[Category:Guides]]

Creating and Testing a Simple Discretion Module

2008-03-16T05:52:23Z

BaK: hmm, forgot what i changed

Once you obtain the [[Discretion]] source, you are ready to make a module for Discretion. If you haven't gotten the source yet, follow the instructions in [[Obtaining the Discretion Source using Subversion]].

There are three ways to make a module: 1. Eclipse with minGW, 2. MS Visual Studio, and 3. make. If you're new, the recommended way is to use minGW and Eclipse.

== minGW and Eclipse ==
The way [[User:BaK|BaK]] works on Discretion is using minGW and Eclipse. Both pieces of software are free, and minGW is a lot like gcc so this might even work for Linux development. Eclipse is also BaK's favorite Integrated Development Environment (IDE). Currently the tutorial is oriented towards Windows users. If you want to try this method see the [[Creating and Testing a Simple Discretion Module in Eclipse]] tutorial.

== Microsoft Visual Studio ==
Microsoft Visual Studio is an IDE produced by Microsoft that supports C++ development. I've used it for a few years and it's pretty good at what it does. Students also often get free licenses for Visual Studio from their school. Currently for Discretion, development is done in Eclipse so there aren't any current visual studio projects for you to use. Nonetheless, setting one up is a snap and is covered in the [[Creating and Testing a Simple Discretion Module in MS Visual Studio]] tutorial.

== Make ==
Make is a tool that can build large projects. It relies on a compiler such as gcc. This one is typically used by the hardcore linux users, but it's also a very portable tool so it works great with cross platform development. [[Goldeye]] is currently in charge of development using make (particularly interested in Mac OS X support), and may one day make (pun!) a [[Creating and Testing a Simple Discretion Module using Make]] tutorial. Send him a ?message in-game so he knows you appreciate him working on this and encourage him to write a tutorial for us!

== Others ==
Outside of these three standard ways there are countless compilers and IDEs you can use to make any C++ project, including Discretion. However, officially we won't help you with these. Unofficially we probably will if you bug us enough ;).

[[Category:Discretion]]
[[Category:Guides]]

Discretion

2008-03-16T05:50:32Z

BaK: added tutorial higher up

[[Image:discretionss.PNG|thumb|A Screenshot of SubSpace Discretion.]]

Discretion[http://ss-discretion.sf.net] is a [[SubSpace]] client created by [[User:BaK|BaK]]. It is open source, like [[ASSS]], and is released under the [http://en.wikipedia.org/wiki/GPL GPL]. Discretion was developed because of the limitations of the in-use client, [[Continuum]]. Furthermore, the lack of development of Continuum led to a situation where limitations in the client would never be overcome. Making heavy use of [http://en.wikipedia.org/wiki/Simple_DirectMedia_Layer SDL], Discretion is cross-platform, and is currently supported under Windows and Linux, with Mac OS X support on the way. Discretion is intended to be secure through design, rather than through obscurity like Continuum. It is designed to make cheating is impossible, rather than just difficult. There is also an extensive [[Discretion Module Tutorial]] on this wiki for those interested in helping out.

Since cheating is to be made impossible, the server must check the data players send it for cheating. This requires modifying the server, which rules out using [[Subgame]]. There is, however, a modified ASSS Server that allows Discretion clients to connect.

In order to encourage client development, Discretion is designed with a modular system similar to ASSS. There are interfaces which define actions for modules (such as "draw ship at 50,50"), and callbacks which signal when events occur (such as "player has been killed"). Where ever possible, magic values have been removed and are instead loaded from plain-text settings files. The goal of this is to eliminate any built-in constraints present in VIE SubSpace and Continuum. These magic values include the location / color of the FPS counter, 1024x1024 tiles in maps, each tile being 16x16 pixels, each ship image having 40 frames thus 9 degree turns, the number of fly over tiles, two sets of doors four tiles each per map, the 0x01 type packet corresponding to an arena login, friendly players showing up yellow in the stat box, the colors in the font file, the number of frames in the wormhole animation, the text that shows up when you press ESC, the number of ships, as well as all the settings Continuum does allow you to change such as the ship images, the game play settings, and the controls. The server is intended to be able to modify most of these, thus giving [[Zone]] developers maximum creativity and flexibility.

==Modules==
Discretion is divided up into several modules, dynamically linked into the main program much like ASSS. These modules are desired to be as generic as possible, with their Continuum-like actions coming from the settings, rather than the modules themselves. Thus Discretion is like a 2D grid game engine, with settings and graphics which make it look like SubSpace. The module interfaces are documented in the corresponding header files using Javadoc-style documentation. There are currently over 30 modules in the Discretion release. Some of the main ones are discussed below.

===Settings Handler===
The '''SettingsHandler''' modules loads the settings from ini-like plain text files. The main settings file is located in conf/MAIN.CONF, which #includes many other settings files. All these settings files are plain text, meaning they can be edited using a utility like pico or notepad. Individual settings can be specified in several formats, depending on how they should be interpreted. Supported types include integers (''50'', ''0x30'', ''0777''), strings (''hello person''), points/vectors/dimensions (''(100,200)''), rgb colors (''(255,255,255)'', ''(0,128,128)''), and [[LVZ]]-style screen locations (''(C+50,50)'', ''(B-10,C+25)''). There also exists a helper function to parse comma separated a list of strings from a single sting in shared/StringManip.h. This module interface also allows modules to load their own conf files, or save a group of settings to a file which the program can then read out of.

The front end program, '''cskinviewer''' uses the saving capability of '''SettingsHandler''' to keep track of zone data between program executions.

===Module Manager===
The '''Module Manger''' itself is a module which is loaded by the program, which then proceeds to load any other modules. This uses the setting Modules::Names which is a comma separated list of strings to figure out which modules to load. It loads module files, '.dll's in Windows and '.so's in Linux, from the bin/ directory. Modules are loaded in stages. During the first stage, LOADMODE_Init, modules register their interface, if any, with the '''Module Manager''' and register any callbacks they want to listen for. During the next stage, LOADMODE_LoadInterfaces, modules load any interfaces they plan to use. Finally, during LOADMODE_PostLoadInterfaces, modules can use their loaded interfaces to other modules to initialize themselves. Upon successful program termination, LOADMODE_Unload is invoked which allows the module to free any data or resources it's using. The module manager also facilitates callbacks. Where possible, C++ exception handling is used to aid in catching errors in a non-fatal way and reports the cause of the problem.

Note that some initialization tasks should not be done in LOADMODE_PostLoadInterfaces since they require modules be initialized in a specific order. For example, the '''Text''' module, which writes text to the screen should not be initialized before the ''Graphics'' module is, since it would be unable to load the text image. Thus some initialization tasks are be done in callbacks, CB_LOADIMAGES in this instance.

===Graphics===
The '''Graphics''' module allows one to load images and draw them to the screen or map. When an image is loaded through the interface, an image handle is given to the calling module which is used to refer to the image. This handle can also be used to get the image size (taking into account that some images are framed animations), or free the image when it's no longer needed. Blank images can also be created and drawn on, thus allowing one to predraw complex images instead of redrawing them every frame. Images, when drawn to the screen, are drawn in layers. This allows several modules to queue up images to be drawn out of order and still result in a correct drawing. Some layers include L_Tiles, L_Weapons, L_AfterWeapons, L_Gauges, L_Chat and L_TopMost. Images can be drawn relative to the screen, or relative to the map. Images can also be blended such that they appear translucent, as long as the user has Graphics::UseBlending set to 1. Rectangles of a constant color can also be drawn to the screen or on to another image. The images are queued up to be drawn during the CB_PRERENDER callback.

Although providing a basic interface, it is uncommon to '''Graphics''' module directly for loading images. Instead the '''UniqueImage''' module allows one to specify an image in the settings and refer to it in code by a name. This is much easier than loading the image yourself, and easily allows a single graphic to contain many different images, which is not uncommon in SubSpace images (the bullets image, for example, contains images for all sorts of bullets rather than just a single type). The '''UniqueImage''' module makes sure to only keep a single copy of the image in memory at all times. The '''UniqueImage''' module, in turn, is used by the '''Animations''' module to provide simple access to SubSpace-style animations. Thus, a programmer can code something like 'draw animation "bullet explosion" at 512,512' and it will handle loading the image, figuring out how many frames there are, the speed of the animation, and how long to display it for.

===Controls===
The '''Controls''' module permits the programmer to provide actions("move forward"), while the settings specify exactly what keyboard or joystick input they correspond to("up arrow key"). Controls should be registered in the CB_CONTROLSLOADED callback. Also, since this a generic module it does not capture any of the physical controls itself, instead relying on other modules to handle that aspect.

The '''SDL Key Controls''' module handles capturing keyboard input and sending it to the '''Controls''' module. The '''Mouse''' module does not use the '''Controls''' module directly, instead providing its own interface which allows one to create mouse hotspots and be notified of mouse clicks or movements within these hotspots.

===Timers===
Similar to how ASSS has timers implemented in the mainloop module, Discretion has a '''Timers''' module that provides a timer functionality. One can register a function to be called in X milliseconds, or every X milliseconds until it's canceled. Discretion is currently not multithreaded beyond SDL, so that a timer in an infinite loop (or any piece of code that gets to run, for that matter), will result in the program freezing up. Thus you should not use blocking calls in timers or take up too much processing time which will degrade performance.

The '''Net''' module uses a timer to send and receive packets.

===Text===
The '''Text''' module provides an easy way to draw text on the screen. This is the standard subspace text and can be specfied by color. This module draws the text on one line for a single frame. Therefore, you must call the appropriate functions in this interface during CB_PRERENDER every frame for however long you wish to display the text. There is support for drawing text relative to the screen or to the map, as well as blending text and drawing on any layer.

The '''Textbox''' module uses '''Text''' to draw its text, but provides additional features such as drawing textbox borders and allowing easy textbox loading from files. '''EscapeBox''' and '''PlayerList''', in turn, use '''Textbox'''. '''Chat''' also makes use of the '''Text''' module when it draws player chat to the screen. The '''Flash''' module, which handles messages similar to SubSpace's kill and prize messages, also uses the '''Text''' module. Pretty much anywhere you see text, the '''Text''' module is at work.

===Physics===
The '''Physics''' module provides functions which can give you a particle's new position given its initial position, velocity, and time elapsed. This is used for ships as well as weapons. The position can be advanced in such a way that is affected by the map (such as bombs going around a wormhole), or not. Particles can bounce off the level or explode on contact.

The '''SelfShip''' module uses '''Physics''' to compute the new position of the player over time. '''SS_Items''' uses '''Physics''' to find the position of a bullet after a certain amount of time.

===PerPlayerData===
The '''PerPlayerData''' module provides a simple way to have data that is common to every player. This is similar to ASSS' PlayerData module in that a struct of memory can be allocated for every player and referred to using a key. The module also facilitates simple sharing of per player data between module such as "name", "x", or "y".

The '''PlayerList''' module uses the sharing facility of '''PerPlayerData''' to get the names of the players on the player list.

===Level===
The '''Level''' module provides a simple interface to possibly many different types of level formats. Modules can load levels through the interface, as well as get the map or tile size. Furthermore, forces on the level, such as wormholes, friction, or gravity can be applied through the interface.

Currently, the only map format implemented is '''oldlvl''' which supports regular SubSpace [[LVL]] files. This provides a somewhat more generic implementation, which a customizable amount of doors or custom animation tiles (wormholes, space station, and asteriods), as well as having wormholes with different properties on the same map.

===Front End===
The front end, not exactly a module, is implemented as its own program, '''cskinviewer''', contributed by [[User:Smong|Smong]]. This program allows one to download a list of ASSS servers from a [[Directory Server]], and choose one and login. It uses the '''SettingsHandler''' to save the current zone list to the settings. Custom zones can not be added through the interface yet, but can be added by hand by editing conf/profiles/ZoneList.conf.

The front end executes '''in_game''', which in turn loads the '''Module Manager''' which runs '''Main SDL''' which runs callbacks to load the various SDL Subsystems and starts the program's main loop.

==Contribute==
Development for Discretion is ongoing and everyone is encouraged to contribute. Graphics are always helpful, and if you have an idea feel free to make it. In the spirit of free software, it would be best if eventually all VIE owned graphics were replaced, as their copyright status is unknown. This includes the ships, bullets, default tileset, and all other graphics from VIE SubSpace or Continuum. Also, a Discretion [[skin]] is yet to be made for the front end (the format follows that of Continuum's, see the skins directory in your Continuum folder). Additionally, many features are in development or unimplemented. If one wanted to help out, just contact [[User:BaK|BaK]], or start working on graphics or a module. There is also a [[Discretion Module Tutorial]] which shows you how to create a simple module. Some planned modules include:

====Star Background====
A '''StarBackground''' module that draws stars and planets similar to how Continuum does it. It would be great it this looked better than Continuum as it would really lead to the immersion necessary for a fun experience. This could also be used to draw all sorts of backgrounds, such as grass for earth-based zones, to provide an alternate to tiling LVZ all over the map. This would be a good module to make to get introduced to Discretion development.

====LVZ====
A reverse compatible LVZ module is desired to allow current zones to easily switch over to Discretion without remaking their lvz files. This could provide additional functionality not present in current lvz such as lvz that depend on ship locations to allow animations within shipsets. The easier way to make this is probably to make a static image/animation module which uses the settings and '''UniqueImage''' and '''Animations''' to draw images on the map and screen. Then, an lvz compatibility layer module would be made which translates an lvz file into a .conf file and uses '''SettingsHandler''' to load in the images from the generated file.

====Radar====
Subspace and Continuum include a radar for locating enemies. This will have to be implemented in Discretion. The users should also be able to make the radar bigger by pressing a key (alt).

====File Transfer====
This module is currently being worked on. This will allow file transfer using STP (SubSpace Transfer Protocol) as well as HTTP. This will permit quicker downloads as servers can put their files on the net instead of forcing everyone to download off the slow servers. Files transferred will include the settings, maps, and lvz files.

====Sound====
Sound provides immersion in video games and gives them an authentic feel. We need a way to play sounds when certain actions occur such as a bullet being fired or player bouncing off a wall. WAV sounds will have to be implemented for reverse compatibility, but mp3 is not out of the question for longer sounds such as victory music or just music in general. After this is done, a built in mp3 player could be made to allow players to change songs from within the game. SDL_mixer[http://www.libsdl.org/projects/SDL_mixer/] provides mp3 capabilities and may be used.

====Weapons====
Currently, only non-bouncing bullets are implemented. There are many items SubSpace uses which must be implemented. Care must be taken here to prevent cheating. For example, it would not be difficult to write a program to detect right before a player is about to get hit and automatically portal out or repel. Thus, these items may have to be modified to be on a timer, so that using a portal might require your ship to take a second to "charge up" instead of instantly warping. Also, it would be great if weapons didn't have to follow boring straight lines and instead could turn. Thus I could specify in the settings the direction a weapon would travel if the ship were facing straight up and it would happen. So a straight line would be (0,t), a curvy shot may be (sin(t),t), a shot that speeds up over time may be (0,2^t).

====Custom Client Side Code====
The server should be able to provide code that can be executed client side. There are two types of code that will be provided: updated versions of modules, and game play related code. This is especially dangerous since a malicious server owner should not be permitted to compromise players' computers. The module updates can be done by providing a RSA signature with the binary .dll or .so which can be checked before executing any downloaded files. As for game play related code, a Java virtual machine could be used with a Security Manager that allows nothing beyond basic functions. Then, an interface could be provided to the game code that could be used by the code. Thus, binary .class file could be distributed for an arena that aren't allowed to delete files off your computer, but are allowed to access the game play relayed interface thus permitting graphics to be drawn or players to be warped around.

==External links==
*[http://ss-discretion.sf.net Main Discretion Website]

[[Category: Clients]]
[[Category: Discretion]]

Creating and Testing a Simple Discretion Module

2008-03-16T05:48:27Z

BaK: added category

Once you obtain the [[Discretion]] source, you are ready to make a module for Discretion. If you haven't gotten the source yet, follow the instructions in [[Obtaining the Discretion Source using Subversion]].

There are three ways to make a module: 1. Eclipse with minGW, 2. MS Visual Studio, and 3. make. If you're new, the recommended way is to use minGW and Eclipse.

== minGW and Eclipse ==
The way [[BaK]] works on Discretion is using minGW and Eclipse. Both pieces of software are free, and minGW is a lot like gcc so this might even work for Linux development. Eclipse is also BaK's favorite Integrated Development Environment (IDE). Currently the tutorial is oriented towards Windows users. If you want to try this method see the [[Creating and Testing a Simple Discretion Module in Eclipse]] tutorial.

== Microsoft Visual Studio ==
Microsoft Visual Studio is an IDE produced by Microsoft that supports C++ development. I've used it for a few years and it's pretty good at what it does. Students also often get free licenses for Visual Studio from their school. Currently for Discretion, development is done in Eclipse so there aren't any current visual studio projects for you to use. Nonetheless, setting one up is a snap and is covered in the [[Creating and Testing a Simple Discretion Module in MS Visual Studio]] tutorial.

== Make ==
Make is a tool that can build large projects. It relies on a compiler such as gcc. This one is typically used by the hardcore linux users, but it's also a very portable tool so it works great with cross platform development. [[Goldeye]] is currently in charge of development using make (particularly interested in Mac OS X support), and may one day make (pun!) a [[Creating and Testing a Simple Discretion Module using Make]] tutorial. Send him a ?message in-game so he knows you appreciate him working on this and encourage him to write a tutorial for us!

== Others ==
Outside of these three standard ways there are countless compilers and IDEs you can use to make any C++ project, including Discretion. However, officially we won't help you with these. Unofficially we probably will if you bug us enough ;).

[[Category:Discretion]]
[[Category:Guides]]

Creating and Testing a Simple Discretion Module

2008-03-16T05:47:52Z

BaK: content

Once you obtain the [[Discretion]] source, you are ready to make a module for Discretion. If you haven't gotten the source yet, follow the instructions in [[Obtaining the Discretion Source using Subversion]].

There are three ways to make a module: 1. Eclipse with minGW, 2. MS Visual Studio, and 3. make. If you're new, the recommended way is to use minGW and Eclipse.

== minGW and Eclipse ==
The way [[BaK]] works on Discretion is using minGW and Eclipse. Both pieces of software are free, and minGW is a lot like gcc so this might even work for Linux development. Eclipse is also BaK's favorite Integrated Development Environment (IDE). Currently the tutorial is oriented towards Windows users. If you want to try this method see the [[Creating and Testing a Simple Discretion Module in Eclipse]] tutorial.

== Microsoft Visual Studio ==
Microsoft Visual Studio is an IDE produced by Microsoft that supports C++ development. I've used it for a few years and it's pretty good at what it does. Students also often get free licenses for Visual Studio from their school. Currently for Discretion, development is done in Eclipse so there aren't any current visual studio projects for you to use. Nonetheless, setting one up is a snap and is covered in the [[Creating and Testing a Simple Discretion Module in MS Visual Studio]] tutorial.

== Make ==
Make is a tool that can build large projects. It relies on a compiler such as gcc. This one is typically used by the hardcore linux users, but it's also a very portable tool so it works great with cross platform development. [[Goldeye]] is currently in charge of development using make (particularly interested in Mac OS X support), and may one day make (pun!) a [[Creating and Testing a Simple Discretion Module using Make]] tutorial. Send him a ?message in-game so he knows you appreciate him working on this and encourage him to write a tutorial for us!

== Others ==
Outside of these three standard ways there are countless compilers and IDEs you can use to make any C++ project, including Discretion. However, officially we won't help you with these. Unofficially we probably will if you bug us enough ;).

Creating and Testing a Simple Discretion Module in MS Visual Studio

2008-03-16T05:19:19Z

BaK: Creating and Testing a Simple Discretion Module moved to Creating and Testing a Simple Discretion Module in MS Visual Studio: adding an eclipse version

This is a tutorial for module creation in [[Discretion]]. For other tutorials, see the [[Discretion Module Tutorial]].

Making a module is easy pie once you know what to do, so let's get to it.

==Windows with MSVC==

First step: make a new VS.net C++ Project.

1. File -> New Project

2. Win32 Console Project

3. Give your project a name ("TestModule" in the picture)

4. Press Ok

[[Image:disc_module1.PNG]]

5. Click on application settings on the left

6. Click DLL from the list of radio buttons

7. Press the Empty Project checkbox

8. Press Finish

[[Image:disc_module2.PNG]]

9. File -> Add New Item

10. Select C++ Source File (.cpp)

11. Name your source file ("testmodule.cpp" in the picture)

12. Press Open

[[Image:disc_module3.PNG]]

13. Paste the following code into your source file
<pre>// Sample Discretion Module Source File
#include "Module.h"

void* getClassInstance(void* _mm, LoadMode lm)
{
if (lm == LOADMODE_Init)
printf("Test Module Initialized\n");

return 0;
}

extern "C"
{
EXPORT void* getInstance(void* mm, LoadMode lm)
{
return getClassInstance(mm,lm);
}
}</pre>

14. Right Click your project in the Solution Explorer and go to Properties (You can also access this through the Project Menu, Project -> Properties)

[[Image:disc_module4.PNG]]

15. In the properties window, from the drop down menu select "All Configurations"

16. Select C++, General from the tree view on the left

17. Type the directory to the Modules directory (the one with Module.h in it, not the one with only .dlls!) that comes with the full version of Discretion in the Additional Include Directory property ("E:/client/modules" in the picture)

18. Press Ok

[[Image:disc_module5.PNG]]

19. Go to Buld -> Build <project name> ("TestModule" in the pictue)

[[Image:disc_module6.PNG]]

If all goes well, you code should compile and a .dll should be produced that is a Discretion module! Now let's put the module into Discretion to see it at work.

20. Copy the produced .dll into your Discretion executable's Module folder (the one with the .dlls in it, not the one with Module.h in it).

[[Image:disc_module7.PNG]]

21. Edit conf/MAIN.CONF with a program such as Notepad

22. Add the name of your dll to the Modules::Names setting (it's a comma seperated list of module names, order doesn't matter)

23. Save the file

[[Image:disc_module8.PNG]]

24. Run Discretion, Select Practice Offline

25. Observe your modules initialization in the console window

[[Image:disc_module9.PNG]]

Now you might say, rightfully so, that this module doesn't do anything. The way to do real things in Discretion is by using other modules. Want to react to user key presses? Use the KeyControls module. Want to display some images? Use the Graphics module. I'll gladly write additional tutorials for how to use each of these as needed. Tell me what you want to do and I'll write a tutorial with how to use the existing modules to accomplish what you want to do.

[[Category:Discretion]]
[[Category:Guides]]

Creating and Testing a Simple Discretion Module

2008-03-16T05:19:19Z

BaK: Creating and Testing a Simple Discretion Module moved to Creating and Testing a Simple Discretion Module in MS Visual Studio: adding an eclipse version

#REDIRECT [[Creating and Testing a Simple Discretion Module in MS Visual Studio]]

UDP Game Protocol

2008-01-11T02:44:19Z

BaK: all those websites were down lol

This is a document outlining the UDP protocol used by game clients ([[Continuum]], [[SubSpace]], and all of the [[Bots]] in use today). This is not exhaustive but has been compiled from [[LogicBot|LogicBot++]], [[MERVBot]], and various other places. All clients also use the [[core protocol]]. '''It is, as of right now, incomplete. This guide is not complete; some packets do not have their contents filled out.''' See the [[Game Protocol FAQ]] article for additional information.

<pre>
Full Packet List (Consolidated Subspace and Continuum Packet List)

//====================\\
|| C2S ||
\\====================//

ID CLASS HANDLER PKT DESC
- OFFSET LEN CONTENTS
- [Type Meaning]

----------------------------------------
0x01 Game 0x40B750 Arena Login

- 0 1 Type
- 1 1 Ship type
- 2 2 Allow audio?
- 4 2 X resolution
- 6 2 Y resolution
- 8 2 Main arena number 0xFFFF for random pub, 0xFFFD for sub.
- 10 16 Arena name (optional, if offset 8 is 0xFFFD)

----------------------------------------
0x02 Game 0x40B3C1 Leave arena

- 0 1 Type

----------------------------------------
0x03 Game 0x409BA9 Position

- 0 1 Type
- 1 1 Direction
- 2 4 Timestamp
- 6 2 X velocity
- 8 2 Y pixels
- 10 1 Checksum
- 11 1 Togglables
- 12 2 X pixels
- 14 2 Y velocity
- 16 2 Bounty
- 18 2 Energy
- 20 2 Weapon info
- 22 2 Energy (Optional)
- 24 2 S2C latency (Optional)
- 26 2 Timer (Optional)
- 28 4 Item info (Optional)

----------------------------------------
0x04 Game 0x40CAA1 Packet tampering

- 0 1 Type

----------------------------------------
0x05 Game 0x40A15B Death message

- 0 1 Type

----------------------------------------
0x06 Chat 0x40B67C Chat

- 0 1 Type
- 1 1 Chat type
- 0x00 Arena
- 0x01 Public macro
- 0x02 Public message
- 0x03 Team message
- 0x04 Freq
- 0x05 Private message
- 0x06 Moderator warning
- 0x07 Remote private message
- 0x09 Channel message
- 2 1 Sound code
- 3 2 Target player's player ID
- 5 - Text

----------------------------------------
0x07 Game 0x40AC3B Take green

- 0 1 Type

----------------------------------------
0x08 Game 0x40B26E Spectate request

- 0 1 Type
- 1 2 Player ID

----------------------------------------
0x09 Game 0x40C0E7 Password/Login

- 0 1 Type
- 1 1 Boolean: New user (1 = New, 0 = Not New)
- 2 32 Name
- 34 32 Password
- 66 4 Machine ident (drive serial number - can be random for bots)
- 70 1 ConnectType (0x00 is a good idea)
- 71 2 Timezone bias
- 73 2 Unkown
- 75 2 Client version (0x24 = Ctm, 0x86 = SS)
- 77 4 Unkown, memory checksum, Set to = 444
- 81 4 Unkown, memory checksum, Set to = 555
- 85 4 Permission ident
- 89 12 Unkown

----------------------------------------
0x0A Game 0x40CAA1 Packet tampering

- 0 1 Type

----------------------------------------
0x0B Game 0x409EA9 SSUpdate.EXE request

- 0 1 Type

----------------------------------------
0x0C Game 0x409A6F Map Request

- 0 1 Type

----------------------------------------
0x0D Game 0x409A9F news.txt request

- 0 1 Type

----------------------------------------
0x0E Game 0x40B4D7 Voice message

- 0 1 Type

----------------------------------------
0x0F Game 0x40AEF5 Frequency change

- 0 1 Type

----------------------------------------
0x10 Game 0x40BF47 Attach request

- 0 1 Type

----------------------------------------
0x11 Game 0x40CAA1 Packet tampering

- 0 1 Type

----------------------------------------
0x12 Game 0x40CAA1 Packet tampering

- 0 1 Type

----------------------------------------
0x13 Game 0x40ADDC Flag request

- 0 1 Type

----------------------------------------
0x14 Game 0x40B183 Drop all attached pilots

- 0 1 Type

----------------------------------------
0x15 Game 0x40B1EB Drop flags

- 0 1 Type

----------------------------------------
0x16 Game 0x40B8C7 File transfer

- 0 1 Type

----------------------------------------
0x17 Game 0x40B645 Registration information response

- 0 1 Type

----------------------------------------
0x18 Game 0x40AF19 Set ship type

- 0 1 Type

----------------------------------------
0x19 Game 0x40B41E Set personal banner

- 0 1 Type

----------------------------------------
0x1A Game 0x4097BA Security checksum

- 0 1 Type Byte 0x1A
- 1 4 Weapon Count
- 5 4 Settings Checksum *2
- 9 4 Subspace.EXE Checksum
- 13 4 Map.LVL Checksum
- 17 4 S2CSlowTotal
- 21 4 S2CFastTotal
- 25 2 S2CSlowCurrent
- 27 2 S2CFastCurrent
- 29 2 S2CRelOut (?Unsure?)
- 31 2 Ping
- 33 2 Ping Average
- 35 2 Ping Low
- 37 2 Ping High
- 39 1 Slow Frame Detected (Boolean)

----------------------------------------
0x1B Game 0x4096C9 Security violation

- 0 1 Type

----------------------------------------
0x1C Game 0x409626 Drop brick

- 0 1 Type

----------------------------------------
0x1D Game 0x40948B ?setsettings

- 0 1 Type

----------------------------------------
0x1E Game KotH Timer drop

- 0 1 Type

----------------------------------------
0x1F Game 0x408EBD Fire a ball

- 0 1 Type

----------------------------------------
0x20 Game 0x409322 Ball request

- 0 1 Type

----------------------------------------
0x21 Game 0x408F95 Soccer goal scored

- 0 1 Type

----------------------------------------
0x22 Game 0x4096E2 ? Task switch ?

- 0 1 Type

*Logged packets:
22 59 B8 13 03 3A 9E 96 60 48 C9 1C 28 0E 00 00 00 00
22 1D 51 DD 00 9A 58 3C 89 48 C9 1C 28 AB 00 00 00 00

----------------------------------------
0x23 CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x24 CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x25 CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x26 CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x27 CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x28 CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x29 CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x2A CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------
0x2B CTMGame 0x40C0E7 Continuum login

- 0 1 Type

----------------------------------------

//====================\\
|| S2C ||
\\====================//

ID CLASS Handler DESC
- OFFSET LEN CONTENTS
- [Type Meaning]

----------------------------------------
0x01 Game 0x402A7E UID notification

- 0 1 Type
- 1 2 ID

----------------------------------------
0x02 Game 0x402A24 In game /* We are in the arena */

- 0 1 Type

----------------------------------------
0x03 Game 0x402B43 Player Entering

- 0 1 Type
- 1 1 Ship type
- 2 1 Accepts audio messages
- 3 20 Player name (confirmed ASCIIZ)
- 23 20 Squad name (confirmed ASCIIZ)
- 43 4 Flag points
- 47 4 Kill points
- 51 2 Player ident
- 53 2 Team
- 55 2 Wins
- 57 2 Losses
- 59 2 Turretee ident
- 61 2 Flags carried
- 63 1 Boolean: Has KoTH

----------------------------------------
0x04 Game 0x402C58 Player leaving

- 0 1 Type
- 1 1 Player ID

----------------------------------------
0x05 Game 0x402D34 Player fired a weapon

- 0 1 Type

----------------------------------------
0x06 Game 0x402CFC Player died

- 0 1 Type
- 1 1 Death green
- 2 2 Killer ident
- 4 2 Killed ident
- 6 2 Bounty
- 8 2 ? Flags

----------------------------------------
0x07 Chat 0x40303D Chat

- 0 1 Type
- 1 1 Message Type
- 0x00 Arena
- 0x01 Public macro
- 0x02 Public message
- 0x03 Team message
- 0x04 Freq
- 0x05 Private message
- 0x06 Moderator warning
- 0x07 Remote private message
- 0x08 Red server errors, without a name tag (S2C only)
- 0x09 Channel message
- 2 1 Sound Code
- 3 2 PlayerID
- 5 - Message

----------------------------------------
0x0A Game 0x40306F Password response

- 0 1 Type byte
- 1 1 Accept response meaning
- 0 Login OK.
- 1 Unknown user.
- 2 Bad password.
- 3 Full arena.
- 4 Locked out.
- 5 Perission only.
- 6 Spectate only.
- 7 Too many points.
- 8 Connection too slow.
- 9 Perission only arena.
- 10 Server full.
- 11 Invalid name.
- 12 Offensive name.
- 13 No biller (not saving scores).
- 14 Server busy
- 15 Restricted zone (insufficient usage)
- 16 Demo Version <- If you get this, theres a serious problem.
- 17 Too many Demo Users (Same as above applys)
- 18 No Demo Players Allowed (again same as the above two)
- 255 Mod Access Required (An invalid value, used only in CEBot)
- 2 4 Server version
- 6 4 ?
- 10 4 EXE checksum
- 14 4 ? unused
- 18 1 ? boolean
- 19 1 Boolean: Request registration form
- 20 4 ? memory checksum
- 24 4 News checksum (0 = no news file)
- 28 4 ? time/date
- 32 4 ? time/date

----------------------------------------
0x09 Game 0x402C22 Player score changed

- 0 1 Type

----------------------------------------
0x0A Game 0x4033AB Password packet response

- 0 1 Type

----------------------------------------
0x0B Game 0x403386 Soccer goal

- 0 1 Type

----------------------------------------
0x0C Game 0x402BEF Player voice

- 0 1 Type

----------------------------------------
0x0D Game 0x402C7C Set player frequency

- 0 1 Type
- 1 2 Player ID
- 3 2 New Freq
- 5 1 Unknown (0xFF)

----------------------------------------
0x0E Game 0x402BC6 Create turret link

- 0 1 Type byte
- 1 2 Turreter ident (gunner)
- 3 2 Turretee ident (driver)(when -1, detaching)

----------------------------------------
0x0F Game 0x402A43 Arena settings

- 0 1 Type

----------------------------------------
0x10 Game 0x4027CD File transfer

- 0 1 Type

----------------------------------------
0x11 Game 0x4033AB No-op

- 0 1 Type

----------------------------------------
0x12 Game 0x4031D4 Flag position

- 0 1 Type

----------------------------------------
0x13 Game 0x403233 Flag claim

- 0 1 Type

----------------------------------------
0x14 Game 0x4030D5 Flag victory

- 0 1 Type

----------------------------------------
0x15 Game 0x40325C Destroy turret link

- 0 1 Type byte
- 1 2 Player ident

----------------------------------------
0x16 Game 0x403280 Drop flag

- 0 1 Type

----------------------------------------
0x17 Game 0x4033AB No-op

- 0 1 Type

----------------------------------------
0x18 Game 0x4030A6 Synchronization

- 0 1 Type

----------------------------------------
0x19 Game 0x4028FB Request file

- 0 1 Type

----------------------------------------
0x1A Game 0x4032A4 Reset score(s)

- 0 1 Type

----------------------------------------
0x1B Game 0x4032C8 Personal ship reset

- 0 1 Type

----------------------------------------
0x1C Game 0x4032E4 Put player in spectator mode / change extra info flag

- 0 1 Type

----------------------------------------
0x1D Game 0x402CC1 Player team and ship changed

- 0 1 Type byte
- 1 1 Ship type
- 2 2 Player ident
- 4 2 Team

----------------------------------------
0x1E Game 0x4033AB Banner flag

- 0 1 Type

----------------------------------------
0x1F Game 0x403209 Player banner changed

- 0 1 Type

----------------------------------------
0x20 Game 0x402ABF Collected prize

- 0 1 Type

----------------------------------------
0x21 Game 0x403302 Brick dropped

- 0 1 Type
repeated until the end of the message
- 1 2 X1 tiles
- 3 2 Y1 tiles
- 5 2 X2 tiles
- 7 2 Y2 tiles
- 9 2 Team
- 11 2 Brick ident (sent more than once)
- 13 4 Timestamp

----------------------------------------
0x22 Game 0x40316E Turf flag update

- 0 1 Type
repeated until the end of the message
- 1 2 Team for flag X

----------------------------------------
0x23 Game 0x403192 Flag reward granted

- 0 1 Type
repeated until the end of the message
- 1 2 Team
- 3 2 Points

----------------------------------------
0x24 Game 0x402AEA Speed zone statistics

- 0 1 Type

----------------------------------------
0x25 Game 0x402B1F Toggle UFO ship

- 0 1 Type

----------------------------------------
0x26 Game 0x4033AB No-op

- 0 1 Type

----------------------------------------
0x27 Game 0x4033AB Keep-alive

- 0 1 Type

----------------------------------------
0x28 Game 0x402EE3 Player position update

- 0 1 Type

----------------------------------------
0x29 Game 0x4030FD Map information

- 0 1 Type

----------------------------------------
0x2A Game 0x402867 Compressed map file

- 0 1 Type

----------------------------------------
0x2B Game 0x402787 Set personal KoTH timer

- 0 1 Type

----------------------------------------
0x2C Game 0x402762 KoTH game reset

- 0 1 Type

----------------------------------------
0x2D Game 0x4027AA ? Some other timer change ?

- 0 1 Type

----------------------------------------
0x2E Game 0x402741 Power-ball position update

- 0 1 Type

----------------------------------------
0x2F Game 0x403364 Arena directory listing

- 0 1 Type

----------------------------------------
0x30 Game 0x402707 Got zone banner advertisements

- 0 1 Type

----------------------------------------
0x31 Game 0x4033A6 Login Finished

- 0 1 Type

----------------------------------------
0x31 CTMGame You are now past the login sequence

- 0 1 Type

----------------------------------------
0x32 CTMGame Change personal ship coordinates

- 0 1 Type

----------------------------------------
0x33 CTMGame Custom login failure message

- 0 1 Type

----------------------------------------
0x34 CTMGame Continuum version packet

- 0 1 Type

----------------------------------------
0x35 CTMGame Object toggling

- 0 1 Type

----------------------------------------
</pre>
[[Category: Protocol]]