Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/BunnyNabbit/celaria-formats/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you’ll have celaria-formats installed, a .cmap file parsed into a JavaScript object, and a modified map serialized back to a binary buffer. All examples use ES module syntax.
1

Install the package

Add celaria-formats to your project using your preferred package manager.
npm install celaria-formats
celaria-formats is an ES module package. Make sure your project is using ES modules — either set "type": "module" in your package.json or use .mjs file extensions.
2

Parse a .cmap file

Read a .cmap file from disk and pass the buffer to CelariaMap.parse().
parse-map.mjs
import fs from "node:fs"
import { CelariaMap } from "celaria-formats"

const buffer = fs.readFileSync("./map.cmap")
const map = CelariaMap.parse(buffer)

console.log(map.name)      // The map's name, e.g. "My Level"
console.log(map.version)   // The file format version number
console.log(map.instances) // Array of all objects in the map
CelariaMap.parse() returns a CelariaMap instance with all map objects deserialized into typed JavaScript classes. The instances array holds every object placed in the map — blocks, spheres, barriers, and more.
Maps saved in format version 0 or 1 encode positions as scaled integers (divided by 10). Version 2 and later use 64-bit doubles. parse() handles both automatically, but if you re-serialize a version 0/1 map with serialize() (which defaults to version 2), coordinate precision will increase and the output will not be byte-for-byte identical to the original.
3

Inspect instances

Filter map.instances by class or instanceId to work with specific object types.
inspect-instances.mjs
import fs from "node:fs"
import { CelariaMap, Block, Sphere, PlayerSpawnPoint } from "celaria-formats"

const map = CelariaMap.parse(fs.readFileSync("./map.cmap"))

// Find all blocks
const blocks = map.instances.filter(i => i instanceof Block)
console.log(`${blocks.length} blocks in map`)

// Find all checkpoints in order
const checkpoints = map.checkpointOrder.toArray()
console.log(`${checkpoints.length} checkpoints (including goal)`)

// Find the player spawn
const spawn = map.instances.find(i => i instanceof PlayerSpawnPoint)
console.log("Spawn position:", spawn.position) // [x, y, z]

// Count collectible spheres
const spheres = map.instances.filter(i => i instanceof Sphere)
console.log(`${spheres.length} collectible spheres`)
The last entry in map.checkpointOrder is always the goal block. Checkpoints appear in the order the player must reach them.
4

Modify and serialize

Change properties on instances and call map.serialize() to produce a binary buffer you can write back to disk.
modify-map.mjs
import fs from "node:fs"
import { CelariaMap, Block } from "celaria-formats"

const map = CelariaMap.parse(fs.readFileSync("./map.cmap"))

// Turn every plain block into a speed block
map.instances
  .filter(i => i instanceof Block && i.type === Block.types.plain)
  .forEach(block => {
    block.type = Block.types.speed
  })

// Serialize to a buffer (defaults to format version 2)
const output = map.serialize()
fs.writeFileSync("./map-modified.cmap", output)
serialize() on CelariaMap defaults to version 2. You can pass a version number explicitly — for example map.serialize(2) — if you need to target a specific format.
Barriers (walls and floors) are not supported in format versions 0 and 1. If your map contains Barrier instances and you serialize to version 0 or 1, serialize() will throw an error.

​
Next steps

Reading maps

A deeper look at parsing both .cmap and .ecmap formats.

Writing maps

Build or transform maps and write them back to binary.

Map objects

Learn about every object type and how to work with them.

CelariaMap API

Full reference for the CelariaMap class.

Build docs developers (and LLMs) love

Get started for freeTalk to us