@web-engine-dev/scheduler

System ordering and parallel execution for web-engine-dev. Provides a flexible scheduling system for ordering and executing systems with support for stages, dependencies, and parallel execution.

Features

• Execution Stages: Organize systems into ordered stages
• Dependency Resolution: Run after/before constraints
• Parallel Execution: Concurrent async execution for parallelizable systems (single-threaded)
• Fluent Builder: Easy system definition API
• Labels: Group systems for bulk operations

Installation

npm install @web-engine-dev/scheduler
# or
pnpm add @web-engine-dev/scheduler

Quick Start

import { createScheduler, defineSystem, CoreStages } from '@web-engine-dev/scheduler';

// Create scheduler
const scheduler = createScheduler();

// Define systems with fluent API
const inputSystem = defineSystem('input', (ctx) => {
  readInput(ctx.world);
})
  .inStage(CoreStages.FIRST)
  .build();

const movementSystem = defineSystem('movement', (ctx) => {
  applyMovement(ctx.world, ctx.deltaTime);
})
  .inStage(CoreStages.UPDATE)
  .after('input')
  .build();

// Add systems
scheduler.addSystem(inputSystem);
scheduler.addSystem(movementSystem);

// Build execution graph
scheduler.build();

// Run each frame
scheduler.run(context);

Configuration

const scheduler = createScheduler({
  enableParallelExecution: false,
  maxParallelWorkers: 0, // 0/undefined = unlimited when parallel execution enabled
  defaultStage: CoreStages.UPDATE,
});

API Reference

Built-in Stages

Stage	Description
FIRST	Runs before everything else
PRE_UPDATE	Preparation stage
UPDATE	Main update stage
POST_UPDATE	Cleanup and propagation
LAST	Runs after everything else

Scheduler Methods

Method	Description
addStage(name, opt)	Add custom stage
addSystem(desc)	Register a system
removeSystem(id)	Remove a system
build()	Build execution graph
run(context)	Execute all systems
getExecutionOrder()	Get computed order
getStages()	Get all stages

System Builder

defineSystem('mySystem', fn)
  .inStage('update') // Set stage
  .after('systemA') // Run after
  .before('systemB') // Run before
  .label('physics') // Add label
  .parallel() // Mark parallelizable
  .build();

Custom Stages

// Add stage after PRE_UPDATE
scheduler.addStage('physics', {
  after: CoreStages.PRE_UPDATE,
});

// Add stage before POST_UPDATE
scheduler.addStage('rendering', {
  before: CoreStages.POST_UPDATE,
});

Parallel Execution

const scheduler = createScheduler({
  enableParallelExecution: true,
  maxParallelWorkers: 4, // Concurrency limit for async systems
});

// Mark systems as parallelizable
const parallelSystem = defineSystem('parallel', fn).parallel().build();

// Note: Parallel execution runs async systems concurrently on the main thread.
// For worker-thread parallelism, use the ECS ParallelScheduler.

Execution Order

// Systems run in topological order
// respecting stages and dependencies

scheduler.addSystem(defineSystem('A', fnA).inStage('update').build());
scheduler.addSystem(defineSystem('B', fnB).inStage('update').after('A').build());
scheduler.addSystem(defineSystem('C', fnC).inStage('update').after('A').build());

// Execution order: A, then B and C (potentially parallel)