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.
Every object placed in a Celaria map is an instance stored in map.instances. Each instance has a numeric instanceId that identifies its type during serialization. All instances extend Instance, which provides a position property as a [x, y, z] array where the z-axis is the gravity axis.
The following sections cover each instance type, its properties, and how to create and configure it.
Block (instanceId: 0)
Block represents solid rectangular prism geometry. It is the most common instance type and the only one with a type property that controls its in-game behavior.
Block types
Block.types key | Value | Color | Description |
|---|
plain | 0 | — | Standard level geometry with no special properties |
goal | 1 | Red | The end goal of a map |
jump | 2 | Green | Lets the player jump higher while touching it |
speed | 3 | Yellow | Speeds up players who walk on it |
ice | 4 | Blue | Difficult to walk on and climb |
checkpoint | 5 | Red | A checkpoint in the map’s progression sequence |
Properties
| Property | Type | Default | Description |
|---|
position | [x, y, z] | [0, 0, 0] | World position; z is the gravity axis |
scale | [x, y, z] | [2, 2, 2] | Dimensions of the block |
rotation | number | 0 | Rotation in radians |
type | number | Block.types.plain | Block type from Block.types |
medalTimes | MedalTimes | undefined | Required for checkpoint/goal blocks in CelariaMap |
Example
import { Block } from "celaria-formats"
// Plain block
const platform = new Block()
platform.position = [0, -2, 0]
platform.scale = [10, 1, 10]
// Jump block
const jumpPad = new Block(Block.types.jump)
jumpPad.position = [5, 0, 0]
// Checkpoint block with medal times (required in CelariaMap)
const checkpoint = new Block(Block.types.checkpoint)
checkpoint.position = [10, 0, 0]
checkpoint.medalTimes = {
platinum: 300, // ticks
gold: 500,
silver: 800,
bronze: 1200,
}
map.instances.push(platform, jumpPad, checkpoint)
map.checkpointOrder.add(checkpoint)
Sphere (instanceId: 1)
Sphere is a collectible red gem placed in the world. It has only a position — no rotation or scale.
Properties
| Property | Type | Default | Description |
|---|
position | [x, y, z] | [0, 0, 0] | World position; z is the gravity axis |
Example
import { Sphere } from "celaria-formats"
const gem = new Sphere()
gem.position = [3, 1, 0]
map.instances.push(gem)
PlayerSpawnPoint (instanceId: 2)
PlayerSpawnPoint marks where the player appears at the start of a map. Each map should have at least one spawn point.
Properties
| Property | Type | Default | Description |
|---|
position | [x, y, z] | [0, 0, 0] | World position; z is the gravity axis |
rotation | number | 0 | Facing direction in radians |
Example
import { PlayerSpawnPoint } from "celaria-formats"
const spawn = new PlayerSpawnPoint()
spawn.position = [0, 0, 1]
spawn.rotation = 0
map.instances.push(spawn)
Barrier (instanceId: 3 or 4)
Barrier is an invisible collision surface used to create walls and floors without visible geometry. Its instanceId is determined by the shape of its scale property:
scale = [x, 0, z] — wall (instanceId 3)scale = [x, y, 0] — floor (instanceId 4)
Properties
| Property | Type | Default | Description |
|---|
position | [x, y, z] | [0, 0, 0] | World position; z is the gravity axis |
scale | FlatVector3 | [1, 0, 1] | Dimensions; must follow the wall or floor pattern |
rotation | number | 0 | Rotation in radians |
If scale does not match either the wall pattern ([x, 0, z]) or the floor pattern ([x, y, 0]), accessing instanceId or calling serialize throws Error("I can't decide if I am a wall or a floor."). Always set exactly one of the middle or last scale component to 0.
Example
import { Barrier } from "celaria-formats"
// Wall barrier (instanceId: 3)
const wall = new Barrier()
wall.position = [0, 0, 5]
wall.scale = [10, 0, 3] // x and z set — wall
// Floor barrier (instanceId: 4)
const floor = new Barrier()
floor.position = [0, -1, 0]
floor.scale = [10, 10, 0] // x and y set — floor
map.instances.push(wall, floor)
TutorialHologram (instanceId: 128)
TutorialHologram is a special holographic object used in tutorial maps. It requires a type argument in its constructor.
Properties
| Property | Type | Default | Description |
|---|
type | number | — | Hologram type (required) |
position | [x, y, z] | [0, 0, 0] | World position; z is the gravity axis |
scale | [x, y, z] | [0, 0, 0] | Dimensions of the hologram |
rotation | number | 0 | Rotation in radians |
Example
import { TutorialHologram } from "celaria-formats"
const hologram = new TutorialHologram(1)
hologram.position = [0, 2, 0]
hologram.scale = [1, 1, 1]
hologram.rotation = 0
map.instances.push(hologram)
Adding all instance types to a map
import fs from "node:fs"
import {
CelariaMap,
Block,
Sphere,
PlayerSpawnPoint,
Barrier,
TutorialHologram,
} from "celaria-formats"
const map = new CelariaMap()
map.name = "Example Map"
// Spawn
const spawn = new PlayerSpawnPoint()
spawn.position = [0, 1, 0]
map.instances.push(spawn)
// Floor platform
const platform = new Block(Block.types.plain)
platform.position = [0, 0, 0]
platform.scale = [20, 1, 20]
map.instances.push(platform)
// Collectible gem
const gem = new Sphere()
gem.position = [3, 2, 0]
map.instances.push(gem)
// Invisible wall
const wall = new Barrier()
wall.position = [10, 0, 0]
wall.scale = [1, 0, 20]
map.instances.push(wall)
// Checkpoint
const checkpoint = new Block(Block.types.checkpoint)
checkpoint.position = [5, 1, 0]
checkpoint.medalTimes = { platinum: 200, gold: 400, silver: 700, bronze: 1000 }
map.instances.push(checkpoint)
map.checkpointOrder.add(checkpoint)
// Goal (last in checkpoint order)
const goal = new Block(Block.types.goal)
goal.position = [15, 1, 0]
goal.medalTimes = { platinum: 200, gold: 400, silver: 700, bronze: 1000 }
map.instances.push(goal)
map.checkpointOrder.add(goal)
fs.writeFileSync("./example.cmap", map.serialize(2))