An ergonomic, runtime agnostic scheduler for Jecs

Features

1. Phases

Rubine uses phases to bind systems to events and order them.

Phases live in rubine's Jecs world, having the Phase tag, and either the Event component or a dependant pair (pair(DependsOn, another_phase)).

Phases can be ordered implicitly:

local event = signal()
local my_phase = scheduler.phase("my_phase", event)
local my_phase_b = scheduler.phase("my_phase_b", event) -- Ordered after `my_phase`

or explicitly:

local event = signal()
local my_phase = scheduler.phase("my_phase", event)
local my_phase_b = scheduler.phase("my_phase_b", my_phase) -- Ordered after `my_phase`

Multiple phases cannot be bound to the same event, but instead depend on one another.

2. Systems

Systems are bound to phases. Whenever an event the system is (indirectly) on is fired, it's ran.

Systems live in rubine's Jecs world, having the System component describing it, and a pair describing what phase it runs on (pair(DependsOn, phase)).

Systems are created with scheduler.on:

local function system()
end

local my_system = scheduler.on(my_phase, system)

can have their execution paused:

scheduler.pause(my_system)

and unpaused:

scheduler.unpause(my_system)

Systems also contain data about the moment they started running and ended, being reset on every run.

type System = {
    run: (...any) -> (),
    paused: boolean,
    frame_start: number,
    frame_end: number,
}

Systems cannot yield without _G.__RUBINE_DEBUG_MODE being true.

3. Hooks

Hooks are available via the abstractions module. Under the hood, they use Jecs hooks to observe changes to the world and run user defined callbacks on them.

With them, you can hook onto system calls

abstractions.hook("SystemCall", function(system_id: Entity, system_data: System, previous_data: System)
end)

system additions

abstractions.hook("SystemAdd", function(system_id: Entity, system_data: System)
end)

system removals

abstractions.hook("SystemRemove", function(system_id: Entity)
end)

and all system changes

abstractions.hook("SystemChange", function(systme_id: Entity, system_data: System, previous_data: System)
end)

4. Pipes

Pipes are a tiny abstraction over phases, mainly meant to be used with pipelines. All pipe names are unique, being the script name and the line number of where they were defined.

local my_pipe = abstractions.pipe()
scheduler.phase(my_pipe, event)

5. Pipelines

Pipelines are an abstraction over phases, allowing for handy implicit ordering.

local pipe_a = abstractions.pipe()
local pipe_b = abstractions.pipe()
local pipe_c = abstractions.pipe()

-- Pipe A is bound to the given event
-- Pipe B depends on Pipe A
-- Pipe C depends on Pipe B
abstractions.pipeline()
    :with(pipe_a)
    :with(pipe_b)
    :with(pipe_c)
    :build(event)

Installation

Pesde

Available for use in standalone luau.

1. pesde add mark_marks/rubine
2. pesde install

Wally

Available for use in Roblox.

1. Add it to your wally manifest

[dependencies]
rubine = "mark-marks/rubine@LATEST" # Replace LATEST with the latest version

2. wally install

NPM (roblox-ts)

1. npm add @rbxts/rubine
2. npm install

Honorable Mentions

• Abstractions were inspired by the ecs agnostic Planck scheduler.
• Logo was kindly created by alice.