Plugin API

From Mineserver Wiki

Revision as of 20:21, 26 February 2011 by Delirium (Talk | contribs)
Jump to: navigation, search

Mineserver uses a C-plugin API which is described in this page.

Contents

Creating a plugin

You will need to include plugin_api.h to your project.

...write some more stuff here...

Example plugin structure:

 #include "plugin_api.h"
 #define PLUGIN_VERSION 1.0
 std::string dtos( double n )
 {
   std::ostringstream result;
   result << n;
   return result.str();
 }
 mineserver_pointer_struct* mineserver;
 std::string pluginName = "command";
 PLUGIN_API_EXPORT void (plugin_name)_init(mineserver_pointer_struct* mineserver_temp)
 {
   mineserver = mineserver_temp;
   if (mineserver->plugin.getPluginVersion(pluginName.c_str()) > 0)
   {
     std::string msg="command is already loaded v." +dtos(mineserver->plugin.getPluginVersion(pluginName.c_str()));
     mineserver->screen.log(msg.c_str(),msg.size());
     return;
   }
   std::string msg="Loaded "+pluginName+"!";
   mineserver->screen.log(msg.c_str());
   mineserver->plugin.setPluginVersion(pluginName.c_str(), PLUGIN_COMMAND_VERSION);
   mineserver->plugin.addCallback("PlayerChatPre", (void *)SOMEFUNCTIONNAME);
   mineserver->plugin.addCallback("BlockPlacePre", (void *)SOMEFUNCTIONNAME2);
 }
 PLUGIN_API_EXPORT void (plugin_name)_shutdown(void)
 {
   if (mineserver->plugin.getPluginVersion(pluginName.c_str()) <= 0)
   {
     mineserver->screen.log("command is not loaded!"));
     return;
   }
 }

Available functions

Mineserver

Chat

Function Parameter name Parameter type Parameter info
sendmsgTo user const char* Username in null Terminated char array
msg const char* Message in null terminated char array
Return value bool, telling it the user was found
Sends a message to specified user


Function Parameter name Parameter type Parameter info
sendmsg msg const char* Message in null terminated char array
Return value bool, telling it the user was found
Sends a message to all players, except they are in DND mode


Function Parameter name Parameter type Parameter info
sendUserList user const char* User in null terminated char array
Return value bool, telling it the user was found
Sends the playerlist to user

Screen

Function Parameter name Parameter type Parameter info
log msg const char* Message in null terminated char array
Return value void
Prints message to server window

Map

Function Parameter name Parameter type Parameter info
createPickupSpawn x int x-coordinate
y int y-coordinate
z int z-coordinate
conut int How many to spawn(1-64)
health int item health. 0 is max health, max value depends on the item
user const char* Username
Return value void
Spawns an item at (x,y,z) with type,count and health specified. If "user" is set, he will not be able to pick up the item right away to make it possible to throw stuff away.


Function Parameter name Parameter type Parameter info
setTime timeValue int value between 0 and 2400
Return value bool
Sets server time to timeValue
Function Parameter name Parameter type Parameter info
getSpawn x int* x-coordinate
y int* y-coordinate
z int* z-coordinate
Return value void
Gets server spawn position
Function Parameter name Parameter type Parameter info
getBlock x int x-coordinate
y int y-coordinate
z int z-coordinate
type unsigned char* block type
meta unsigned char* block metadata
Return value bool
Get block type and metadata (absolute block coordinates) in first world (id 0)
Function Parameter name Parameter type Parameter info
getBlockW x int x-coordinate
y int y-coordinate
z int z-coordinate
w int World ID
type unsigned char* block type
meta unsigned char* block metadata
Return value bool
Gets block type and metadata (absolute block coordinates)
Function Parameter name Parameter type Parameter info
setBlock x int x-coordinate
y int y-coordinate
z int z-coordinate
type unsigned char block type
meta unsigned char block metadata
Return value bool
Set block type and metadata (absolute block coordinates)
Function Parameter name Parameter type Parameter info
setBlockW x int x-coordinate
y int y-coordinate
z int z-coordinate
w int World ID
type unsigned char* block type
meta unsigned char* block metadata
Return value bool
Sets block type and metadata (absolute block coordinates)
Function Parameter name Parameter type Parameter info
setSpawn x int x-coordinate
y int y-coordinate
z int z-coordinate
Return value bool
Set spawn to x, y, z (absolute coordinates)


Function Parameter name Parameter type Parameter info
saveWholeMap void
Return value void
Saves the whole map to disk


Function Parameter name Parameter type Parameter info
getMapData_block x int x-coordinate
z int z-coordinate
Return value unsigned char*


Function Parameter name Parameter type Parameter info
getMapData_meta x int x-coordinate
z int z-coordinate
Return value unsigned char*


Function Parameter name Parameter type Parameter info
getMapData_skylight x int x-coordinate
z int z-coordinate
Return value unsigned char*


Function Parameter name Parameter type Parameter info
getMapData_blocklight x int x-coordinate
z int z-coordinate
Return value unsigned char*

User Functions

Function Parameter name Parameter type Parameter info
toggleDND user const char* Username in null terminated char array
Return value bool, indicates if user was found
Toggles the DND (Do not Disturb)-Mode of a user
Function Parameter name Parameter type Parameter info
getPosition user const char* Username in null terminated char array
x double* x-coordinate
y double* y-coordinate
z double* z-coordinate
yaw float* yaw-Value
pitch float* pitch-Value
*stance double stance-Value
Return value bool, true if user has been found
Finds a player and stores its info in the referenced variables
Function Parameter name Parameter type Parameter info
getPosition user const char* Username in null terminated char array
x double* x-coordinate
y double* y-coordinate
z double* z-coordinate
w int* World ID
yaw float* yaw-Value
pitch float* pitch-Value
*stance double stance-Value
Return value bool, true if user has been found
Finds a player and stores its info in the referenced variables

Available callbacks

Name Parameter name Parameter type Parameter info
Timer200 no params
Return value bool, isn't used
200ms timer callback
Name Parameter name Parameter type Parameter info
Timer1000 no params
Return value bool, isn't used
1000ms (1s) timer callback
Name Parameter name Parameter type Parameter info
Timer10000 no params
Return value bool, isn't used
10s timer callback
Name Parameter name Parameter type Parameter info
PlayerChatPre user const char* Username in null terminated char array
timestamp size_t time of the message
msg const char* Message in null terminated char array
Return value bool
called on chat message processing, returning false will terminate the callback.
Name Parameter name Parameter type Parameter info
PlayerChatCommand user const char* Username in null terminated char array
command const char* command
argc int argument count
arguments const char** list of arguments
Return value bool
called when chat command is used
Name Parameter name Parameter type Parameter info
BlockPlacePre user const char* Username in char array
x int32_t x-coord
y int8_t y-coord
z int32_t z-coord
block int16_t block type
direction int8_t placement direction
Return value bool
called on block placement, returning false will prevent block placement and terminate callback.
Name Parameter name Parameter type Parameter info
BlockBreakPre user const char* Username in char array
x int x-coord
y int y-coord
z int z-coord
Return value bool
called on block break, returning false will prevent block breaking and terminate callback.


ToDo:

   setHook("PlayerLoginPre", new Hook2<bool,const char*,char***>);
   setHook("PlayerLoginPost", new Hook1<bool,const char*>);
   setHook("PlayerNickPost", new Hook2<bool,const char*,const char*>);
   setHook("PlayerKickPost", new Hook2<bool,const char*,const char*>);
   setHook("PlayerQuitPost", new Hook1<bool,const char*>);
   setHook("PlayerChatPost", new Hook3<bool,const char*,time_t,const char*>);
   setHook("PlayerArmSwing", new Hook1<bool,const char*>);
   setHook("PlayerDamagePre", new Hook3<bool,const char*,const char*,int>);
   setHook("PlayerDamagePost", new Hook3<bool,const char*,const char*,int>);
   setHook("PlayerDisconnect", new Hook3<bool,const char*,uint32,uint16>);
   setHook("PlayerDiggingStarted", new Hook4<bool,const char*,sint32,sint8,sint32>);
   setHook("PlayerDigging", new Hook4<bool,const char*,sint32,sint8,sint32>);
   setHook("PlayerDiggingStopped", new Hook4<bool,const char*,sint32,sint8,sint32>);
   setHook("BlockBreakPre", new Hook4<bool,const char*,sint32,sint8,sint32>);
   setHook("BlockBreakPost", new Hook4<bool,const char*,sint32,sint8,sint32>);
   setHook("BlockNeighbourBreak", new Hook7<bool,const char*,sint32,sint8,sint32,sint32,sint8,sint32>);
   setHook("BlockPlacePre", new Hook5<bool,const char*,sint32,sint8,sint32,sint16>);
   setHook("BlockPlacePost", new Hook5<bool,const char*,sint32,sint8,sint32,sint16>);
   setHook("BlockNeighbourPlace", new Hook7<bool,const char*,sint32,sint8,sint32,sint32,sint8,sint32>);
   setHook("BlockReplacePost", new Hook6<bool,const char*,sint32,sint8,sint32,sint16,sint16>);
   setHook("BlockNeighbourReplace", new Hook9<bool,const char*,sint32,sint8,sint32,sint32,sint8,sint32,sint16,sint16>);