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.
celaria-formats is a JavaScript library for reading and writing the binary file formats used by Celaria, a first-person parkour game. It gives you a structured API for parsing map files into JavaScript objects and serializing them back to binary — so you can inspect existing maps, build tools, or generate levels programmatically without touching the raw binary format yourself.
Supported formats
| Format | Extension | Class | Description |
|---|---|---|---|
| Celaria Map | .cmap | CelariaMap | Finalized map file with checkpoint ordering and medal times |
| Editable Celaria Map | .ecmap | EditableCelariaMap | Editable map for the in-game level editor |
| UV Map | .cuvdata | CelariaUvMap | Per-face UV texture coordinate data for map blocks |
Key concepts
Celaria uses two distinct map formats that serve different purposes in the game’s workflow.CelariaMap (.cmap) represents a finalized map ready for play. It includes checkpoint ordering and medal times (platinum, gold, silver, bronze) on every checkpoint and goal block. Use CelariaMap when you want to parse maps as they appear to players, or when producing a map for the game server.
EditableCelariaMap (.ecmap) represents a map as stored by the in-game level editor. It does not carry medal time data. Use EditableCelariaMap when you want to read or write maps that will be opened in the editor rather than played directly.
Both classes extend BaseCelariaMap, which defines the shared structure: a list of instances, a checkpointOrder set, lighting properties (sunRotationHorizontal, sunRotationVertical), and a previewCamera position.
CelariaMap.serialize() defaults to format version 2. EditableCelariaMap.serialize() requires an explicit version number — passing no argument throws an error.Map object types
Every object placed in a map is anInstance stored in map.instances. You can identify each instance by its instanceId property.
Block
Block (instanceId 0) is the primary geometry type — a rectangular prism. Every block has a type that controls its in-game behavior:
| Type | Value | Description |
|---|---|---|
plain | 0 | Standard level geometry with no special effect |
goal | 1 | The red finish block; the last entry in checkpointOrder |
jump | 2 | Green block that lets players jump higher |
speed | 3 | Yellow block that accelerates players on contact |
ice | 4 | Blue block that reduces traction |
checkpoint | 5 | Intermediate checkpoint; ordered via checkpointOrder |
CelariaMap carry a medalTimes object with platinum, gold, silver, and bronze fields (in game ticks).
Sphere
Sphere (instanceId 1) is a collectible object — a red sphere the player can pick up. It has a position but no rotation or scale.
PlayerSpawnPoint
PlayerSpawnPoint (instanceId 2) marks where the player starts in the map. It has a position and a rotation (facing direction).
Barrier
Barrier (instanceId 3 or 4) is an invisible wall or floor that slows players who pass through it. Whether a barrier serializes as a wall (instanceId 3) or floor (instanceId 4) is determined automatically by its scale: a non-zero Z component makes it a wall; a non-zero Y component makes it a floor.
TutorialHologram
TutorialHologram (instanceId 128) is a special object used in tutorial levels. It has a type, position, scale, and rotation.
Where to go next
Quickstart
Install the library and parse your first map file in a few steps.
Reading maps
Parse
.cmap and .ecmap files and work with their contents.Writing maps
Modify map data and serialize it back to a binary buffer.
API reference
Full reference for all exported classes, methods, and types.