GameMaker: GMMOD/D3D file format explained


A sample model from GameMaker Model Viewer and its raw data

This is a blog post about the structure of GameMaker's (now-legacy) 3d model format.

Description

GMMOD/D3D (no formal extension) is a 3d model file format used by GameMaker versions starting with Game Maker 6 and up until GameMaker: Studio (deprecated in GMS2 together with the rest of d3d_ functions).

In a slight contrast with how model formats usually work, D3D model format stores not vertices and triangles, but functions that were called to populate the model.

This allows a model to contain mixed geometry types (e.g. both lines and triangles), and to contain shapes as a primitive unit.

In compatible versions, they can be saved using d3d_model_save and loaded using d3d_model_load.

Structure

The file format is text-based.
Empty lines are skipped.
Unusual line endings (like CR-CR-LF) are allowed.

The structure is as following:

version number (always 100)
number of entries that follow
...entries

Each entry consists of an instruction ID and the arguments for it.

d3d_model_save always pad arguments to maximum argument count (10) with zeroes, though d3d_model_load loads models without unused arguments just fine.

d3d_model_save uses 4..7-digit precision for floating-point arguments, but you can use both less or more digits if necessary.

The following are the supported instructions, equivalent functions, and their arguments:

ID Function
0 d3d_model_primitive_begin(m, kind)
1 d3d_model_primitive_end(m, kind)
2 d3d_model_vertex(m, x, y, z)
3 d3d_model_vertex_color(m, x, y, z, color, alpha)
4 d3d_model_vertex_texture(m, x, y, z, xtex, ytex)
5 d3d_model_vertex_texture_color(m, x, y, z, xtex, ytex, color, alpha)
6 d3d_model_vertex_normal(m, x, y, z, nx, ny, nz)
7 d3d_model_vertex_normal_color(m, x, y, z, nx, ny, nz, color, alpha)
8 d3d_model_vertex_normal_texture(m, x, y, z, nx, ny, nz, xtex, ytex)
9 d3d_model_vertex_normal_texture_color(m, x, y, z, nx, ny, nz, xtex, ytex, color, alpha)
10 d3d_model_block(m, x1, y1, z1, x2, y2, z2, hrepeat, vrepeat)
11 d3d_model_cylinder(m, x1, y1, z1, x2, y2, z2, hrepeat, vrepeat, closed, steps)
12 d3d_model_cone(m, x1, y1, z1, x2, y2, z2, hrepeat, vrepeat, closed, steps)
13 d3d_model_ellipsoid(m, x1, y1, z1, x2, y2, z2, hrepeat, vrepeat, steps)
14 d3d_model_wall(m, x1, y1, z1, x2, y2, z2, hrepeat, vrepeat)
15 d3d_model_floor(m, x1, y1, z1, x2, y2, z2, hrepeat, vrepeat)

x/y/z are fairly abstract coordinates - it is up to the game to decide unit scale.

nx/ny/nz are the normal vector for a point. The length is usually 1.

xtex/ytex are texture coordinates, (0,0) being top-left and (1,1) being bottom-right.

color is a 24-bit BGR color.

alpha is in 0..1 range.

hrepeat/vrepeat indicate how many times the texture should repeat on a primitive.
For blocks, it repeats HxV on top/bottom and HxV for each side, which leads people to use walls+floors instead for non-cubes to have finer control.

closed for cylinder and cone indicate whether whether they should have lid(s).

steps is the number of polygons per quadrant for shapes that are circular.

The kind in d3d_model_primitive_begin can be as following:

ID Name Description
1 pr_pointlist Each vertex is drawn as a point.
2 pr_linelist Pairs of vertices to be connected with lines
(1,2,3,4 ➜ 1-2, 3-4)
3 pr_linestrip Each vertex is connected to a preceding one
(1,2,3,4 ➜ 1-2, 2-3, 3-4)
4 pr_trianglelist Trios of vertices to be joined into triangles
(1,2,3,4,5,6 ➜ 1-2-3, 4-5-6)
5 pr_trianglestrip Each vertex is connected to the preceding two
(1,2,3,4,5,6 ➜ 1-2-3, 2-3-4, 3-4-5, 4-5-6)
Often used for drawing curves and multi-segment lines.
6 pr_trianglefan Each vertex is connnected to a preceding one and to the first vertex
(1,2,3,4,5,6 ➜ 1-2-3, 1-3-4, 1-5-6)
Often used for drawing circles, stars, and anything else where everything connects to a center point.

Note: Since GameMaker models tend to be converted from other common formats, implementing instructions 0 (for pr_trianglelist), 1, and 9 is enough to display most of these.

Software

A number of tools exist for converting GM models, mostly made in GM itself, such as:


That is all.

Related posts:

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.