⚙️ Requirements

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

🧭 Workspaces

Every workspace name below drops the @jolly-pixel/ scope: network is @jolly-pixel/network. Workspaces are grouped by sub-domain. Each arrow shows what one sub-domain provides to another.

🤝 Collaboration

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

🎨 Authoring

Shell

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

Editors and formats

Each editor is an editor.<name> workspace, and the formats it owns (the asset kinds it reads and writes, and that asset-server stores) live in asset.<name> workspaces linked from each extension. Editors also read the formats their documents link, such as the .pixelart textures used by voxel maps and models.

• Voxel map - Voxel-terrain editor for .voxelmap.json worlds and .blockset.json blocksets
• Voxel model - Low-polygon 3D model editor for .voxelmodel.json models and .voxelanim.json animation sets
• Pixel art - Pixel-art texture editor for .pixelart textures, built on pixel-draw.renderer
• Terrain 🚧 - Heightfield terrain editor for .terrain.json terrains
• Scene 🚧 - Actors, components and environment, saved as .scene.json scenes

UI

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

🗄️ Asset Management

• asset - Asset references, catalogs and loading orchestration for browser and Node.js
• asset-server - Event-sourced asset projection, reconciliation and catalog delivery
• asset-source - Physical asset storage (filesystem, memory, IndexedDB)
• 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

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

Renderers

• voxel.renderer - Voxel engine and renderer
• terrain.renderer - Heightfield terrain engine and renderer 🚧
• pixel-draw.renderer - Pixel-art canvas drawing and rendering

🧩 Shared libraries

Generic packages used by more than one sub-domain.

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

🛠️ Tooling

• bench - Benchmarking harness and CLI
• 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

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