Engine Plugins

Instructions

1. Create Plugins using the Factory Pattern

Feature packages (for example @repo/fps) generally follow a factory pattern. They are functions that accept configuration options and return a system definition (created via createSystem).

Structure:

import { createSystem, useSystem } from "@repo/engine";
import { z } from "zod";

// define schema
const Schema = z.object({
  enabled: z.boolean(),
  configValue: z.number(),
});

type PluginOptions = {
  initialValue: number;
  enableByDefault?: boolean;
};

// 1. Export the system factory
export const MyPlugin = (opts: PluginOptions) => {
  // 2. Return the createSystem call
  return createSystem("plugin:my-plugin")({
    system: Entrypoint,
    initialize: () => Initialize(opts), // Pass options to init if needed
    schema: {
      schema: Schema,
      default: {
        enabled: opts.enableByDefault ?? true,
        configValue: opts.initialValue,
      },
    },
  });

  function Initialize(options: PluginOptions) {
    // setup resources (heavy lifting here, not in factory)
  }

  function Entrypoint() {
    // Access own state
    const { data } = useSystem("plugin:my-plugin");

    if (!data.enabled) return;
    // ... logic
  }
};

2. Consume Plugins in App Entrypoints

Plugins are instantiated and passed to the createEngine function in the application.

import * as Engine from "@repo/engine";
import { MyPlugin } from "@repo/fps";

const engine = Engine.createEngine({
  systems: [
    // Instantiate the plugin with options
    MyPlugin({
      initialValue: 42,
      enableByDefault: true,
    }),
    // ... other systems
  ],
});

3. Follow Best Practices

1. Prefix Naming: Use a prefix (e.g., plugin:) for system names to distinguish them from app-specific systems.
2. Configuration: Expose necessary configuration via the factory arguments rather than hardcoding values.
3. Laziness: Initialize heavy resources (event listeners, large data structures) in the initialize hook, not the factory function itself.