@web-engine-dev/scheduler

---

@web-engine-dev/scheduler / Scheduler

Interface: Scheduler<TContext>

The Scheduler manages system execution order and parallel execution.

Systems are organized into stages and ordered based on their dependencies. The scheduler uses topological sorting to determine execution order.

Example

interface GameContext {
  deltaTime: number;
  world: World;
}

const scheduler = createScheduler<GameContext>();

// Add systems
scheduler.addSystem(defineSystem('input', handleInput).inStage(CoreStages.FIRST).build());
scheduler.addSystem(defineSystem('physics', updatePhysics).after('input').build());
scheduler.addSystem(defineSystem('render', drawScene).after('physics').build());

// Run in game loop
function gameLoop(dt: number) {
  scheduler.run({ deltaTime: dt, world: gameWorld });
}

Type Parameters

TContext

TContext = unknown

Methods

addStage()

addStage(name, options?): void

Add a new stage to the scheduler.

Parameters

name

string

Stage name

options?

Positioning options

after?

string

before?

string

Returns

void

Example

// Add custom stage after UPDATE
scheduler.addStage('ai', { after: CoreStages.UPDATE });

// Add custom stage before LAST
scheduler.addStage('networking', { before: CoreStages.LAST });

---

addSystem()

addSystem(descriptor): void

Register a system with the scheduler.

Parameters

descriptor

SystemDescriptor<TContext>

System descriptor with metadata

Returns

void

Example

// Using defineSystem builder
scheduler.addSystem(
  defineSystem('movement', (ctx) => updatePositions(ctx))
    .inStage(CoreStages.UPDATE)
    .after('input')
    .build()
);

// Using direct descriptor
scheduler.addSystem({
  id: 'render',
  fn: renderScene,
  stage: CoreStages.POST_UPDATE,
});

---

addSystemSet()

addSystemSet(name, options?): void

Create a system set for grouping systems with shared ordering.

Parameters

name

string

Unique name for the set

options?

Ordering constraints for the set

runAfter?

string[]

runBefore?

string[]

Returns

void

---

addSystemToSet()

addSystemToSet(setName, systemId): void

Add a system to a system set.

Parameters

setName

string

Name of the system set

systemId

SystemId

ID of the system to add

Returns

void

---

build()

build(): void

Build the execution graph based on dependencies.

Called automatically by run() if needed. Call manually to validate the dependency graph or get the execution order before running.

Returns

void

Throws

If a cycle is detected

Example

scheduler.addSystem(systemA);
scheduler.addSystem(systemB);

// Validate dependencies before first run
scheduler.build();

// Inspect computed order
console.log(scheduler.getExecutionOrder());

---

getExecutionOrder()

getExecutionOrder(): SystemId[]

Get the computed execution order.

Returns

SystemId[]

---

getStages()

getStages(): Stage[]

Get all registered stages in order.

Returns

Stage[]

---

getSystemSets()

getSystemSets(): SystemSet[]

Get all registered system sets.

Returns

SystemSet[]

---

removeSystem()

removeSystem(id): void

Remove a system from the scheduler.

Parameters

id

SystemId

System identifier

Returns

void

---

run()

run(context): void | Promise<void>

Run all systems in order.

Automatically calls build() if needed. Returns a Promise if any system is async or parallel execution is enabled.

Parameters

context

TContext

Context passed to each system

Returns

void | Promise<void>

Example

// Synchronous execution
scheduler.run({ deltaTime: 0.016, world });

// Async execution (when systems return Promises)
await scheduler.run({ deltaTime: 0.016, world });