@mowogames/mdf

A typed, human-readable data format designed for game engines. First-class support for vec3(), quat(), rgb(), hex(), uuid(), asset references, and bare enums.

This is the official JavaScript/TypeScript implementation of MDF.

Install

npm install @mowogames/mdf

Quick Start

Parse

import { parse } from "@mowogames/mdf";

const doc = parse(`
  Scene "Forest" {
    version: 2
    gravity: vec3(0, -9.81, 0)

    GameObject "Player" {
      active: true
      mesh: @"Assets/Models/Character.fbx"

      Transform {
        position: vec3(0, 1, 0)
        rotation: quat(0, 0.707, 0, 0.707)
      }

      RigidBody {
        type: Dynamic
        mass: 75.0
      }
    }
  }
`);

const root = doc.root();
console.log(root.type);  // "Scene"
console.log(root.name);  // "Forest"

const gravity = root.getVec3("gravity");
console.log(gravity);  // { x: 0, y: -9.81, z: 0 }

const player = root.findChild("GameObject", "Player");
console.log(player.getBool("active"));     // true
console.log(player.getString("mesh"));     // "Assets/Models/Character.fbx"

const pos = player.findChild("Transform").getVec3("position");
console.log(pos);  // { x: 0, y: 1, z: 0 }

Build & Serialize

import {
  MdfDocument, MdfInt, MdfBool, MdfString, MdfVec3Val,
  MdfEnum, MdfAssetRef, MdfUUID, stringify
} from "@mowogames/mdf";

const doc = new MdfDocument();
const scene = doc.createRoot("Scene", "MyLevel");
scene.set("version", MdfInt(1));
scene.set("gravity", MdfVec3Val(0, -9.81, 0));

const player = scene.addChild("GameObject", "Player");
player.set("active", MdfBool(true));
player.set("tag", MdfString("Player"));
player.set("id", MdfUUID("550e8400-e29b-41d4-a716-446655440000"));

const transform = player.addChild("Transform");
transform.set("position", MdfVec3Val(0, 1, 0));

const body = player.addChild("RigidBody");
body.set("type", MdfEnum("Dynamic"));

console.log(stringify(doc));

Output:

Scene "MyLevel" {
    version: 1
    gravity: vec3(0.0, -9.81, 0.0)

    GameObject "Player" {
        active: true
        tag: "Player"
        id: uuid("550e8400-e29b-41d4-a716-446655440000")

        Transform {
            position: vec3(0.0, 1.0, 0.0)
        }

        RigidBody {
            type: Dynamic
        }
    }
}

Value Types

| Type | MDF Syntax | Constructor | |------|-----------|-------------| | Null | null | MdfNull() | | Bool | true / false | MdfBool(true) | | Int | 42 | MdfInt(42) | | Float | 3.14 | MdfFloat(3.14) | | String | "hello" | MdfString("hello") | | Vec2 | vec2(1, 2) | MdfVec2Val(1, 2) | | Vec3 | vec3(1, 2, 3) | MdfVec3Val(1, 2, 3) | | Vec4 | vec4(1, 2, 3, 4) | MdfVec4Val(1, 2, 3, 4) | | Quat | quat(0, 0, 0, 1) | MdfQuatVal(0, 0, 0, 1) | | Color | rgb(0.5, 0.2, 0.1) | Parsed as Vec4 with alpha 1.0 | | Hex | hex(#FF6600) | Parsed as normalized Vec4 | | UUID | uuid("...") | MdfUUID("...") | | Asset Ref | @"path" | MdfAssetRef("path") | | Enum | Dynamic | MdfEnum("Dynamic") | | Array | [1, 2, 3] | MdfArray([...]) |

API

parse(source: string): MdfDocument

Parse MDF text. Throws on syntax errors.

stringify(doc: MdfDocument, indent?: number): string

Serialize a document to MDF text format.

MdfDocument

doc.createRoot(type, name?)  // Create root node
doc.root()                   // Get first root (throws if empty)
doc.roots                    // All root nodes

MdfNode

node.type                    // Node type identifier
node.name                    // Optional name
node.set(key, value)         // Set property (chainable)
node.get(key)                // Get raw MdfValue
node.has(key)                // Check if property exists
node.properties              // Map<string, MdfValue>

// Typed getters (throw on type mismatch)
node.getBool(key)            // boolean
node.getInt(key)             // number (truncated)
node.getFloat(key)           // number
node.getString(key)          // string (works for String, UUID, AssetRef, Enum)
node.getVec2(key)            // { x, y }
node.getVec3(key)            // { x, y, z }
node.getVec4(key)            // { x, y, z, w }
node.getArray(key)           // MdfValue[]

// Children
node.addChild(type, name?)   // Add child node
node.findChild(type, name?)  // Find first child by type
node.findChildren(type)      // Find all children by type
node.children                // All children

Format Features

• // line comments and /* */ block comments
• Trailing commas in arrays
• Scientific notation (1e-6)
• Escape sequences in strings (\n, \t, \\, \")
• Multiple root nodes per document
• Heterogeneous arrays

Compatibility

Fully compatible with the C++ MDF library. Files written by either implementation can be read by the other.

License

MIT