Well as for beta testing it probably won't be for a while yet. Yes, the mapper can load files (including those from a VOL) and it can place tiles on the map, but that's purely all it can do. (It can't save maps yet. It can't load standard BMP tilesets yet, only the sierra format. It doesn't have undo, etc)
So I want to make it a little bit more complete before I release it as even an 'alpha'.
As for plugins, I'm pretty sure about how these will work (no API docs or headers yet, sorry since I haven't gotten there yet).
The plugins will use a C interface (as opposed to C++) since this is much more compatible. (If I used a C++ interface you would be locked into using Microsoft C++ and nothing else). On the other hand, C interface functions can be called from many languages so you could use your favorite programming language to develop them.
As for the functions of the plugins, I can see support for at least two types of plugins. The first, simpler, type is one that adds a menu item or toolbar button. When clicked the plugin's code is called and allowed to manipulate the open file.
The second type would be a plugin that creates a new tool that can be loaded on the left side of the screen (like the tile picker). This one will be a bit more complex to write since it will be intercepting things such as drawing and mouse events on the map window, and would need to supply its own window procedure (so it knows when the user clicks on it / resizes it / etc). It will also have to handle loading and saving of custom data if it modifies things that aren't built into the map format already (e.g. units or some other metadata).
The plugins will be able to access data like the map data itself, the drawing calls to paint the map and the tool window, so on -- so they won't be crippled compared to the internal classes (Well, with a few exceptions -- for example most of the interface to the global application object won't be accessible. A plugin would never need access to this code and it would introduce application instability / bugs / memory leaks if the plugin called this code).
As for the API itself, I can give you a sample although it is by no means complete. (Read: the code I'm about to write isn't guaranteed to work when I do actually release a plugin SDK).
C++ classes inside the program will probably be represented as opaque pointers or handles to the real class. Functions will allow you to manipulate the classes thru the pointers.
My code will represent a simple menu plugin, nothing special yet. (Since I don't even know how it's going to work yet, I haven't written code for plugins).
// called when the plugin is loaded
bool __stdcall plugin_init()
{
// register a menu item in the mapper.
// obtain a handle to the application object.
MHApp *pApp = Mapper_GetAppObject();
// register the menu so we can get called back when the user activates it.
MApp_RegisterMenuHandler(pApp, "Test Plugin", plugin_testmenu);
// destroy the app handle.
Mapper_DeleteHandle(pApp);
return true; // init succeeded
}
// called when the plugin is supposed to clean up
void __stdcall plugin_cleanup()
{
// do nothing. I'll make it easy on you guys and not require you to unregister the menu items or do other annoying things most plugin toolkits force you to do. I'm sure I can keep track of all that stuff within the app and unregister them myself.
}
// our custom menu handler
bool __stdcall plugin_testmenu(MHMapWindow *curMap)
{
// let's set (20,20) on the map to the blue tile (index 0).
// first we need to obtain the map file object from the window object.
MHMapFile *pMapFile = MMapWindow_GetMap(curMap);
// now we can set the tile. first we have to get the tile object, change the field, and then set it back.
MapTile t = MMapFile_GetTile(pMapFile, 20, 20);
t.tileIndex = 0;
MMapFile_SetTile(pMapFile, 20, 20, t);
// done, destroy the handle we created
Mapper_DeleteHandle(pMapFile);
// no need to destroy the map window instance passed as a parameter, the mapper will take care of that.
return true; // success, keep the plugin loaded
}
And that's about it. In fact, I might make the destruction of the handles unnecessary. (The handle will be nothing more than a pointer to the internal class). Thus the pointer can be thrown away so long as it doesn't point to newly allocated data. (which it won't if you're referencing the already-existing map class and such).
Sound good?