Jump to content

GMF2, Plugins, and Modding



I wanted to get a working example of the plugin system together. One thing led to another, and...well, this is going to be a very different blog.


The first thing I had to do is figure out a way for plugins to communicate with the main program. I considered using a structure they both share in memory, but those always inevitably get out of sync when either the structure changes or there is a small difference between the compilers used for the program and DLL. This scared me so I went with a standard file format to feed the data from the plugin to the main program.

GLTF is a pretty good format but has some problems that makes me look for something else to use in our model loader plugins.

  • It's text-based and loads slower.
  • It's extremely complicated. There are 3-4 different versions of the file format and many many options to split it across multiple files, binary, text, or binary-to-text encoding.
  • It's meant for web content, not PC games.
  • Tons of missing functionality is added through a weird plugin system. For example, DDS is supported through a plugin, but a backup PNG has to be included in case the loaded doesn't support the extension.

The GMF file format was used in Leadwerks. It's a custom fast-loading chunk-based binary file format. GMF2 is a simpler flat binary format updated with some extra features:

  • Vertices are stored in a single array ready to load straight into GPU memory.
  • Vertex displacement is supported.
  • Compressed bitangents.
  • Quad and line meshes are supported.
  • LOD
  • Materials and textures can be packed into the format or loaded from external files.
  • PBR and Blinn-Phong materials
  • Mesh bounding boxes are supported so they don't have to be calculated at load time. This means the vertex array never has to be iterated through, making large meshes load faster.

I am not sure yet if GMF2 will be used for actual files or if it is just going to be an internal data format for plugins to use. GLTF will continue to be supported, but the format is too much of a mess to use for plugin data.

Here's a cool five-minute logo:


The format looks something like this:

char[4] ID "GMF2"
int version 200
int root //ID of the root entity
int texture_count //number of textures
int textures_pos //file position for texture array
int materials_count //number of materials
int materials_pos //file position for materials
int nodes_count //number of nodes
int nodes_pos //file position for nodes

As you can see, it is really easy to read and really easy to write. There's enough complexity in this already. I'm not bored. I don't need to introduce unnecessary complexity into the design just so I can show off. There are real problems that need to be solved and making a "tricky" file format is not one of them.

In Leadwerks 2, we had a bit of code called the "GMF SDK". This was written in BlitzMax, and allowed construction of a GMF file with easy commands. I've created new C++ code to create GMF2 files:

//Create the file
GMFFile* file = new GMFFile;

//Create a model
node = new GMFNode(file, GMF_TYPE_MODEL);

//Add an LOD level
GMFLOD* lod = node->AddLOD();

//Add a mesh
GMFMesh* mesh = lod->AddMesh(3); //triangle mesh

//Add a vertex
mesh->AddVertex(0,0,0, 0,0,1, 0,0, 0,0, 255,255,255,255);
mesh->AddVertex(0,0,1, 0,0,1, 0,0, 0,0, 255,255,255,255);
mesh->AddVertex(0,1,1, 0,0,1, 0,0, 0,0, 255,255,255,255);

//Add a triangle

Once your GMFFile is constructed you can save it into memory with one command. The Turbo Plugin SDK is a little more low-level than the engine, so it includes a MemWriter class to help with this, since the engine Stream class is not present.

As a test I am writing a Quake 3 MD3 import plugin and will provide the project and source as an example of how to use the Turbo Plugin SDK.



The ZIP virtual file system from Leadwerks is being expanded and formalized. You can load a Package object to add new virtual files to your project. These will also be loadable from the editor, so you can add new packages to a project, and the files will appear in the asset browser and file dialogs. (Package files are read-only.) Plugins will allow packages to be loaded from file formats besides ZIP, like Quake WADs or Half-Life GCF files. Notice we keep all our loaded items in variables or arrays because we don't want them to get auto-deleted.

//Load Quake 3 plugins
auto pk3reader = LoadPlugin("Plugins/PK3.dll");
auto md3loader = LoadPlugin("Plugins/MD3.dll");
auto bsploader = LoadPlugin("Plugins/Q3BSP.dll");

Next we load the game package files straight from the Quake game directory. This is just like the package system from Leadwerks.

//Load Quake 3 game packages
std::wstring q3apath = L"C:/Program Files (x86)/Steam/steamapps/common/Quake 3 Arena/baseq3";
auto dir = LoadDir(q3apath);
std::vector<shared_ptr<Package> > q3apackages;
for (auto file : dir)
	if (Lower(ExtractExt(file)) == L"pk3")
		auto pak = LoadPackage(q3apath + L"/" + file);
		if (pak) q3apackages.push_back(pak);

Now we can start loading content directly from the game.

//Load up some game content from Quake!
auto head = LoadModel(world, "models/players/bitterman/head.md3");
auto upper = LoadModel(world, "models/players/bitterman/upper.md3");
auto lower = LoadModel(world, "models/players/bitterman/lower.md3");
auto scene = LoadScene(world, "maps/q3ctf2.bsp");


I have a soft spot for modding because that is what originally got me into computer programming and game development. I was part of the team that made "Checkered Flag: Gold Cup" which was a spin-off on the wonderful Quake Rally mod:

I expect in the new editor you will be able to browse through game files just as if they were uncompressed in your project file, so the new editor can act as a modding tool, for those who are so inclined. It's going to be interesting to see what people do with this. We can configure the new editor to run a launch script that handles map compiling and then launches the game. All the pieces are there to make the new editor a tool for modding games, like Discreet's old Gmax experiment.


I am going to provide official support for Quake 3 because all the file formats are pretty easy to load, and because gmax can export to MD3 and it would be fun to load Gmax models. Other games can be supported by adding plugins.

So here are some of the things the new plugin system will allow:

  • Load content directly from other games and use it in your own game. I don't recommend using copyrighted game assets for commercial projects, but you could make a "mod" that replaces the engine and requires the player to own the original game.
  • You could probably safely use content from any Valve games and release a commercial game on Steam.
  • Use the editor as a tool to make Quake or other maps.
  • Add plugin support for new file formats.

This might all be a silly waste of time, but it's a way to get the plugin system working, and if we can make something flexible enough to build Quake maps, well that is a good test of the robustness of the system.


  • Like 4


Recommended Comments

25 minutes ago, aiaf said:

We would be able to load gltf models? 

GLTF is already available, right now. It will continue to be supported.

Link to comment

I shared this in the Quake modding discord server since you mentioned quake 3 mapping a few times. Hopefully it drives some more interest into turbo :)

  • Like 1
  • Haha 1
Link to comment
40 minutes ago, Mr_SquarePeg said:

I shared this in the Quake modding discord server since you mentioned quake 3 mapping a few times. Hopefully it drives some more interest into turbo :)

Quake is what got me into computer programming in the first place, and now I work with NASA. I am very fond of that whole scene.

Link to comment

Notice there is actually no one talking about a game-ready model format, because I guess that is boring or something. OpenGEX, Collada, and FBX are "exchange formats" for moving data between modeling programs, and I guess this USD format is too. GLTF is a scene (not model) format for web graphics, which is why it uses JPG and PNG textures. No one even considers making something for normal 3D games.

What do you think the advantage of this USD format is? GLTF is nice because at least you can load all the Sketchfab content up easily.

Link to comment

USD is used to transfer, well, anything you can do in a 3D modeling program. So, it doesn't matter if you use 3DS Max, Maya, or even Blender. If you can import/export out USD, you can bring the entire scene (models, materials, animations (including bones, etc.), lights ... everything, in one shot (if you want). Unity already supports USD. Unreal is getting ready to (if they don't already). And most 3D modeling programs do, too. Apparently it has advantages over GLTF. 

USD Primer

Link to comment

What is USD?

Pipelines capable of producing computer graphics films and games typically generate, store, and transmit great quantities of 3D data, which we call "scene description".  Each of many cooperating applications in the pipeline  (modeling, shading, animation, lighting, fx, rendering) typically has its own special form of scene description tailored to the specific needs and workflows of the application, and neither readable nor editable by any other application.   Universal Scene Description (USD) is the first publicly available software that addresses the need to robustly and scalably interchange and augment arbitrary 3D scenes that may be composed from many elemental assets.  

From: https://graphics.pixar.com/usd/docs/index.html

Link to comment

@Monkey Frog Studio You've convinced me to make GMF2 our default file format. If another standard is coming along that replaced GLTF, yet still does not give us fast-loading models, we need to invent our own. We will still provide direct loading and optional conversion of GLTF files, and maybe also this new format, but some of these huge CAD files we are working with would take ages to load if we have to sort through all the data. I think we will be able to show some loading speed comparisons between GLTF and GMF2, and the difference will be massive.

I am going to introduce the file format at GDC 2020, along with tools for working with it.

Link to comment



You've convinced me to make GMF2 our default file format.

Well, firstly, I didn't ask for it to be the DEFAULT file format, but recommended it as a format that could be supported by Leadwerks. And that was at least a year ago, too. Time moves on. Things progress. And as you worked with GLTF you found things you both liked and did not like. Due to the things you didn't like about GLTF (some of them mentioned in your post here), I then recommended USD as a possibility. Some are saying there are advantages USD has over GLTF. So, is there really any harm in looking at it? If you find that GLTF is great for what you want, then good. You've already done the work (or most of it), right? If you find USD is a viable option and provides benefits, then wouldn't you be happy to know about it?


If another standard is coming along that replaced GLTF, yet still does not give us fast-loading models, we need to invent our own.

And when you do that, you then need a way for artists to get their content into your engine. That means exporting from their 3D package of choice into your custom file format. And that means someone creating and maintaining these export plugins for the various packages, such as Maya, 3DS Max, C4D, MODO, and Blender. 


We will still provide direct loading and optional conversion of GLTF files, and maybe also this new format,

Glad to hear it.


but some of these huge CAD files we are working with would take ages to load if we have to sort through all the data.

That's a standard issue with CAD files in a non-CAD application.

Link to comment

Sorry, I just meant that in a matter-of-fact way.

The way the plugin system is set up, the data is always run through the GMF2 data format. So we can have a plugin that loads a GLTF or USD or other files and gives it to the engine in memory as a GMF2 file, or we can make it save the GMF2 for faster loading. Bottom line is if we have an import plugin for any format, we also automatically have a converter. Plus the file format is so simple I think we will see more community-made exporters than we did with GMF1, which had a "tricky" chunk structure.

Plus, we have the GMF2 SDK, which makes it easy to just create some data structures and then the code saves a file for you. So GMF2 and its SDK is a big funnel we can easily pipe all kinds of data into and either save it or load it from memory.

I think loading speed is a significant consideration we should be paying attention to. This seems like a really basic consideration we should be designing file formats around, for all games. I guess I need to get some definite numbers on what mesh data load times are like under realistic use cases.

Link to comment

 That all sounds pretty awesome, actually. Thanks for taking the time to fill me in. Selfishly, all I care about, as an artist, is getting my assets into the engine as easily as possible. The less hoops I have to jump through, the better. :)

  • Haha 1
Link to comment
Add a comment...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Create New...