Background
- The current event system supports triggers like onStart, onKey, onMsg, and onTimer, but does not support Scratch
event_whengreaterthan (when value > threshold).
- This causes behavior gaps when importing Scratch projects.
- Reference project: https://goplus-builder.qiniu.io/project/sb2xbp/970974930
Goal
- Add a generic condition-based event trigger:
onCondition(condition, () => {
// ...
})
- Use this as the runtime mapping target for Scratch
event_whengreaterthan.
Requirements
- New Event API
- Add a public condition trigger registration API (suggested name:
OnCondition / onCondition).
- Accept a boolean condition function/expression and a callback.
- Trigger Semantics (critical)
- Use edge-trigger behavior: fire once on
false -> true.
- Do not fire repeatedly every frame while condition remains true.
- Allow retrigger only after condition returns to false and becomes true again.
- This matches expected Scratch behavior and avoids callback storms.
- Scratch Mapping
- Map
event_whengreaterthan(option, value) to onCondition.
- At minimum support:
option = timer: Timer() > value
option = loudness: Loudness() > value
- If loudness input is not fully implemented yet, document phased behavior clearly (e.g., timer first, loudness as TODO or non-triggering placeholder).
- Scheduling & Performance
- Evaluate conditions in the existing logic/event loop (no busy-wait).
- Keep per-frame checks lightweight and allocation-free where possible.
- Dispatch callbacks consistently with existing event execution model (async coroutine-based style).
- Lifecycle & Isolation
- Condition handlers should follow existing ownership semantics (sprite/game, clones, destroy, reload).
- Behavior under
stop all and related control-flow operations should be consistent with other hat events.
Acceptance Criteria
- A minimal
onCondition example can be written and triggers correctly.
event_whengreaterthan(timer, x) fires once when timer crosses threshold.
- No repeated firing while condition stays true.
- Re-fires after falling below threshold and crossing again.
- Coexists with existing events (
onStart, onTimer, onMsg, etc.) without regressions.
- Add tests for:
- Edge-trigger behavior
- Retrigger after reset
- Multi-instance/clone isolation
- Stop/reload lifecycle behavior
Background
event_whengreaterthan(when value > threshold).Goal
event_whengreaterthan.Requirements
OnCondition/onCondition).false -> true.event_whengreaterthan(option, value)toonCondition.option = timer:Timer() > valueoption = loudness:Loudness() > valuestop alland related control-flow operations should be consistent with other hat events.Acceptance Criteria
onConditionexample can be written and triggers correctly.event_whengreaterthan(timer, x)fires once when timer crosses threshold.onStart,onTimer,onMsg, etc.) without regressions.