VMF Transpiler

1.0.0 verified Fri May 01 auth: no javascript

VMF Transpiler is a library for converting between Valve Map Format (VMF) used by the Hammer editor and JSON. Version 1.0.0, based on leops/vmfparser. It provides parse() and compile() functions for bidirectional conversion, with support for VMF-specific features like multiple values per key (converted to arrays). It is a lightweight utility for game development tooling involving Source Engine maps. Currently stable but single-version release with no published updates.

Common errors

error TypeError: vmf_transpiler_1.parse is not a function ↓

cause Using default import instead of named import.

fix

Use import { parse } from 'vmf-transpiler' instead of import parse from 'vmf-transpiler'.

error Cannot find module 'vmf-transpiler' ↓

cause Module not installed or not in node_modules.

fix

Run npm install vmf-transpiler, or check that the package name is correct.

error SyntaxError: Unexpected token ':' in JSON at position ... ↓

cause Passing a JSON string to parse instead of VMF string.

fix

Ensure input to parse() is VMF format, not JSON.

Warnings

gotcha Duplicate keys in VMF become arrays in JSON, which may be unexpected. ↓

fix Handle output values that can be strings or arrays; check Array.isArray().

gotcha The parse method does not preserve key order beyond what JavaScript objects support. ↓

fix Use ast: true option to get an AST if order matters.

breaking No TypeScript types shipped; module does not include type definitions. ↓

fix Write ambient declarations or use @ts-ignore.

Install

npm install vmf-transpiler

yarn add vmf-transpiler

pnpm add vmf-transpiler

Imports

parse

wrong

const vmf = require('vmf-transpiler'); vmf.parse()

correct

import { parse } from 'vmf-transpiler'

ESM module; named exports only.

compile

wrong

import vmf from 'vmf-transpiler'; vmf.compile()

correct

import { compile } from 'vmf-transpiler'

No default export; only named exports.

whole module

wrong

const vmf = require('vmf-transpiler')

correct

import * as vmf from 'vmf-transpiler'

For CommonJS, use dynamic import() or use ESM.

Quickstart

Shows importing parse and compile, converting a VMF string to a JSON object, and back to VMF string.

import { parse, compile } from 'vmf-transpiler';

// Example VMF string
const vmfSource = `"entity"
{
  "id" "1"
  "classname" "info_player_start"
  "origin" "0 0 0"
}`;

// Parse VMF to JSON
const json = parse(vmfSource);
console.log(json);
// Output: { entity: { id: '1', classname: 'info_player_start', origin: '0 0 0' } }

// Compile JSON back to VMF
const vmfOutput = compile(json);
console.log(vmfOutput);
// Output: "entity"\n{\n\t"id" "1"\n\t"classname" "info_player_start"\n\t"origin" "0 0 0"\n}