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.

CelariaMap represents a finalized Celaria map — one that includes medal times on checkpoint and goal blocks and is ready to be played in-game. It extends BaseCelariaMap and adds the game mode property, checkpoint medal time handling, and version-aware serialization. Use EditableCelariaMap instead if you are working with maps opened in the in-game editor.

​
Inheritance

CelariaMap extends BaseCelariaMap and inherits all of its properties: instances, checkpointOrder, name, sunRotationHorizontal, sunRotationVertical, previewCamera, and version.

​
Static properties

​
fileSignature

CelariaMap.fileSignature // "celaria_map"
The 11-character ASCII string written at the start of every .cmap file. parse checks this value and throws if the buffer does not begin with it.

​
gameModes

CelariaMap.gameModes // { freeRoam: 0, timeTrial: 1 }
An object mapping game mode names to their integer values as stored in the binary format.
KeyValueDescription
freeRoam0No timer, no checkpoint requirements
timeTrial1Timed run with checkpoint and goal ordering

​
Instance properties

​
mode

map.mode // number, default: CelariaMap.gameModes.timeTrial
The game mode of the map. Defaults to CelariaMap.gameModes.timeTrial (1) on construction. Set this to CelariaMap.gameModes.freeRoam to produce a free-roam map.

​
Static methods

​
parse(buffer)

Parses a .cmap binary buffer and returns a populated CelariaMap instance.
​
buffer
Buffer
required
A Node.js Buffer containing the raw bytes of a .cmap file.
Returns: CelariaMap Checkpoints and the goal block are sorted by their priority value during parsing and assigned their medal times from the header. The resulting checkpointOrder reflects that sorted sequence.
Throws Error("Magic mismatch.") if the first 11 bytes of the buffer do not equal "celaria_map".Throws Error("Missing Block#medalTimes on checkpoint/goal.") if there are fewer medal time entries in the file header than there are checkpoint and goal blocks.Throws Error("I can't decide if I am a wall or a floor.") if a Barrier instance has a scale configuration that does not resolve to either a wall (instance type 3) or a floor (instance type 4).Throws Error("Unknown instance type ${instanceType}.") if the file contains an instance type byte that is not 0, 1, 2, 3, 4, or 128.
import fs from "node:fs"
import { CelariaMap } from "celaria-formats"

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

console.log(map.name)
console.log(map.mode)        // 1 (timeTrial)
console.log(map.instances.length)

​
instanceTypeIsSupported(instanceType, version)

Returns whether a given instance type is supported in a given file format version. Barriers (instance types 3 and 4) require version 2 or higher.
​
instanceType
number
required
The instance type integer. Use the instanceId property of a map object instance.
​
version
number
required
The format version number to check against.
Returns: boolean 
CelariaMap.instanceTypeIsSupported(3, 1) // false — barriers not supported in v1
CelariaMap.instanceTypeIsSupported(3, 2) // true
CelariaMap.instanceTypeIsSupported(0, 0) // true — blocks supported in all versions

​
Instance methods

​
serialize(version?)

Serializes the map to a binary buffer suitable for writing to a .cmap file.
​
version
number
default:"2"
The format version to serialize to. Defaults to 2 if not specified.
Returns: Buffer Blocks that are in checkpointOrder are written after all other instances and have their type set to checkpoint or goal (the last entry) in place. Blocks that were already typed as checkpoint or goal but are not in checkpointOrder are downgraded to plain blocks during serialization.
Serialization modifies checkpoint and goal block type values in place. If you need to preserve the original type values, work on a copy of the map data.
Throws Error("Missing Block#medalTimes on checkpoint/goal.") if any block in checkpointOrder does not have a medalTimes object set.Throws Error("Instance type ${name} unsupported on version ${version}.") if the map contains a Barrier and version is less than 2.Throws Error("I can't decide if I am a wall or a floor.") if a Barrier instance has a scale that cannot be resolved to wall or floor.
import fs from "node:fs"
import { CelariaMap } from "celaria-formats"

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

// Change the game mode and re-serialize
map.mode = CelariaMap.gameModes.freeRoam
const output = map.serialize()         // version defaults to 2
fs.writeFileSync("./modified.cmap", output)

​
Full example

import fs from "node:fs"
import { CelariaMap, Block, Sphere, Barrier } from "celaria-formats"

// Parse an existing map
const buffer = fs.readFileSync("./myMap.cmap")
const map = CelariaMap.parse(buffer)

console.log(`Map name: ${map.name}`)
console.log(`Mode: ${map.mode === CelariaMap.gameModes.timeTrial ? "Time Trial" : "Free Roam"}`)
console.log(`Instances: ${map.instances.length}`)

// Count spheres
const sphereCount = map.instances.filter(i => i instanceof Sphere).length
console.log(`Spheres: ${sphereCount}`)

// Check checkpoint medal times
for (const checkpoint of map.checkpointOrder.toArray()) {
  console.log(checkpoint.medalTimes)
  // { platinum: number, gold: number, silver: number, bronze: number }
}

// Check barrier support before serializing to an older version
const hasBarriers = map.instances.some(i => i instanceof Barrier)
if (hasBarriers && !CelariaMap.instanceTypeIsSupported(3, 1)) {
  console.warn("Barriers are not supported in version 1")
}

// Serialize to version 2 (default)
const output = map.serialize()
fs.writeFileSync("./output.cmap", output)

EditableCelariaMap

The editable map format for the in-game editor, without medal times.

BaseCelariaMap

Shared base class with all common properties and defaults.

Block

Block instance including checkpoint, goal, and medal time fields.

Types

Type definitions including MedalTimes and Vector3.

Build docs developers (and LLMs) love

Get started for freeTalk to us