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.

Block is the most commonly used map object in Celaria. It represents a solid rectangular prism — the fundamental building block of every level. Blocks can serve as plain geometry, goal markers, jump pads, speed surfaces, ice surfaces, or checkpoints, all controlled by the type property. Block extends Instance and has an instanceId of 0.

​
Constructor

new Block(type?)
​
type
number
default:"Block.types.plain"
The surface type of the block. Must be one of the values in Block.types. Defaults to Block.types.plain (0).

​
Properties

​
position
[number, number, number]
World-space position inherited from Instance. Defaults to [0, 0, 0]. Z is the gravity axis.
​
scale
[number, number, number]
The dimensions of the block along each axis. Defaults to [2, 2, 2].
​
rotation
number
Rotation of the block in the horizontal plane, in radians. Defaults to 0.
​
type
number
The surface type of the block. Use Block.types.* constants to set this value. See the block types table below for the full list.
CelariaMap may override type during map serialization for checkpoint and goal blocks. Avoid relying on type being the value you set after a round-trip through serialization if the block is positioned as a checkpoint or goal.
​
medalTimes
{ platinum: number, gold: number, silver: number, bronze: number }
Medal time thresholds associated with this block, measured in ticks. This field is populated and required by CelariaMap for blocks with type Block.types.checkpoint or Block.types.goal. It is undefined for all other block types.
KeyTypeDescription
platinumnumberPlatinum medal threshold in ticks
goldnumberGold medal threshold in ticks
silvernumberSilver medal threshold in ticks
bronzenumberBronze medal threshold in ticks

​
Getters

​
instanceId
0
Always returns 0. Used during binary serialization to identify this object as a Block.

​
Block types

Block.types is a static object containing named constants for all supported block surface types.
ConstantValueIn-game appearanceBehavior
Block.types.plain0DefaultStandard level geometry with no special properties
Block.types.goal1RedFinish block — the space above it is the actual goal zone
Block.types.jump2GreenPlayers jump higher when touching this surface
Block.types.speed3YellowSpeeds up players who walk on this surface
Block.types.ice4BlueDifficult to walk on and climb; slippery physics
Block.types.checkpoint5Red/purpleMap checkpoint; requires medalTimes to be set

​
Examples

​
Creating blocks of different types

import { Block } from "celaria-formats"

// Plain geometry block
const platform = new Block()
platform.position = [0, 0, -2]
platform.scale = [10, 10, 1]

// Jump pad
const jumpPad = new Block(Block.types.jump)
jumpPad.position = [4, 0, -2]
jumpPad.scale = [2, 2, 0.5]

// Ice surface
const icePlatform = new Block(Block.types.ice)
icePlatform.position = [-6, 0, -2]
icePlatform.scale = [4, 4, 1]

// Speed strip
const speedStrip = new Block(Block.types.speed)
speedStrip.position = [0, 8, -2]
speedStrip.scale = [2, 6, 0.5]

​
Adding a checkpoint with medal times

import { Block, CelariaMap } from "celaria-formats"

const map = new CelariaMap()
map.name = "My Level"

const checkpoint = new Block(Block.types.checkpoint)
checkpoint.position = [0, 20, 0]
checkpoint.scale = [4, 4, 4]
checkpoint.medalTimes = {
  platinum: 300,   // game ticks
  gold:     600,
  silver:   900,
  bronze:   1500,
}

const goal = new Block(Block.types.goal)
goal.position = [0, 50, 0]
goal.scale = [4, 4, 4]
goal.medalTimes = {
  platinum: 1200,
  gold:     1800,
  silver:   2400,
  bronze:   3600,
}

map.instances.push(checkpoint)
map.instances.push(goal)
map.checkpointOrder.add(checkpoint)
map.checkpointOrder.add(goal)

​
Filtering blocks by type

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

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

const checkpoints = map.instances.filter(
  instance => instance instanceof Block && instance.type === Block.types.checkpoint
)

console.log(`Map has ${checkpoints.length} checkpoint(s)`)

Instance

Abstract base class that Block extends.

Map objects guide

How to add and configure map objects.

Types reference

Vector3 and MedalTimes type definitions.

CelariaMap

Finalized map format that serializes blocks and medal times.

Build docs developers (and LLMs) love

Get started for freeTalk to us