Old School Ops

MMO World Format

The open, engine-neutral file format GoMMO Studio saves an MMO world in, and how to turn it into your own game's files with an exporter.

Every game · updated 2026-10-11
On this page

An MMO World is a folder. It holds one world.json, one folder per map, and your own models. Every file is plain JSON or a standard 3D format, so any tool or game can read it without GoMMO Studio. This page is the full specification, version 2.

The folder

my-world/
  world.json                the world: its unit, object kinds, map settings and catalogue
  maps/
    start/
      map.json              one map: its settings, objects and painted grids
      terrain.glb           optional ground model for this map
      terrain_height.png    optional editable terrain: heights as a greyscale image
      terrain_color.png     the colours draped over it
      terrain_layer_grass.png   the weights of one tiled texture layer
      terrain_holes.png     the cells cut out of the terrain
      foliage_pine.bin      the instances of one foliage layer
      lightmap_terrain.png  baked light over the terrain
      lightmap_props_0.png  baked light for props
      navmesh.json          the walkable ground as polygons, for a server's pathing
    darkwood/
      map.json
      terrain/              a terrain larger than one tile: its images split into tiles
        height_0_0.png
        color_0_0.png
  models/                   your glTF, GLB, OBJ and FBX files, in any folders you like
  textures/                 images terrain layers tile, anywhere outside maps/
  exporters/
    example.lua             scripts that write your game's own files

Versions

world.json and every map.json say which version of this format they were written for. Version 2 adds terrain texture layers, holes and tiles, foliage, baked lighting and the navmesh; everything else is version 1. A writer should use the oldest version that describes the file: GoMMO Studio writes version 1 for a map that uses none of the version 2 fields, so older readers keep opening it. A reader refuses a version newer than it knows and reads every older one.

A map's key is its folder name: lower case letters, digits, _ and -, at most 64 characters. Paths inside the files use forward slashes and are relative: a model path to the world folder, a terrain path to its map's folder.

Units and axes

  • Positions are in world units. unitsPerMetre in world.json says how many make a metre; it defaults to 100, so a world unit is a centimetre unless you say otherwise.
  • Z is up. X and Y lie on the ground.
  • Models are read in metres, the glTF convention, and scaled by unitsPerMetre. glTF, OBJ and FBX files are all converted to Z up as they load.
  • rot is [yaw, pitch, roll] in degrees. Yaw turns about +Z, counter-clockwise seen from above, with 0 facing +X. A positive pitch tips the object's +X axis down. Roll turns about the tipped X axis. Written as the object's axes in world space:
X = ( cos(yaw)cos(pitch),  sin(yaw)cos(pitch),  -sin(pitch) )
Y = ( cos(yaw)sin(pitch)sin(roll) - sin(yaw)cos(roll),
      sin(yaw)sin(pitch)sin(roll) + cos(yaw)cos(roll),  cos(pitch)sin(roll) )
Z = ( cos(yaw)sin(pitch)cos(roll) + sin(yaw)sin(roll),
      sin(yaw)sin(pitch)cos(roll) - cos(yaw)sin(roll),  cos(pitch)cos(roll) )

A model-space point p lands at pos + X*p.x*scale.x + Y*p.y*scale.y + Z*p.z*scale.z.

world.json

{
  "format": "mmo-world",
  "version": 1,
  "name": "My World",
  "unitsPerMetre": 100,
  "kinds": [],
  "mapSettings": [],
  "creatures": [ { "id": "wolf", "name": "Grey Wolf", "model": "models/wolf.glb", "level": 3, "group": "Beasts" } ],
  "npcs":      [ { "id": "smith", "name": "Blacksmith", "model": "models/smith.glb", "group": "Town" } ],
  "items":     [ { "id": "copper_ore", "name": "Copper Ore", "group": "Ore" } ],
  "exporters": [ { "name": "My server", "script": "exporters/server.lua", "output": "../server/data", "onSave": true } ]
}
FieldMeaning
format, versionAlways "mmo-world" and the version the file was written for. A reader refuses a version newer than it knows.
nameThe world's name.
unitsPerMetreWorld units in a metre. Optional; 100 when left out.
kindsObject kinds. Each one replaces the default kind of the same name or adds a new one. Optional.
mapSettingsThe settings every map carries. When present it replaces the default list. Optional.
creatures, npcs, itemsThe catalogue a spawn, NPC or field picks from. id is what a map stores; model is drawn in the editor; scale multiplies the model.
exportersLua scripts that write your game's files. See Exporters.

Object kinds

A kind says what an object is, how the editor shapes it, and which fields it carries.

{
  "kind": "chest", "label": "Treasure chest", "layer": "chests", "side": "server",
  "shape": "point", "model": "model", "color": "#c08040", "rotates": true,
  "fields": [ { "key": "gold", "label": "Gold", "type": "int", "default": 10 } ]
}
FieldMeaning
kindThe name a map's objects use.
label, layer, colorHow the editor names, groups and colours it. layer defaults to kind.
sideclient or server: which half of your game reads it. Defaults to server.
shapepoint, box (uses size), radius (uses radius) or path (uses points).
modelWhat an object's model names: model (a model file), creature, npc, or nothing.
pointstrue when the object carries a point list as well as its shape, such as a spawn's spawn points.
rotates, scalesWhether the editor offers rotation and scale.
fixedtrue stops the editor adding new objects of this kind.
fieldsThe kind's typed values.

A field has a key, a label, a type, an optional default, and help text. Types are text, int, float, bool, color (#rrggbb), enum (with options, each a value and a label), and the references creature, npc, item and map, which the editor fills from the catalogue or the world's map list.

The default kinds

A world that lists no kinds gets these. A new world writes them into its world.json so you can change them.

KindShapeModelFields
proppointmodel filecollision
spawnradius, with pointscreaturecount, respawn (seconds), wander, level, path
npcpointNPCrole, dialogue
portalboxtarget_map, target_marker, min_level
markerpointstart, respawn
regionboxtype, music, min_level, max_level
pathpathloop, speed
resourcepointmodel fileitem, amount, respawn
soundradiussound, volume, loop
triggerboxevent, once
lightradiustype (point, spot or sun), color, intensity, enabled
roadpathwidth and shoulder (metres), flatten, layer
riverpathwidth, depth and shoulder (metres), layer, color
waterboxcolor, opacity, swim

A light turns like any object: a sun or spot shines along its X axis. A road and a river are curves through their points (see Roads, rivers and water). A water box's top face is the water's surface; its depth is the box.

The default map settings are type, min_level, max_level, music, sky, fog_color, fog_start and fog_end.

map.json

{
  "format": "mmo-world-map",
  "version": 1,
  "title": "Willow Vale",
  "group": "Starter Zones",
  "size": [20000, 20000],
  "terrain": "terrain.glb",
  "settings": { "music": "vale_day", "min_level": 1 },
  "objects": [
    { "id": "spawn-1", "kind": "spawn", "name": "Grey Wolf", "model": "wolf",
      "pos": [4500, 3500, 0], "radius": 900,
      "points": [[4200, 3300, 0], [4800, 3700, 0]],
      "props": { "count": 4, "respawn": 45 } }
  ],
  "grids": []
}
FieldMeaning
title, groupThe map's name, and the heading it is listed under.
sizeThe flat ground a map with no terrain is drawn on, centred on the origin.
terrainA model file in the map's folder, drawn as the map's ground and used for ground snapping. GoMMO Studio can build one from a greyscale heightmap image. Optional.
terrainGridAn editable terrain, which a reader draws in place of terrain when it can. See The terrain grid. Optional.
settingsValues for the world's map settings, by key.
objectsEverything placed on the map.
gridsPainted per-cell layers, such as a walkable grid.
foliageModels painted many times over the map, such as grass, trees and rocks. See Foliage. Version 2, optional.
lightingBaked light for the terrain and the props. See Baked lighting. Version 2, optional.
navmeshA navmesh file in the map's folder. See The navmesh. Version 2, optional.

An object has an id unique on its map, a kind, an optional name and model, a pos, and as its kind needs: rot, scale, size (a box's half extents), radius and points. Its fields go in props, keyed by field key. A value that equals its field's default may be left out; a reader uses the default.

A grid has a key, a label, w and h in cells, an origin (the corner of cell 0,0), a cell edge in world units, and cells, a base64 string of w * h bytes where cell (x, y) is byte y * w + x. A palette names what each byte value means.

The walkable grid

A grid with the key walk is the map's walkable area for a server's pathing: a cell holding 0 is walkable and 1 is blocked. GoMMO Studio generates it from the map's geometry (the Map tab's Walkable area) by sampling the top surface at each cell's centre and blocking a cell with no ground, or whose rise to a neighbour is steeper than the slope and higher than the step you set. Foliage that blocks movement blocks the cells under it.

The terrain grid

"terrainGrid": {
  "height": "terrain_height.png", "color": "terrain_color.png",
  "size": [25600, 25600], "low": -1200, "high": 6000,
  "holes": "terrain_holes.png",
  "layers": [
    { "key": "grass", "label": "Grass", "texture": "textures/grass.png", "tile": 400,
      "weights": "terrain_layer_grass.png" }
  ]
}

The terrain is a grid of vertices spanning size world units centred on the origin. Its height image holds one pixel per vertex, its top row the map's north (+Y) edge and its left column the west (-X) edge; black stands for low and white for high in world units, read at any bit depth (GoMMO Studio writes 16-bit greyscale). color is an image drawn over the whole ground edge to edge, whatever its size. GoMMO Studio also writes terrain as a matching terrain.glb, with the texture layers drawn into its colours and at most 513 vertices a side, so a reader that only takes a model sees the same ground.

  • Texture layers (version 2). Each layer tiles the image texture (relative to the world folder) every tile world units: U runs along +X and V along -Y, starting at the world origin. weights is an 8-bit greyscale image with one pixel per vertex, laid out like the height image. Layers are drawn in order over the colour image: at every point, colour = colour + (texture - colour) * weight / 255, the weight interpolated between vertices. At most 8 layers.
  • Holes (version 2). holes is an 8-bit greyscale image with one pixel per cell (one fewer than the vertices each way): a non-zero pixel cuts that cell out of the ground, which a reader neither draws nor stands anything on. Holes let a model, such as a cave mouth, take the ground's place.
  • Tiles (version 2). A terrain more than 257 vertices a side is split into tiles of cells cells, and tiles replaces height, color and holes:
"terrainGrid": {
  "size": [409600, 409600], "low": 0, "high": 12000,
  "tiles": { "cells": 256, "grid": [4097, 4097],
             "height": "terrain/height_{x}_{y}.png", "color": "terrain/color_{x}_{y}.png",
             "holes": "terrain/holes_{x}_{y}.png" },
  "layers": [ { "key": "rock", "texture": "textures/rock.png", "tile": 800,
                "weights": "terrain/layer_rock_{x}_{y}.png" } ]
}

grid is the whole terrain's vertices across and down. Tile (x, y) covers cells x * cells up to (x + 1) * cells across (fewer in the last column) and the same down, {x} and {y} in each path name its column and row from 0 at the north-west corner. Its height and weight images hold the vertices on both of its edges, so neighbouring tiles repeat the vertices they share; its hole image holds its cells; its colour image holds the same whole number of texels for every cell of the terrain. low and high apply to every tile.

Foliage

Version 2. A foliage layer is one model painted many times. Its instances are kept in a binary file in the map's folder, so a map can hold hundreds of thousands of them.

"foliage": [
  { "key": "pine", "label": "Pine", "model": "models/pine.glb",
    "instances": "foliage_pine.bin", "count": 2400, "collision": true, "radius": 60 }
]
FieldMeaning
keyThe layer's name: lower case letters, digits, _ and -, unique on the map.
modelThe model file every instance draws, relative to the world folder.
instances, countThe instance file in the map's folder, and how many instances it holds. A reader refuses a file whose count differs.
collisionThe instances block movement and cast shadows.
radiusThe blocking radius at scale 1 in world units; 0 takes half the model's width.

The instance file is little-endian: the four bytes MMWF, then three 32-bit unsigned integers (the file version, 1; the instance count; the bytes per instance, 28), then for each instance seven 32-bit floats: x, y, z, yaw, pitch, roll and scale. Position and rotation mean what an object's pos and rot mean, and scale multiplies the model on all three axes.

Roads, rivers and water

A road or river object is a smooth curve through its points: a Catmull-Rom spline that passes through every point, at each point's height. Shaping the ground along one is an editing step, not something a reader repeats: GoMMO Studio levels the terrain under a road to the curve across its width, blends it into the ground over its shoulder and paints its texture layer; under a river it cuts a channel depth metres below the curve at its centre. What is stored is the shaped terrain and the objects. A reader draws a river's water as a flat strip width wide along the curve, at its points' height, and a water box's water at its top face, in its color and opacity.

Baked lighting

Version 2. A bake stores how much light reaches each surface, so a reader can draw the map lit without lighting it again.

"lighting": {
  "terrain": "lightmap_terrain.png",
  "pages": ["lightmap_props_0.png"],
  "props": [
    { "id": "prop-3", "page": 0, "rect": [0.002, 0.002, 0.123, 0.123], "probe": [0, 0, 0] },
    { "id": "prop-4", "page": -1, "probe": [0.93, 0.9, 0.84] }
  ],
  "scale": 2
}
  • A lightmap image's RGB is light: light = texel / 255 * scale. A surface is drawn as its colour times its light, so with scale 2 a texel of 128 leaves the colour as it is.
  • terrain is drawn over the terrain grid's ground edge to edge, its top row the north edge.
  • A prop whose model has a second set of texture coordinates (glTF TEXCOORD_1) has a page and a rect: its lightmap coordinate is (x + u1 * w, y + v1 * h) on that page, where rect is [x, y, w, h] in 0 to 1 and (u1, v1) is the model's second set.
  • Every other prop has page -1 and a probe: the light at its top, which tints the whole prop.
  • A prop the list does not name, such as one placed after the bake, is drawn with the reader's own lighting.

The navmesh

Version 2. navmesh names a JSON file in the map's folder: the map's walkable ground as convex polygons, for a server to find paths across.

{
  "format": "mmo-world-navmesh", "version": 1, "cell": 100,
  "verts": [[0, 0, 12], [800, 0, 12], [800, 800, 15], [0, 800, 14]],
  "polys": [ { "verts": [0, 1, 2, 3], "links": [-1, 4, -1, 2] } ]
}

Positions are world units. Each polygon lists its corners counter-clockwise seen from above, and for each edge, from corner i to corner i + 1 (the last back to the first), the index of the polygon across it, or -1 where the edge is a wall. Two linked polygons share that edge exactly. cell is the walkable grid's cell the mesh was built from. GoMMO Studio builds it from the walk grid, merging open cells into rectangles.

How the maps connect

A field whose type is map names another map. With the default kinds that is a portal's target_map, and its target_marker names an object on the target map by its name. A marker whose start is true makes its map a start map. GoMMO Studio's World graph reads these to show every map, the portals between them, the maps no start reaches, the maps with no portal out, and portals into a level range much higher than the map they leave.

Maps exported from a game

A map GoMMO Studio exports from a game client keeps the game's own kinds and fields, so a spawn from RF Online carries RF's fields. Two props may appear on its objects:

  • game_model: the game's own model key, on a prop whose model was not exported.
  • in_terrain: true on a prop that is drawn as part of the map's terrain.glb instead of as a model of its own, because its placement in the game cannot be written as rot and scale.

Rules for tools that write the format

  • Keep every props key you do not understand, with its value unchanged. GoMMO Studio does: a field your world.json does not define stays in the file through every save.
  • Keep object ids stable. Other files may refer to them.
  • Leave out what you would write as zero: rot, scale, size and radius default to nothing turned, scaled or sized.

Exporters

An exporter is a Lua script in the world folder that turns the world into your game's own files. GoMMO Studio runs it from the World tab, and after every save when onSave is true. The script runs in a sandbox: it cannot open files or run programs. It reads the world through these functions and hands back what it wants written.

FunctionReturns or does
world()world.json as a table, with the kinds and map settings filled in from the defaults.
maps()Every map as a table, with its key added. Lists start at 1 in Lua, so o.pos[1] is X.
write(path, text)Writes text to path under the exporter's output folder. A path that leaves that folder is refused.
json(value)Turns a table into indented JSON text.
log(text)Shows a line in the editor after the run.
terrain(key)The map's terrain grid as a table (w, h, size, low, high, tiled, holes, layers), or nil when it has none.
height(key, x, y)The terrain's height at a ground point, or nil off the terrain or over a hole.
weight(key, layer, x, y)A texture layer's weight at a ground point, 0 to 1, or nil.
foliage(key)The map's foliage layers, each with its instances (x, y, z, yaw, pitch, roll, scale).
navmesh(key)The map's navmesh as a table, or nil when it has none.

terrain, height, weight, foliage and navmesh read the map's saved files.

output is relative to the world folder and may lie outside it, so an exporter can write straight into a server's data folder. It may not be the world folder itself or its maps folder. A file whose bytes have not changed is left untouched. A script that runs for more than a minute, or loops without end, is stopped.

local lines = { "map,id,creature,x,y,z,count" }
for _, m in ipairs(maps()) do
  for _, o in ipairs(m.objects) do
    if o.kind == "spawn" then
      local p = o.props or {}
      lines[#lines + 1] = string.format("%s,%s,%s,%g,%g,%g,%d",
        m.key, o.id, o.model or "", o.pos[1], o.pos[2], o.pos[3], p.count or 1)
    end
  end
end
write("spawns.csv", table.concat(lines, "\n") .. "\n")

A new world comes with exporters/example.lua, which writes a spawn table and one JSON file per map. Copy it and change what it writes.

Something here wrong?

Out of date, incomplete, or assuming something it should not. Documentation errors are bugs, and this one arrives tagged and pointed at this page.

Top xp sources

How xp works
Loading…

Open the full search page