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.

Instance is the root class in the map-object hierarchy. Every object that can appear inside a Celaria map — blocks, spheres, barriers, and more — extends Instance. It is responsible for defining the one property all objects share: their position in the world. You should never instantiate Instance directly; use one of its concrete subclasses instead.
Instance is abstract. Calling new Instance() produces an object whose instanceId getter throws Error("Instance#instanceId is abstract and must be implemented by subclasses.") when accessed. Always instantiate a concrete subclass such as Block, Sphere, or Barrier.

​
Constructor

new Instance()
The base constructor initializes position to [0, 0, 0]. Subclass constructors call this via super() before setting their own properties.

​
Properties

​
position
[number, number, number]
required
The world-space position of the object as an [x, y, z] tuple. Defaults to [0, 0, 0].Celaria uses Z as the gravity axis, so Z represents the vertical dimension. X and Y span the horizontal plane.

​
Getters

​
instanceId
number
Returns the numeric identifier that distinguishes this object type during binary serialization. Each concrete subclass returns a fixed value.
instanceIdClassDescription
0BlockRectangular geometry block
1SphereCollectible red sphere
2PlayerSpawnPointPlayer starting position
3Barrier (wall)Physics barrier oriented as a wall
4Barrier (floor)Physics barrier oriented as a floor
128TutorialHologramTutorial hologram display object
On Instance itself this getter throws Error("Instance#instanceId is abstract and must be implemented by subclasses."). Subclasses override it to return their specific value.

​
Identifying instances at runtime

Because all map objects share the Instance base class, you can use instanceId to branch on object type without importing every subclass: 
import { CelariaMap } from "celaria-formats"
import fs from "node:fs"

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

for (const instance of map.instances) {
  switch (instance.instanceId) {
    case 0:
      console.log("Block at", instance.position)
      break
    case 1:
      console.log("Sphere at", instance.position)
      break
    case 2:
      console.log("Player spawn at", instance.position)
      break
    case 3:
      console.log("Barrier (wall) at", instance.position)
      break
    case 4:
      console.log("Barrier (floor) at", instance.position)
      break
    case 128:
      console.log("Tutorial hologram at", instance.position)
      break
  }
}
Alternatively, use instanceof checks against the concrete classes: 
import { Block, Sphere, PlayerSpawnPoint, Barrier, TutorialHologram } from "celaria-formats"

for (const instance of map.instances) {
  if (instance instanceof Block) {
    console.log("Block type:", instance.type)
  } else if (instance instanceof Barrier) {
    // instanceId is 3 (wall) or 4 (floor) depending on scale
    console.log("Barrier instanceId:", instance.instanceId)
  }
}

Block

Rectangular prism geometry with multiple surface types.

Sphere

Collectible red sphere placed in the level.

PlayerSpawnPoint

Marks where the player appears at the start of a run.

Barrier

Invisible physics barrier that slows players.

TutorialHologram

Hologram display object used in tutorial levels.

Map objects guide

Overview of all map object types and how to use them.

Build docs developers (and LLMs) love

Get started for freeTalk to us