Difference between revisions of "MERVBot Tutorial"

Revision as of 12:18, 20 February 2005

This tutorial is based on the ever-popular MERVBot Tutorial by Underlord. It has since been updated to reflect new changes with MervBot.

This tutorial also assumes that you have a basic knowledge of C++. If you don't, check out cplusplus.com's great documentation.

1 Setting up a MERVBot (plugin)
2 Player Commands - (command.cpp)
3 Event Calls
4 The Messaging System
- 4.1 Output of data in messages
5 Timer - How to use the timing function
6 Writing Functions
- 6.1 Function notes
7 Cycling through players
8 Random numbers
- 8.1 Generating a random number
- 8.2 Picking a random pilot
9 Tracking time not using countdown[n]
10 Storing data for pilots
11 Input/Output to files
12 Player data
13 Bot built in functions
14 Example Code

Setting up a MERVBot (plugin)

MERVBot download site

MERVBot Forum (Development - MervBot forum)

Obtaining MERVBot

Download the 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 step 4, otherwise continue to learn how to make your own bot

Download 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++

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

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).

Edit spawns.txt. Read every word of spawns.txt to find out what needs to go in there.
Example:
```
2v2-Bot-League : botpw : 2v2a : 2v2league : staffpw
```
Note: The bot will attempt to create the name if it doesn't exist already.

Edit MERVBot.ini

[Login]
Zone=216.33.98.254:21000	// make that your zone IP:PORT available from zone.dat in Continuum dir

Edit operators.txt. Read every word of operators.txt to find out what needs to go in there.
Example:
```
4:my_name:
4:another_sysop:
3:other_person:
```
Make sure the bot is on vip.txt or has smod+ access, then run MERVBot.exe.
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.

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"):

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

How to have commands with numerical parameters

Example (!test #):

	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);

How to have player name as input

Example (!rank player):

	if (c->check("rank"))
	{
		String player_name = c->final;

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

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):

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

Help Menu

When a player sends !help to the bot, MERVBot calls botInfo::gotHelp() in each plugin loaded.

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");

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().

tell(makeFollowing(false));

The Messaging System

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

Examples:

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.");

Team message - void sendTeamPrivate(Uint16 team, char *msg);

Examples:

a) sendTeamPrivate(8025,"hi spec freq");
b) Uint16 test=0; sendTeamPrivate(test,"hi freq 0");

Public message - void sendPublic(char *msg);

Example: sendPublic("*arena " + (String) p->name + " is now a captain");

Chat channel message - void sendChannel(char *msg);

Example: sendChannel("hi chat channel");

Remote private message - void sendRemotePrivate(char *name, char *msg);

Example: sendRemotePrivate("Player01", "hi");

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.

 // 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);

Or,

 //NOTE: this can be considered inefficient.

 sendPublic("*arena " + (String)temp + " pilots left in the game");

An example using sprintf to align/space data, where output data will be in this approximate format.

// 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

Timer - How to use the timing function

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:

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

Using timer functions in spawn.cpp:

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
	}

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.

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:

//////// 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);
}

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.

//////// DLL "import" ////////

bool botInfo::closeto(Player *p, int x, int y, int tolerance) 
    {
	 ...
    }

In spawn.h, add your method's prototype without botInfo::, it will look like this:

//...
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.
//  ...
};

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 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:

	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

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:

_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
}

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:

 void handleCmdSetShip(enum Ship_Types ship);

In spawn.cpp add:

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

To use, just call the function with the appropriate Ship_Type from the enum in clientprot.h:

 handleCmdSetShip(SHIP_Warbird);

Random numbers

Generating a random number

To use this method, these two includes must be used:

#include "time.h"    //provides time() function.
#include "stdlib.h"  //provides srand() and rand() functions.

Use:

    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

Picking a random pilot

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

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

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:

	int begin = GetTickCount();

	// do some code here.

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

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:

#define DMG_DEALT        0
#define DMG_TAKEN        1

In spawn.cpp, initialize the values on ArenaEnter and PlayerEnter:

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

case EVENT_PlayerEntering:
{
//	...
	set_tag(p, DMG_DEALT, 0); // initialize to 0
	set_tag(p, DMG_TAKEN, 0);
	sendPrivate(p,"*watchdamage");
}

Then somewhere edit the tag values:

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

The following demonstrates how to retrieve the tag values as a command in command.cpp:

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

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

struct PlayerTag
{
	Player *p;
	char name[20];
	int index;
	int data;
};

In spawn.cpp:

	case EVENT_PlayerLeaving:
	{
	    Player *p = (Player*)event.p[0];

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

//	...

Locate in spawn.cpp and modify accordingly:

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

Using structs

In spawn.h:

class botInfo
{
	struct freqdata 
	{
		int kills, deaths;
	};
// ...
};

To make use of this structure, implement accordingly:

	freqdata freqs[100]; // 100 of those structs

Access the data in spawn.cpp using

freqs[56].kills = 1;

See CPlusPlus.com's 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:

#include <fstream>
using namespace std; // not a good practice, but works.

Note: neither example shows how to properly handle possible error-exceptions.

File stream input

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

#include "stdlib.h" // for atoi()

  ifstream file("duel.ini");
  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();

File stream output

The following code example will demonstrate how to append to a file, duelleaguestat.inc.

 ofstream file("duelleaguestat.inc", ios::app);   // app = put all data at end of file
 file << squad1<< endl;  // squad1 = char[20]
 file << " vs "<< endl;
 file << squad2<< endl;  // squad2 = char[20]
 file.close();

Similarly, you are able to write an output of a String to a file:

 // 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;

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 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:

 7=is on a killing spree! (6:0)
 10=is opening a can of booya! (9:0)

In rampageini.cpp:

#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);
	}
}

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:

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.
     }
}

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.

Example Code

Here are a few code examples that show how to do common tasks in MERVBot plugins. You should not simply copy and paste this code, but try to understand and emulate it.

Note that some of the examples require the following inline function to be defined:

inline int abs(int n)
{
	return (n < 0) -n : n;
}

Some examples also require the following structs to be defined:

struct playerstats
{
	char name[20];

	int kills, deaths;
	Uint16 points, flagpoints;
	int flagtime, cflagtime;
	int flags;
	int flagkills;

	int dmgdealt, dmgtaken;
};

struct freqdata
{
	playerstats pilots[100];

	int freqpoints;
	char freqname[20];
	int freqflagpoints;
	Uint16 freqteam;
	int freqflagtime;

	int flags;
	int kills;
	int deaths;
	int flagkills;

	int dmgdealt;
	int dmgtaken;

	int playercount;
};

No antiwarp in center of the map

Example A: No antiwarp in center of map. Warn the player and revoke the prize.

Requirements: Bot must have smod+ privilages. abs() function defined.

Let's first implement a generic function which we will need:

bool closeto(Player *p, int x, int y, int tolerance)
{
	int x_dist = abs(p->tile.x - x);
	int y_dist = abs(p->tile.y - y);
	return (x_dist < tolerance) && (y_dist < tolerance);
}

Now we declare a variable in spawn.h for the radius that defines the "center" of the map. For simplicity's sake, we will just define it in the botInfo constructor, but it can also be set via a command, INI, etc.

class botInfo
{
//	...

	// Put bot data here
	int radius;

public:
	botInfo(CALL_HANDLE given)
	{
//	...
	// Put initial values here
		radius = 35;

Now let's put the actual checking in spawn.cpp under EVENT_PlayerMove. This way, every time a player moves, the bot will check for a violation of the rule.

case EVENT_PlayerMove:
{
	Player *p = (Player*)event.p[0];

	// no anti in center
	if (p->awarp && closeto(p, 512, 512, radius))
	{
		sendPrivate(p, "*warn Antiwarp is not allowed in center.");
		sendPrivate(p, "*prize #-20");
	}
}

Just as a word of caution, players may be flooded with *prize #-20, and *warn statements under certain conditions.

Setting freq size depending on pilot count

This code shows how to change the maximum freq size depending on how many players are in ships.

Requirements: The bot must have Sysop or Arena-Owner privilages. Constructor must initialize countdown[0] to > 0 and freqchange to 0 in spawn.h.

In spawn.cpp:

case EVENT_Tick:
{
//	...
	if (countdown[0] == 0)
	{
		_listnode <Player> *parse = playerlist->head;
		int count = 0;

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

			if (p->ship != SHIP_Spectator)
				count++;

			parse = parse->next;
		}

		if ((count > 24) && (freqchange != 4))
		{
			sendPublic("?set Team:MaxPerTeam:4"); //Sysop command to modify arena config.
			freqchange = 4;
		}

		if ((count < 25) && (count > 14) && (freqchange != 3))
		{
			sendPublic("?set Team:MaxPerTeam:3"); //Sysop command to modify arena config.
			freqchange = 3;
	 	}

		String s("Max freq size ");
		s += freqchange;
		s += " (";
		s += count;
		s += " pilots in game)";
		sendPublic(s.msg);

		countdown[0] = 120; // reset timer to 120 seconds.
	 }

Tracking and announcing kill sprees

This code shows how to track the kills of a pilot and then announce when the pilot gets 10 kills in a row (without dying).

Requirements: The bot must have smod+ privilages.

Simply add the following code into spawn.cpp:

EVENT_PlayerDeath:
{
	Player *p = (Player*)event.p[0],
		 *k = (Player*)event.p[1];
	Uint16 bounty = (Uint16)(Uint32)event.p[2];
	Uint16 flags = (Uint16)event.p[3];

	set_tag(p, KILLS, 0);  // Reset KILLS to 0 on death.
	set_tag(k, KILLS, get_tag(k, KILLS) + 1);  // Increment killer's KILLS by 1.

	if (get_tag(k, KILLS) == 10)
		sendPublic("*arena " + (String)k->name + " has gotten 10 kills.");
}

Warp points

This code will warp a pilot to a coord when they are in a certain region.

Requirements: The bot must have smod+ privilages. The abs() function must be defined.

Let's first implement a generic function which we will need:

bool closeto(Player *p, int x, int y, int tolerance)
{
	return (abs(p->tile.x - x) < tolerance) && (abs(p->tile.y - y) < tolerance);
}

Then, in spawn.cpp, we just check every time a player moves to see if he has entered the warp point area. If he has, then warp him with the *warpto command to the warp destination.

case EVENT_PlayerMove: 
{
	Player *p = (Player*)event.p[0];

	if (closeto(p, 509, 509, 2)) // if pilot within 2 tiles of map coord 509,509
		sendPrivate(p, "*warpto 509 504");  // warp to coord 509,504

Of course, this is a very simple example. Real warping plugins, like TM Baw, will have a list of warp points set through an INI file. See its source for an example of this method.

Tracking flag data

This example demonstrates how to track plag data.

Requirements: Example freq/pilot structures must be defined.

Note: case EVENT_FlagDrop: {} gets called anytime theres a teamkill.

First, let's define a function to determine whether a pilot is in the structure list:

bool botInfo::GetPilot(Player *p)
{
	// first find the freq index for the pilot's freq
	for (freq = 0; freq < freqcount; freq++)
	{
		if (p->team == freqs[freq].freqteam)
			break;
	}

	// then find the pilot in the freq struct
	for (pilot = 0; pilot < freqs[freq].playercount; pilot++)
		if (strcmp(p->name,freqs[freq].pilots[pilot].name)==0)
			return true;

	return false;
}

To track flag data using above struct/functions, in spawn.cpp:

case EVENT_FlagGrab:
{
    //...

    if (GetPilot(p))  // function
    {
        freqs[freq].pilots[pilot].flags++;
        freqs[freq].flags++;

        if (freqs[freq].pilots[pilot].flags < 2) // didnt have a flag before, first flag
            freqs[freq].pilots[pilot].cflagtime = GetTickCount();  // time stamp when picked up flag
    }

    //...

To track flag data using built-in get/set tag, in spawn.cpp:

case EVENT_FlagGrab:
{
 //...

  set_tag(p, TAG_STAT_FS, get_tag(p, TAG_STAT_FS) + 1);
  set_tag(p, TAG_FLAGTIMER, GetTickCount());

 //...
}

Source: Catid's flagbot.

Get current flag times using struct format:

void botInfo::SetFlagTimes()
{
	// set current flagtime for pilots/freqs
	_listnode <Player> *parse = playerlist->head;
   
	while (parse)
	{
		Player *p = parse->item;

		if (GetPilot(p) && freqs[freq].pilots[pilot].flags > 0)
		{
			int time = (GetTickCount() - freqs[freq].pilots[pilot].cflagtime)/1000;

			if (PilotOnSquad(p))
				freqs[freq].freqflagtime += time;

			freqs[freq].pilots[pilot].flagtime += time;
			freqs[freq].pilots[pilot].cflagtime = GetTickCount();
		}

		parse = parse->next;
	}
}

A simple !spam feature

This example shows how to implement a !spam command, which allows a standard player to announce something to the zone every 60s. (In reality, the delay might need to be increased.)

First, let's declare a constant and a variable we will need in spawn.h:

#define SPAM_TIME 1	//in minutes
class botInfo
{
	//...

	// Put bot data here
	bool spamready;	//whether bot is ready to make another announcement

	//...

public:
	botInfo(CALL_HANDLE given)
	{
	//...

	// Put initial values here
	spamready = true;

Now, let's create the !spam command in commands.cpp:

case OP_Player: // Player-level commands
{    
	//...
	if (c->check("spam"))
	{
		// zone announcement "Need pilots to duel in ?go [arena] - [pilotname]"
		if (spamready == true)
		{
			char s[128];

			sprintf(s, "*zone Need pilots to duel in ?go %s - %s",
				arena,
				p->name);

			sendPublic(s);
		  
			spamready=false;
			countdown[0] = SPAM_TIME * 60; // set the timer for 60s
		}
		else if (countdown[0] < 0)
		{
		     sendPrivate(p, "Spam ability disabled.");
		}
		else
		{
			char s[128];

			sprintf(s,
				"%d minute timer between announcements. %dm:%2ds before next spam.",
				SPAM_TIME,
				countdown[0] / 60,
				countdown[0] % 60);

			sendPrivate(p, s);
		}
	}

Then, in spawn.cpp, mark spamready as true when countdown[0] hits 0:

case EVENT_Tick:
{
	//...

	if (countdown[0] == 0)
		spamready = true;
}

Implementing a simple queue for several "boxes"

This code demonstrates how to have a queue of players for dueling boxes.

In spawn.h, define a constant and declare a couple variables we'll need:

#define MAX_NEXT 8
class botInfo
{
	//...

	// Put bot data here
	Player *next[99][MAX_NEXT];
	int nextcount[99];

In spawn.cpp, implement a fuction to move up the queue when a person enters a box or simply leaves the queue:

void botInfo::MoveUp(int pos, int box_id)
{
	Player **box = next[box_id];	//define a pointer because we'll be accessing this a lot

	// decrement box's nextcount
	if (nextcount[box_id] > 0)
		nextcount[box_id]--;

	// move up the line for that box
	for (pos; pos < MAX_NEXT - 1; pos++)
		box[pos] = box[pos + 1];

	box[MAX_NEXT] = 0;
}

Reading text from a file and printing it to a player

This example demonstrates how to read text from a file line-by-line and print it to a pilot. It uses a staff text file, but the input file could be anything.

Requirements: Include <fstream.h>.

Simply implement the following code in commands.cpp:

case OP_Player:
{
	//...

	if (c->check("staff"))
	{
		ifstream file("staff.txt");
		char line[256];	//max length 255

		while (file.getline(line, 256))
			sendPrivate(p, line);

		file.close();
	}

Printing a player stats table

This example demonstrates how to print the statistics stored in the example structures at the beginning of this section to the various freqs.

Requirements: The example structures must be defined. Function sendFreqs() must be defined.

In spawn.cpp:

void botInfo::DisplayPlayers(int freqcount)
{
	// Display Match player/freq stats in this format
	// ---------------------------------------------------
	// Squad: squad_name_1          K  D TK DMG DEALT TAKEN
	// ---------------------------------------------------
	// Player_1                     0  0  0         0     0
	// Player_2                     0  0  0         0     0
	// TOTAL:                       0  0  0         0     0
	// ---------------------------------------------------
	// Squad: squad_name_2          K  D TK DMG DEALT TAKEN
	// ---------------------------------------------------
	// Player_3                     0  0  0         0     0
	// Player_4                     0  0  0         0     0
	// Player_5                     0  0  0         0     0
	// TOTAL:                       0  0  0         0     0
	// ---------------------------------------------------

	char str[255];
	freqdata *freq = freqs;	//pointer for efficiency

	while (freqcount--)
	{
		sendFreqs("---------------------------------------------------");

		sprintf(str, "Squad: %-20s K  D TK DMG DEALT TAKEN", freq->freqname);
		sendFreqs(str);

		sendFreqs("---------------------------------------------------");

		for (pilot = 0; pilot < freq->playercount; pilot++)
		{
		  sprintf(str, "%-20s %8d %2d %2d %9d %5d", //use sprintf() to space output evenly
		           freq->pilots[pilot].name,
		           freq->pilots[pilot].kills,
		           freq->pilots[pilot].deaths,
		           freq->pilots[pilot].teamkills,
		           freq->pilots[pilot].dmgdealt,
		           freq->pilots[pilot].dmgtaken
		         );
		  sendFreqs(str);
		}

		sprintf(str, "TOTAL:                     %2d %2d %2d %9d %5d",
		        freq->kills, freq->deaths,
		        freq->teamkills,
		        freq->dmgdealt,
		        freq->dmgtaken
		       );
		sendFreqs(str);

		freq++;	//increment the pointer to next on the list
	}

	sendFreqs("---------------------------------------------------");
}

Checking if any pilots are within a region

Example K: Example of checking if any pilots are within a region.

Note: User-defined function GetPilotName is missing, and needs to be implemented.See prior examples.

Note: User-defined function closeto is missing, and needs to be implemented. See prior examples.

In spawn.cpp (Note: you will also need to add the function prototype to spawn.h accordingly):

bool botInfo::FreqAInBox()
{
    // return true if teamA has a pilot in the box, otherwise false
    for (int tempplayercount = freqs[0].playercount-1; tempplayercount >= 0; tempplayercount--)
       if (GetPilotName(freqs[0].pilots[tempplayercount].name))
         if (closeto(TempPlayer, coordX, coordY, 73) && (TempPlayer->ship != SHIP_Spectator))
            return true;

    return false;
}

Functions to get a pilot's struct id info from a name or *player info

Example L: Example of functions to get a pilot's struct id info from a name or *player info.

Note: Required structures needed for this example to work. See structure examples for variable information.

Note: Remember to implement any function into the spawn.h accordingly.

Note: Using pilot names as vital comparisions should be used with caution. See Bot-Issues by CypherJF.

Note from Underlord: It is "better to implement these functions as passing values by reference instead of using global variables... [it is] just easier to not have to be declaring different int freq, int pilot all the time."

In spawn.cpp:

// return struct freq/pilot id from *player info
bool botInfo::GetPilot(Player *p)
{
    // return freq, pilot of a player p
    for (freq=freqcount-1; freq>=0; freq--)
     if (p->team == freqs[freq].freqteam)
        for (pilot = freqs[freq].playercount-1; pilot>=0; pilot--)
            if (strcmp(p->name,freqs[freq].pilots[pilot].name)==0)
               return true;

    return false;
}

// return *player as TempPlayer info from p->name info
bool botInfo::GetPilotName(char *name)
{
    // get pilot from a name, return as TempPlayer
    _listnode <Player> *parse = playerlist->head;

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

        // convert both to lowercase to compare
        char pname[20];           
        strncpy(pname,p->name,20);

        char nname[20];           
        strncpy(nname,name,20);

        tolower(pname);
        tolower(nname);

        if (strcmp(pname,nname)==0)
        {
          TempPlayer = p;
          return true;
        }
        
        parse = parse->next;
    }
    return false;
}

Creating a logfile name using date and squad names

Example M: Example of creating a logfile name using date and squad names.

Example Output: 03y01m27dBLACKDRaGON vs Integral05h08m.txt.

Format: year, month, day, squadA vs squadB, hour, minute.

Note: Assuming you define the following variables: squadA (String), squadB (String).

    // create log file name (squadA and squadB external char[20] variables)
    char u[100];
    time_t t=time(NULL);
    tm *tmp = localtime(&t);
    strftime(u,99,"%y",tmp);
    logname = u;
    logname += "y";
    strftime(u,99,"%m",tmp);
    logname += u;
    logname += "m";
    strftime(u,99,"%d",tmp);
    logname += u;
    logname += "d";
    logname += squadA;
    logname += " vs ";
    logname += squadB;
    strftime(u,99,"%I",tmp);
    logname += u;
    logname += "h";
    strftime(u,99,"%M",tmp);
    logname += u;
    logname += "m";
    logname += ".txt";

Sending messages to playing freqs or public and logging depending on status

Example N: Example of sending messages to playing freqs or public and logging depending on status.

Note: Assumes you have the following variables declared: teamA (String), teamB (String), logname (String).

Note: Remember to implement the function prototypes into spawn.h

Required include statements:

#include <fstream>
using namespace std;  // bad coding practice, but it works.

In spawn.cpp:

// teamA, teamB, logname global variables
void botInfo::sendFreqs(char *msg)
{
  char *mmsg = "*arena";
  String s = msg;
   
  if (teammsgs == false)
  {
    s.prepend("*arena ",7);
    sendPublic(s);
  }
  else
  {
    sendTeamPrivate(8025,msg);
    sendTeamPrivate(teamA,msg);
    sendTeamPrivate(teamB,msg);
  }
  if (gameon == true)
  {
    ofstream outf(logname, ios::app);
    outf << msg << endl;
    outf.close();
  }
}

Reading in all player/freqs to struct data

Example O: Example of reading in all player/freqs to struct data.

Note: see structures within structures example for freqs[] declaration.

Note: remember to add the function prototypes to spawn.h.

// to get freqs in a game where there are several freqs
void botInfo::GetFreqs()
{
    // read pilots into freq struct data from ingame and on playing freqs

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

      if (p->ship != SHIP_Spectator)
      if (closeto(p, coordX, coordY, 73))
      {
        // look for freq in struct
        bool foundfreq=false;

        freq=freqcount-1;

        while ((freq>=0) && (foundfreq==false))
        {
            if (p->team == freqs[freq].freqteam)
            {
               foundfreq=true;
               strncpy(freqs[freq].pilots[freqs[freq].playercount].name, p->name, 20);
               freqs[freq].playercount++;   
            }
            freq--;
        }

        // didnt find freq in struct so add new freq
        if (foundfreq == false)
        {
            if (manualsquads == false)
            {
               strncpy(freqs[freqcount].freqname, p->squad, 20);

               if (freqcount == 0)
                {
                   teamA = p->team;
                   strncpy(squadA, p->squad, 20);
                }
                else
                {
                   teamB = p->team;
                   strncpy(squadB, p->squad, 20);
                }
            }
            else
            {
              if (p->team == teamA)
                 strncpy(freqs[freqcount].freqname,squadA,20);
              else if (p->team == teamB)
                 strncpy(freqs[freqcount].freqname,squadB,20);
            }
           
            freqs[freqcount].freqteam = p->team;

            strncpy(freqs[freqcount].pilots[0].name, p->name, 20);
                       
            freqs[freqcount].playercount++;
            freqcount++;
        }
      }
      parse = parse->next;
    }
}

// to get freqs in a game where there are only two teams
void botInfo::GetFreqs()
{
    // read pilots into freq struct data from ingame and on playing freqs
    _listnode <Player> *parse = playerlist->head;
   
    while (parse)
    {
	    Player *p = parse->item;

		if ((p->ship != SHIP_Spectator) && ((p->team == teamA) || (p->team == teamB)))
		{
			// freq 100, team A
			// set freq
			freq = 0;

			if (p->team == teamB)
				freq = 1;

			// number of pilots on freq counted so far, starts 0
			pilot = freqs[freq].playercount;

			// pilot name
			strncpy(freqs[freq].pilots[pilot].name, p->name, 20);
			// time stamp for playing time
			freqs[freq].pilots[pilot].cplaying_time = GetTickCount();

			// slot name
			if (freqs[freq].playercount < NUMBER_PILOTS)
				strncpy(freqs[freq].slotname[pilot], p->name, 20);

			// increment freq player count
			freqs[freq].playercount++;

			// if freq not already have name, give it player squad name
			if ((manualsquads == false) && (strlen(p->squad) > 0))
				strncpy(freqs[freq].freqname, p->squad, 20);

			// set player ship
			freqs[freq].pilots[pilot].ship = p->ship + 1;
		}

        parse = parse->next;
    }
}

Finding MVP from struct data (2*kills - deaths formula)

Example P: Example of finding MVP from struct data (2*kills - deaths formula).

 int highest = -20;
 int mvp = 0;

 for (pilot = freqs[mvpteam].playercount-1; pilot >=0; pilot--)
   {
     if (((freqs[mvpteam].pilots[pilot].kills * 2) - freqs[mvpteam].pilots[pilot].deaths) > highest)
      {
        mvp = pilot;
        highest = (freqs[mvpteam].pilots[pilot].kills * 2) - freqs[mvpteam].pilots[pilot].deaths;
      }
   }

Print time stamp of event

Example Q: Print time stamp of event.

#include "time.h" // required include

Use:

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

Simple way to track player bomb/bullet damage stats

Example R: Simple way to track player bomb/bullet damage stats.

Note: see data section for how to setup set_tag.

Note: see clientprot.h for weapon information.

In spawn.cpp:

case EVENT_WatchDamage:
{
    if (PLAYING)  // if tracking stats
    {
        if ((wi.type == PROJ_PBomb) && (p->name != k->name))
        {
            set_tag(k, DMG_BOMB_DEALT, get_tag(k, DMG_BOMB_DEALT) + damage);
            set_tag(k, DMG_TOTAL_DEALT, get_tag(k, DMG_TOTAL_DEALT) + damage);
            set_tag(p, DMG_BOMB_TAKEN, get_tag(p, DMG_BOMB_TAKEN) + damage);
            set_tag(p, DMG_TOTAL_TAKEN, get_tag(p, DMG_TOTAL_TAKEN) + damage);
        }
        else if (wi.type == PROJ_BBullet)
        {
            set_tag(k, DMG_BULLET_DEALT, get_tag(k, DMG_BULLET_DEALT) + damage);
            set_tag(k, DMG_TOTAL_DEALT, get_tag(k, DMG_TOTAL_DEALT) + damage);
            set_tag(p, DMG_BULLET_TAKEN, get_tag(k, DMG_BULLET_TAKEN) + damage);
            set_tag(p, DMG_TOTAL_TAKEN, get_tag(k, DMG_TOTAL_TAKEN) + damage);
        }
    }

Simple way to print those stats

Example S: Simple way to print those stats.

case OP_Moderator:
{
   if (c->check("showstats"))
    {
       sendPublic("Showing stats:");
       
       _listnode <Player> *parse = playerlist->head;             
   
       while (parse) 
	{
	  Player *p = parse->item;
    
          if (get_tag(p, DMG_TOTAL_DEALT) > 0)
	   {
	     char str[256];
	     sprintf(str, "(%-20s Dmg Dealt: Total %0004d, Bomb %0004d, Bullet %0004d  Dmg TAKEN: Total %0004d, Bomb %0004d, Bullet %0004d)",
	     p->name,
             get_tag(p,DMG_TOTAL_DEALT),
             get_tag(p,DMG_BOMB_DEALT),
             get_tag(p,DMG_BULLET_DEALT),
	     get_tag(p,DMG_TOTAL_TAKEN),
             get_tag(p,DMG_BOMB_TAKEN),
             get_tag(p,DMG_BULLET_TAKEN)
             );

	     sendPublic(str);
	    }
	  parse = parse->next;
	}
    }
}

Make bot spectate specific coordinates

Example T: Make bot spectate specific coordinates.

// make bot spectate the coord 512,600
// possible use - capturing weapon packets in a specific region

tell(makeFollowing(false));
tell(makeFlying(true));
me->move(512 * 16, 600 * 16);
tell(makeSendPosition(true));

Difference between revisions of "MERVBot Tutorial"

Revision as of 12:18, 20 February 2005

Contents

Setting up a MERVBot (plugin)

Obtaining MERVBot

Preparing to write a plugin

Microsoft Visual c++

Run your bot dll

Player Commands - (command.cpp)

How to have commands with numerical parameters

How to have player name as input

How to have multi-parameter input

Help Menu

Event Calls

The Messaging System

Output of data in messages

Timer - How to use the timing function

Writing Functions

Function notes

Cycling through players

Random numbers

Generating a random number

Picking a random pilot

Tracking time not using countdown[n]

Storing data for pilots

Built-in get/setTag method

Modified permanent get/setTag method

Using structs

Input/Output to files

File stream input

File stream output

Input with GetPrivateProfileString

Player data

Bot built in functions

Example Code

No antiwarp in center of the map

Setting freq size depending on pilot count

Tracking and announcing kill sprees

Warp points

Tracking flag data

A simple !spam feature

Implementing a simple queue for several "boxes"

Reading text from a file and printing it to a player

Printing a player stats table

Checking if any pilots are within a region

Functions to get a pilot's struct id info from a name or *player info

Creating a logfile name using date and squad names

Sending messages to playing freqs or public and logging depending on status

Reading in all player/freqs to struct data

Finding MVP from struct data (2*kills - deaths formula)

Print time stamp of event

Simple way to track player bomb/bullet damage stats

Simple way to print those stats

Make bot spectate specific coordinates

Navigation menu

Search