DevelopersEarly development

Build the

Everything you need to get Pulsar building, find your way around a workspace of hundreds of crates, and land your first change. The architecture is still moving, so the best time to shape it is now.

Set up your environment Browse the source

zero to running

$ git clone --recursive https://github.com/Far-Beyond-Pulsar/Pulsar-Native
$ cd Pulsar-Native
# opens the voxel planet example in the editor
$ just example voxel_planet

Needs Rust, just and (on Linux) a few system packages: see step 01

Rust

the whole engine, editor included

25+

first-party plugins, each its own repo

MIT

licensed, developed in the open

Linux · Windows · macOS

Linux gates every PR; all three run on main

01 / Quick start

From clone to a running editor.

The repository is a large Cargo workspace whose plugins and renderer are git submodules, so a plain clone will not build: clone recursively.

Get the code

shell

$ git clone --recursive https://github.com/Far-Beyond-Pulsar/Pulsar-Native
# already cloned without --recursive?
$ just submodule-init

Install the toolchain

Rust installs the pinned version from rust-toolchain.toml on first build, with clippy, rustfmt and the wasm target. Install just for the shortcuts below. On Ubuntu you also need:

ubuntu

$ sudo apt install -y gcc g++ clang libfontconfig-dev libwayland-dev \
$   libwebkit2gtk-4.1-dev libxkbcommon-x11-dev libx11-xcb-dev \
$   libssl-dev libzstd-dev vulkan-validationlayers libvulkan1

Build and run

shell

$ just check      # cargo check, fastest feedback
$ just run        # the editor
$ just example voxel_planet
# voxel_moon, voxel_desert and voxel_blocks are the other examples

Before you open a PR

shell

$ just fmt        # formats Pulsar-Native's own crates
$ just clippy     # warnings are errors
$ just test       # cargo test --workspace

A GPU with Vulkan, Metal or DX12 support is needed to run the editor. Tests that need a GPU are excluded from CI. The full command list is in the justfile.

02 / Where to contribute

Pick the layer that interests you.

You do not need to understand all of it. Each area has its own boundaries and its own documentation.

Engine core

SceneDB, the archetype ECS, reflection, the virtual filesystem, scripting and the code generator that turns your project into a standalone Rust crate.

crates/core

Helio renderer

The GPU-driven renderer: passes, features, WGSL and render graphs. Rendering work has its own architecture skill you must read first.

Helio

Plugins

Every object kind (meshes, lights, sky, water, voxels, physics, animation) is a plugin with its own repository. Small, self-contained, a good first contribution.

plugins/vendor

Editor and UI

The level editor, file manager, inspector and the rest of the editor chrome, built on WGPUI, a GPU-accelerated UI framework forked from Zed's GPUI.

crates/editor

Docs and website

Documentation, this site and the blog are all Next.js and Markdown. Fix a page, write a guide, or document a system you just learned.

far-beyond-pulsar.github.io

Testing and reports

Try the examples, break them and report what you find. Clear reproduction steps on a hardware and driver matrix are worth a lot to a renderer.

Issues

03 / The shape of it

The engine is a
factory for your game.

Pulsar does not run your game inside the editor. On export it generates a separate Rust crate holding your reflected types, blueprints, scenes and asset manifests, and that crate compiles on its own against only the runtime crates it uses. If it compiles, your data matches the engine.

The editor is built the same way, and an object's component is one typed value: edited in the inspector, ticked at runtime, mirrored to GPU rows and drawn by Helio.

Read the philosophy

Workspace map

crates/core

Engine fundamentals

ECS, reflection, filesystem, LSP, settings, scripting, the plugin manager

crates/subsystems

Integration crates

Physics (Rapier), scene graph, the glue between engine and renderer

crates/editor

Editor panels

Level editor, inspector, file manager, log viewer, settings: the workspace chrome

crates/ui

WGPUI

Vendored GPU-accelerated UI framework and component library, as submodules

crates/agent-providers

AI backends

One crate per supported provider, behind a shared chat core

crates/third-party

Vendored deps

Graphy (node graphs), config and other small path dependencies

plugins/vendor

Plugins

Every object kind and editor tool, each its own repository and a workspace member

crates/renderer/helio

Helio

The renderer, a submodule. It knows no object kind: plugins contribute features

04 / Anatomy of a plugin

Every object kind has the same five crates.

Learn one plugin and you can read them all. Hosts reach a plugin only through its root crate, and a disabled plugin is simply absent: its classes, features, settings and editors are not registered.

api

helio-<kind>-api

Contracts other plugins read: keys, row ABIs, WGSL

feature

helio-pass-*

The Helio feature and its render passes

component

<kind>_component

SceneDB components, methods, runtime, file formats

editor

<kind>_editor

Level editor UI, tools, thumbnails

root

<kind>_plugin

The registrations: the one place the plugin contributes anything

pulsar-plugin.toml

# beside the plugin's crates
id = "pulsar.fog"            # the one stable identity
name = "Fog"
description = "Global and local fog media"
enabled_by_default = true
requires = []                # plugins it cannot work without
root = "fog_plugin"          # the root crate in this directory

Projects switch plugins in Pulsar.toml. First-party plugins live in their own Plugin_<Kind> repositories and are pinned into the main workspace as submodules. Start with the plugin system guide.

05 / Workflow

How a change gets in.

The day-to-day loop is short. The rules below are the ones that most often surprise new contributors.

Commands

just checkcargo check across the workspace

just build / releaseDebug or release build of the editor

just testcargo test --workspace

just clippyClippy with warnings denied

just fmtFormat Pulsar-Native's own crates

just conformanceInterpreted vs generated Rust, debug and release

just submodule-initgit submodule update --init --recursive

just check-submodule-pinsEvery submodule pinned to a commit on its upstream main

House rules

01
Submodule changes merge dependency-first
Merge the plugin or Helio PR into its own main, re-pin the submodule to that commit, then merge the Pulsar-Native PR.
02
Branch pushes do not run CI, PRs do
A new push cancels the superseded run. Draft and docs-only PRs skip CI, so open a draft while you iterate.
03
Linux is the gate
fmt, clippy, guards and nextest run on Linux per PR. Windows and macOS compile checks run on main and nightly.
04
TODOs need an issue
A TODO comment must reference an issue (#123 or a URL). The check scans tracked source in the main repository.
05
Rendering work loads the Helio skill first
Anything touching Helio, its plugins, WGSL, render graphs or GPU rows. Bug fixes and small changes count too.