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.

Share this comment

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

Share this comment

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.

Share this comment

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.

Share this comment

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

Share this comment

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

Share this comment

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.

Share this comment

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.

Share this comment

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.

Share this comment

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

Share this comment

Link to comment

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

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.

  • Blog Entries

    • By Josh in Josh's Dev Blog 0
      Leadwerks 4 supports compressed and encrypted game files in ZIP format, but there are many different custom package formats different games use. The plugin system in Leadwerks 5 allows us to create importers for these different package formats so we can access content directly from commercial games you have installed on your computer. The example below shows how to load a VTF texture from the game Half-Life 2 directly from the game's install files.
      First we need to load some plugins to deal with these weird file formats.
      --Load VPK package loader plugin local vpkloader = LoadPlugin("Plugins/VPK.dll") --Load VTF texture loader plugin local vtfloader = LoadPlugin("Plugins/VTF.dll") Next we will load a single VPK package directly from the Half-Life 2 install directory. If you have Steam installed somewhere other than the default path you can change the value of the STEAM_PATH variable to load the package from somewhere else.
      --Steam installation path local STEAM_PATH = "C:/Program Files (x86)/Steam" --Load package (Half-Life 2 must be installed) local pkg = LoadPackage(STEAM_PATH.."/steamapps/common/Half-Life 2/hl2/hl2_textures_dir.vpk") Now we can load content directly from the Half-Life 2 game files. Although the file specified below does not actually exist in the game folder, it will be loaded as if it was because of the VPK package we previously loaded.
      --Load texture local tex = LoadTexture("materials/building_template/buildingset040a.vtf") Here is the result when I run the program:

      Now if you wanted to load all the HL2 data files when your game starts, that is easy to do too. If you place this script in the "Scripts/Start" folder all the content will be automatically made available:
      local STEAM_PATH = "C:/Program Files (x86)/Steam/" local HL2_PATH = STEAM_PATH.."steamapps/common/Half-Life 2/hl2/" local dir = LoadDir(HL2_PATH) local k,v LoadedPackages = {} for k,v in ipairs(dir) do local ext = Lower(ExtractExt(v)) if ext == "vpk" then local pkg = LoadPackage(v) if pkg ~= nil then table.insert(LoadedPackages, pkg) end end end What is this good for? You can browse and view all the content in your installed games and use some assets as placeholders. Valve is pretty lenient with their IP so if your game is only published on Steam, you could probably use all the Source games textures and models. You could make a mod that replaces the original game engine but requires the game to be installed to run. It would also not be too hard to integrate these features into the new editor so that it can be used as a modding tool for different games and allow you to create new game levels.
      You can get the source for this and other plugins on Github.
    • By Josh in Josh's Dev Blog 2
      I've restructured the plugin SDK for our new engine and created a new repository on Github here:
      The GMF2 format will only be used as an internal data transfer protocol for model loader plugins. Our main supported file format will be GLTF.
      As of now, the plugin system can be used to write texture loaders for different file formats, model loaders, or to modify behavior of particles in the new particle system. The FreeImage texture loader has been moved out of the core engine and into a plugin so you no longer have to include the FreeImage DLL unless you want to use it. The main supported texture format will be DDS, but the FreeImage plugin supports many common image file formats.
    • By Admin in Leadwerks Company Blog 0
      The GMF2 file format provides the fastest possible load times for 3D models. A preliminary specification and SDK for loading and saving files in the GMF2 file format is now available on GitHub here:
      A Quake 3 MD3 model loader is included as an example.
  • Create New...