Create a plugin

Pascal plugins add new kinds of objects to a scene. A plugin can define how its objects are validated, rendered in 3D, drawn in floor plans, edited, and exposed to AI tools. It can also provide a panel in the editor. Start with the open-source Nature plugin. It is a complete, standalone example that adds trees, flowers, and grass to Pascal. Clone it when you want a working package to modify instead of starting from an empty repository.

git clone https://github.com/pascalorg/plugin-trees.git
cd plugin-trees
bun install

Follow the repository’s README for its current build, test, and local integration commands.

Plugin structure

Every plugin exports a manifest with a globally unique ID, the Pascal plugin API version it targets, and its node definitions:

import type { Plugin } from "@pascal-app/core";
import { plantDefinition } from "./plant";

export const gardenPlugin: Plugin = {
  id: "acme:garden",
  apiVersion: 1,
  nodes: [plantDefinition],
};

Use a namespaced ID such as company:plugin-name. The current apiVersion is 1; Pascal rejects plugins that target an incompatible version. Declare the @pascal-app/* packages used by your plugin as peer dependencies. The host must provide these packages so your plugin and the editor share one node registry. Bundling another copy of @pascal-app/core creates a separate registry and the plugin will not load correctly.

Define a node

The manifest’s nodes array contains NodeDefinition objects. Each definition starts with a schema and defaults, then opts into only the Pascal capabilities it needs.

import {
  BaseNode,
  nodeType,
  objectId,
  type NodeDefinition,
} from "@pascal-app/core";
import { z } from "zod";

const PlantNode = BaseNode.extend({
  id: objectId("plant"),
  type: nodeType("acme:plant"),
  species: z.string().default("fern"),
  height: z.number().positive().default(1),
});

export const plantDefinition = {
  kind: "acme:plant",
  schemaVersion: 1,
  schema: PlantNode,
  category: "furnish",
  defaults: () => ({
    object: "node",
    parentId: null,
    visible: true,
    metadata: {},
    species: "fern",
    height: 1,
  }),
  capabilities: {
    selectable: { hitVolume: "bbox" },
    duplicable: true,
    deletable: true,
  },
  presentation: {
    label: "Plant",
    paletteSection: "furnish",
  },
  renderer: {
    kind: "parametric",
    module: () => import("./plant-renderer"),
  },
  tool: () => import("./plant-tool"),
} satisfies NodeDefinition<typeof PlantNode>;

A definition can contribute any combination of:

Contribution	Purpose
`parametrics`	Inspector fields and an optional custom properties panel
`renderer`	A custom React Three Fiber renderer
`geometry`	Pure Three.js geometry for Pascal’s generic geometry system
`system`	Shared runtime or per-frame work for all nodes of this kind
`floorplan`	A 2D representation for floor-plan view and export
`tool` and `affordanceTools`	Placement and manipulation tools
`presentation`	Labels, icons, and editor palette placement
`mcp`	Descriptions used when AI tools inspect or create the node

Keep renderer and editor modules lazy, as shown above. This lets hosts avoid loading plugin UI and rendering code until it is needed.

Add an editor panel

The core manifest is independent of any editor UI. Export an EditorHostPanel separately if your plugin needs a sidebar panel:

import type { EditorHostPanel } from "@pascal-app/editor";

export const gardenPanel: EditorHostPanel = {
  id: "acme:garden:catalog",
  pluginId: "acme:garden",
  label: "Garden",
  description: "Place plants from the Acme garden collection.",
  creator: {
    name: "Acme",
    url: "https://acme.example",
  },
  pluginUrl: "https://github.com/acme/pascal-garden",
  icon: { kind: "iconify", name: "lucide:sprout" },
  component: () => import("./garden-panel"),
};

Register the panel with registerEditorHostPanel. Pascal uses creator and pluginUrl on the plugin detail page and loads the panel component inside an error boundary.

Load the plugin in a host

The host decides where plugins come from. Register discovery before importing the Pascal bootstrap module:

import { setPluginDiscovery } from "@pascal-app/core";
import { gardenPlugin } from "@acme/pascal-garden";

setPluginDiscovery(async () => [gardenPlugin]);

await import("./pascal-bootstrap");

Plugin loading is add-only for the browser session. Duplicate node kinds fail at startup instead of silently replacing each other.

The Plugins sidebar controls whether an already loaded plugin is enabled for the current project. Installing or uninstalling there does not download or remove an npm package. Uninstalling hides the plugin’s panel, tools, renderers, systems, and floor-plan output while preserving its nodes in the scene graph, so no project data is deleted.

Test your plugin

Before integrating a plugin into a host:

Validate every node against its schema and test any geometry or floor-plan functions as pure functions.
Add a registry test that loads the manifest and confirms each expected node kind is registered.
Load the plugin in a Pascal host with setPluginDiscovery and confirm the development console reports its ID and node count.
Create, save, reload, uninstall, and reinstall its nodes to check the complete project lifecycle.

The Nature plugin source demonstrates the manifest, node definitions, shared rendering systems, placement tools, editor panel, and tests together in one package.

Current API boundaries

Plugin API v1 does not add routes, application pages, host stores, or new material and floor-plan primitive types. A plugin can use its own state and can create materials inside its renderer or system, but it does not extend Pascal’s global stores. Keeping this boundary narrow lets the same plugin contract work for first-party and external nodes.

​Plugin structure

​Define a node

​Add an editor panel

​Load the plugin in a host

​Test your plugin

​Current API boundaries

Plugin structure

Define a node

Add an editor panel

Load the plugin in a host

Test your plugin

Current API boundaries