#2 Basic plugin

Following on from tutorial 1 we’re going to start by looking at the Game Plugin. For this we’ll need a couple of pieces of software. The first we need is a compiler to build the plugin itself, as I’m demonstrating this on Windows, we’ll stick to Visual C++. You can download Microsoft Visual C++ 2010 Express for free and use that. Visual Studio has many nice features such as syntax highlighting, compiler, debugger etc.

Maratis is a nice, cross platform engine. If we just develop using Visual Studio, that cuts off the possibility to use a Maratis Game plugin on a Linux game, or a Mac OSX game, right?

Wrong. For this reason, we won’t be making a Visual Studio solution directly, we’re going to use another program called premake4 to manage a meta-project. This will allow us to make one project file, run premake4 and have it generate the relevant platform specific projects we need. For this example, I’m going to suggest you download the 4.4 beta as I’m going to be using a new feature (vpaths) to make our Visual Studio solution look a bit nicer. When you have premake4, the easiest thing is to put it somewhere in your OS’ search path. For me, I suggest making a tools directory within C:\dev (if you’re following my layout) and then follow any guide you like as to how to add C:\dev\tools\ to your PATH environment variable. This means that, when you want to run premake4, you just need ‘premake4’ rather than ‘C:\dev\tools\premake4’. Just a handy way to keep tools you want easily usable.

While you’re changing your PATH variable, I also suggest adding a new User environment variable to keep track of where Maratis is installed. I have it at C:\Maratis\ and I have made a variable called MSDKDIR which points to that. The reason for this is that you can then, later, update Maratis to being in a different location, or give your projects to a friend who has it installed somewhere else, and there will only be one central place that you need to set up where it’s pointing to. I’m sure this will make more sense when we move onto the premake4.lua file.

Which brings us to actually starting the project work. Within C:\dev\tutorial we now want somewhere to store our source code, so let’s make a folder called source. Within that, create a new file called premake4.lua. This will be our meta project file. I’ve provided my framework one. It’s by no means complete, but it’s a good start and will do what we want.

Just smile and nod.
A sample of my premake4 file

It’s a bit much to take in all at once, but I’ll try and explain it a bit.
The first thing that we need is a solution. This is the overarching project. We can have several projects within it, and several build configurations within those. It also doesn’t really matter what this is called. The way that premake4 files are formatted is a little weird. Everything that we set is relevant to the current scope, but the only way of changing the scope is setting a new one. The indentation doesn’t matter at all. So that means that, we have language “C++ in the solution, it applies to the whole solution, if we moved it under project “Game” it would only apply to the game plugin project. A lot of the settings could be moved into the solution, it’s just personal preference where you put it.

So, what else do we have. If you look at libdirs and includedirs, you can see why I wanted the environment variable. It makes it easier to set all of these in a nice way. The same can be said about files. The **.cpp and **.h will add all files recursively of the given directory to the project. I’ve added Maratis SDK headers as it’s nice to be able to access them from within the project.

Next, we have the vpaths setup. This creates filters within Visual Studio, which is a lot nicer than just a huge dump of all the files (especially now we’ve added the Maratis SDK headers). The way this works is that you specify a tag [“Game/*”] and then the paths to match for it. The files already have to be loadedfor this to work.

links is quite simple, it tells Visual Studio that you will be linking to MCore and MEngine libraries (which we’ve told it where they live in the libdirs section) so we can use the functions from Maratis SDK.

I’ve made it output to “../” which should put the final build into the project directory (rather than the source directory) so Maratis can use it directly, without having to manually move it.

The two configurations are more or less useless at this stage as there’s no easy way to debug a Maratis plugin like this, but I will add that in a later tutorial.

One final note which I haven’t mentioned yet. The project name should be “Game” as Maratis expects “Game.dll”. You can get around this by changing some of the premake4 settings. Also, technically I should have added targetprefix “” so it will make Game.so on Linux rather than libGame.so… but to be honest, I forgot.

Now, to add some files, rather than reinventing the wheel, I’d suggest downloading the files from Anael’s tutorial and putting the .cpp and .h files into our source directory. Then open up a command window by holding shift and right click on the source directory. You should see “Open command window here”. Then type:

premake4 vs2010

running premake4
Running... but from what?

That should generate the Visual Studio solution, among the files will be a .sln file. Open this with Visual Studio and you should be greated by something like this.

Visual Studio
So there we have it... our project.

As you can see, there are “filters” already made for MCore, MEngine and Game. This is thanks to the vpaths stuff in the premake4.lua file. I’ve obviously renamed Anael’s files here, but I was going to take you through what they do, writing from scratch. For now I’ll just leave it at that. If you press Ctrl+Shift+B it will build the project with the current configuration (debug by default) and write the Game.dll to the project directory. We’ve not assigned the behavior to any object yet, I’m going to assume that you can read the original tutorial for now in order to do that. I’ll cover that when I get around to writing the behavior myself.

If you’ve done everything right, when you hit pacman at the top right, you should see the cube spinning. Congratulations.

Next time I’ll add some more functionality to our plugin and add it to our scene properly.

<-Previous Next->


Leave a Reply

Your email address will not be published. Required fields are marked *

Diary of a Slacker