⚙️ Requirements

• Node.js version 24 or higher
• pnpm v12+ for workspaces (the repository pins it through the packageManager field)

🧭 Workspaces

Workspaces are grouped by sub-domain. Each arrow shows what one sub-domain provides to another.

🤝 Collaboration

• @jolly-pixel/network - Rooms, peers and state sync for the collaborative editors
• @jolly-pixel/accounts - User accounts and session tokens for JollyPixel servers
• @jolly-pixel/history - Command documents and per-person undo history that survives collaboration

🎨 Authoring

Shell

• @jolly-pixel/studio - One project, its assets and one editor per tab
• @jolly-pixel/editor.host - Shared launch, session and runtime boot for the editors

Editors and formats

Each editor is listed with the formats it owns: the asset kinds it reads and writes, and that asset-server stores. Editors also read the formats their documents link, such as the .pixelart textures used by voxel maps and models.

• @jolly-pixel/editor.voxel-map - Voxel-terrain editor
  • @jolly-pixel/asset.voxel-map - .voxelmap.json worlds and the .blockset.json blocksets
• @jolly-pixel/editor.voxel-model - Low-polygon 3D model editor
  • @jolly-pixel/asset.voxel-model - .voxelmodel.json models
  • @jolly-pixel/asset.voxel-animation - .voxelanim.json animation sets
• @jolly-pixel/editor.pixel-art - Pixel-art texture editor (built on pixel-draw.renderer)
  • @jolly-pixel/asset.pixel-art - .pixelart textures
• @jolly-pixel/editor.terrain - Heightfield terrain editor 🚧
  • @jolly-pixel/asset.terrain - .terrain.json heightfield terrains 🚧
• @jolly-pixel/editor.scene - Scene editor: actors, components and environment 🚧
  • @jolly-pixel/asset.scene - .scene.json scenes 🚧

UI

• @jolly-pixel/ui - Design system (declarative UI components and a facade API)
• @jolly-pixel/resize-handle - Resize handles and splitters
• @jolly-pixel/console - Command palette and developer console for the editors
• @jolly-pixel/lantern - Guided tours for the editors

🗄️ Asset Management

• @jolly-pixel/asset - Asset references, catalogs and loading orchestration for browser and Node.js
• @jolly-pixel/asset-server - Event-sourced asset projection, reconciliation and catalog delivery
• @jolly-pixel/asset-source - Physical asset storage (filesystem, memory, IndexedDB)
• @jolly-pixel/event-store - Append-only event log (event sourcing)

🏗️ Build

Planned. It will turn a project's assets into the catalog manifest the runtime loads.

🎮 Runtime

Core

• @jolly-pixel/runtime - Game runtime for web browsers and Electron
• @jolly-pixel/engine - Minimal ECS framework on top of Three.js
• @jolly-pixel/loop - Frame scheduling and time primitives (FrameScheduler, GameLoop)
• @jolly-pixel/controls - Input controls (screen, mouse, touchpad, keyboard, gamepad)

Renderers

• @jolly-pixel/voxel.renderer - Voxel engine and renderer
• @jolly-pixel/voxel.tiled - Tiled map import for voxel.renderer 🚧
• @jolly-pixel/terrain.renderer - Heightfield terrain engine and renderer 🚧
• @jolly-pixel/pixel-draw.renderer - Pixel-art canvas drawing and rendering

🧩 Shared libraries

Generic packages used by more than one sub-domain.

• @jolly-pixel/three - Three.js components and utilities (grid, transform controls, selection highlight...)
• @jolly-pixel/color - Color parsing, palettes, color spaces and conversions
• @jolly-pixel/image - PNG codecs and browser raster decoding

🛠️ Tooling

• @jolly-pixel/bench - Benchmarking harness and CLI
• @jolly-pixel/e2e - Playwright config, locators and editor fixtures for e2e suites

💃 Getting started

Public packages are published on npm and can be installed with npm or yarn. The studio, editors, formats, tooling and 🚧 renderers are private workspaces.

$ npm i @jolly-pixel/engine
# or
$ yarn add @jolly-pixel/engine

Build

To install and compile all workspaces, just run the following command at the root

$ pnpm install
$ pnpm run build

Run

@jolly-pixel/studio is the full application

$ pnpm --filter @jolly-pixel/studio dev

Test

Run tests for one workspace, then run the repository type checks:

$ pnpm --filter <workspace> test
$ pnpm run typecheck

Linter

Lint all workspaces with oxlint (the script also checks package exports and CSS):

$ pnpm run lint

📦 Publishing package

Each public package has its own prepublishOnly script that builds the TypeScript source before publishing.

$ pnpm publish --filter <workspace>

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Thomas.G 💻 📖 🐛 ⚠️ 🛡️

Alexandre Malaj 💻 📖 🐛

PierreDemailly 💻

Clement Gombauld 💻

📃 License

MIT