Use when adding, refactoring, auditing, or testing ESIR runtime code that receives Factorio research completion events, handles on_research_finished or on_scripted_research_burst, reacts to scripted research floods, updates force-derived research caches, buffs, milestones, notifications, damage/status refreshes, or plans QC around the scripted research burst UPS saver.
Installation
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Use when adding, refactoring, auditing, or testing ESIR runtime code that receives Factorio research completion events, handles on_research_finished or on_scripted_research_burst, reacts to scripted research floods, updates force-derived research caches, buffs, milestones, notifications, damage/status refreshes, or plans QC around the scripted research burst UPS saver.
ESIR Research Events
Use this skill before changing research-aware runtime code. ESIR has a deliberate UPS saver for event.by_script research floods, so normal research handling and scripted burst handling must be designed together.
Dispatch Model
Keep exotic-space-industries-remembrance/control.lua as the only top-level script.on_event(defines.events.on_research_finished, ...) registration.
For event.by_script, the dispatcher calls queue_scripted_research_burst(e) and returns. The queued state lives under storage.ei.scripted_research_burst, is coalesced per force, and is scheduled through the shared delayed-bucket helpers.
For normal research, the dispatcher first calls flush_scripted_research_burst_for_force(research_force.index, e.tick) if that force has a pending scripted burst, then fans out to module on_research_finished(event) handlers.
The on-tick backstop calls flush_due_scripted_research_bursts(event.tick, state) when the next due burst matures. Burst fan-out calls module on_scripted_research_burst(...) handlers.
Treat the current dispatcher names as canonical search anchors: queue_scripted_research_burst, flush_scripted_research_burst_for_force, flush_due_scripted_research_bursts, on_research_finished, and on_scripted_research_burst.
Handler Rules
Any module added to normal research fan-out must explicitly decide whether scripted research should reach it through on_scripted_research_burst.
Add or update on_scripted_research_burst when research handling changes caches, notifications, milestones, buffs, damage/statuses, unlocked-tech scans, or any other force-derived state that could be stale after many scripted completions.
Prefer force-wide refresh, rebuild, or scan behavior in burst handlers. Do not rely on a single event.research.name; a scripted flood may represent many completed technologies.
Keep per-technology delta logic in on_research_finished(event) only when it is safe for normal one-tech completions. If scripted floods still need a narrow hint, follow the Tesla variant-sync precedent: store the smallest boolean or scalar needed on the burst entry and pass it through the existing burst dispatch.
Validate force, force.valid, and force.technologies before scanning research state in burst handlers.
Keep return values simple (true when useful work happened, false or nil otherwise). Do not make control.lua depend on broad return semantics unless the dispatcher truly needs them.
If a module gets on_research_finished, update its file-map forwarded_events comment and decide on the burst hook in the same patch.
Do not add parallel research dispatchers, ad hoc tick queues, on_nth_tick burst drains, or bypasses around storage.ei.scripted_research_burst.
Use event.tick in event callbacks and pass current_tick through burst work when timing matters. Fall back to game.tick only outside event context.
Use esir-lua-types when adding or changing research handler signatures, burst option payloads, or storage shapes.
Use factorio-lua-assumptions before applying generic Lua event/storage advice to Factorio runtime code.
QC Guidance
For deterministic scripted flood coverage, use the helper documented by esir-dev: references/scripted-research-qc-helper.md.
Stage the zzz-scripted-research-qc helper only for explicit scripted-research QC runs, then remove or disable it before unrelated QC.
Inspect the research hitch/scripted snapshot fields when validating the burst saver: pending force count, next due tick, due bucket counts, tech-scaling snapshot, Tesla status, and EM train status.
Normal research behavior still needs ordinary research-completion coverage; the scripted helper only proves the event.by_script flood path.
