miaoda-game-scheduler-core

Use this package for deterministic domain-time events in strategy and management games: research completion, construction, transport arrivals, taxes, cooldown deadlines, or world events. It is not a frame timer or wall-clock callback system.

Install and schedule events

pnpm add miaoda-game-scheduler-core

import { EventScheduler } from 'miaoda-game-scheduler-core';

const scheduler = new EventScheduler<{ projectId: string }>({
  now: 0,
  maxEventsPerAdvance: 1_000,
});
scheduler.schedule({
  id: 'research-steel',
  type: 'research-complete',
  due: 72,
  priority: 10,
  payload: { projectId: 'steel' },
});

const result = scheduler.advanceTo(100);
for (const event of result.events) commandEngine.dispatch(toCommand(event));

due, now, repeat intervals, priorities, occurrences, and insertion sequences are safe integers in a unit chosen by your game. Time never moves backward. Equal-due events run by priority descending, then insertion order ascending.

Operations and repeating events

| API | Purpose | | --- | --- | | schedule / cancel / reschedule | Manage unique pending event IDs | | peek / list | Inspect upcoming work in execution order | | step | Trigger exactly one occurrence and move time to its due value | | advanceTo | Trigger due occurrences up to a safety limit | | snapshot / loadSnapshot | Preserve exact queue order and repeat progress |

Repeating events use a positive integer interval and an optional number of repeats after the first occurrence. The next occurrence is queued before the current one is returned, so the host can immediately cancel or reschedule it.

Bounded offline catch-up

When advanceTo returns exhausted: true, process the returned batch and call it again with the same target. now remains at the last processed event and nextDue identifies remaining due work. This prevents a long offline period from freezing one frame.

Snapshots clone payloads with structuredClone; keep functions and engine objects out of them. The scheduler returns occurrences but never invokes callbacks or game rules. Convert occurrences into commands or apply them in the host simulation.