Introduce cross-world scheduling and system registration

[waynemwashuma]

Objective

Introduce first-class support for cross-world schedules and systems, enabling logic to operate on two worlds while preserving the existing scheduling model.

Solution

Changes Made

The following changes were introduced:

• Added CrossWorldSchedule for executing systems that operate across two worlds.

• Introduced CrossWorldSystemFunc and the associated scheduling APIs:

  • App.registerCrossWorldSchedule()
  • App.registerCrossworldSystem()

• Extended Scheduler to manage both standard and cross-world executables independently.

• Enhanced SchedulerBuilder to:

  • Build cross-world schedules.
  • Resolve ordering constraints between cross-world systems.
  • Validate target and source world configuration.

• Updated Executable to support custom schedule types and source worlds.

• Modified the default runner to:

  • Execute cross-world schedules before standard schedules.
  • Resolve both target and source worlds at runtime.

• Added regression tests verifying cross-world execution order.

Why This Approach

• Keeps cross-world execution isolated from standard schedules without changing existing behavior.
• Reuses the existing scheduling infrastructure, including ordering semantics and validation.
• Provides a clean API for synchronization and data transfer between worlds.
• Ensures deterministic execution by running cross-world schedules before per-world schedules.

Notes

• Cross-world schedules require both a target world and a source world.
• Cross-world systems support the same before/after ordering semantics as standard systems.
• Existing schedules and systems continue to function unchanged.

Showcase

Before

// Not supported

After

class ExtractSchedule {}
class RenderWorld {}
class MainWorld {}

app
  .registerCrossWorldSchedule({
    label: ExtractSchedule,
    world: RenderWorld,
    sourceWorld: MainWorld
  })
  .registerCrossworldSystem({
    schedule: ExtractSchedule,
    system: extractVisibleEntities
  })

// Cross-world systems receive both worlds:
function extractVisibleEntities(renderWorld, mainWorld) {
  // Synchronize data between worlds.
}

Migration Guide

No migration required.

Existing schedules and systems continue to work as before. Cross-world scheduling is an additive feature that can be adopted incrementally.

Checklist

• I have updated the documentation accordingly.
• I have added tests to cover my changes.