Signals by warquys · Pull Request #52 · outfox/fennecs

warquys · 2026-08-22T00:30:31Z

Add On method returning a Signale. On as the same signature than Add. Meaning you can specify if you whant to handle relation.

// This an exemple, avoid lambda you can't remove the handler
world.On<Position>().Added   += (EntityRef e, ref Position p) => ...;
world.On<Position>().Removed += (EntityRef e, in  Position p) => ...;

Signale are contained in a Dictionary with for key the type of the compoent tarrget. Then a list do the job to raise every matching (base on the Expression).

World lock are by default on signal to avoid raising other signale will handling one. This also allow to pass a EntityRef.

Open question:

Should the Expression follow a patern ? Or give a new Signale each time? Currently the way of storing Expression kind a bad. For exemple: 2 differente Expression matching a same case, it will be raised depending base on the first call of On.
Should orphan Signals be added back to the World? Or should we only count alive signal and remove clean of the GC?
For new we only count alive signal. Orphan Signal get remove of the list of Signal to free up space (like GC imply).
Should the Exception expose a method to allow for continuation of the operation? Or finishing the operation should not be an option and it should be done whatever.
Actually Exception are raise and there is now way to fix up/continue the current Action except retrying.

What is done to do:

There is no incorrect information in it. However, I didn't like the way Claude wrote it. I did not rewrites theme. I make a lot of spelling mistakes, and it would take me some time to correct them. So, since the methods are still likely to change, the documentation will be done at the end.

Summary by cubic

Adds component lifecycle signals so subscribers can observe structural changes across entity, batch, spawn, despawn, relation, and link operations.

World.On<T>(Match) returns a signal memoized per expression, with AfterAdded and BeforeRemoved handlers; removal handlers receive a RemoveCause.
Handlers fire once per operation on index-aligned spans of Entity and component values; AfterAdded values are a writable slice of storage.
Structural changes handlers request are deferred until dispatch completes; a nested-drain guard prevents stack overflow during bulk deferred operations.
Handler failures surface as SignalException; failures during deferred catch-up are marked Deferred = true.
Replacements and tolerated no-op removals remain silent. World.GC drops signals with no subscribers weakly: a signal still held by user code is revived by On<T>(), and the runtime collects signals nobody references.
Dispatch runs on a single thread even when a parallel job requested the changes; only the batch path allocates, and it rents its capture buffer.

Benchmarks on both this branch and main measure what having the feature costs when nobody subscribes. Documentation covers events and EntityRef, and tests exercise dispatch under parallel job runners.

^{Written for commit f7c1a4b. Summary will update on new commits.}

cubic-dev-ai

All reported issues were addressed across 20 files

_{Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic}

warquys · 2026-08-22T00:40:01Z

This doesn't provide advanced component tracking; it's just enough to handle major changes. It’s useful when you want to use a physics engine or networking that doesn't integrate seamlessly with ECS.
Otherwise, I would have been forced to use an extension method to do the same job and mark the entity with a flag. Then destroy the entity properly in an other querry.

I would have liked to use a flag system that notifies mark entity and lets the user query them, However, that introduces too many complications. Such as what happens if the user doesn't query, and the need to store the components and entity before destruction. Meaning an other world just holding data before final change.

One issue with Signal is the fact of not knowing what the other handler can do. Like doing a loop of removing adding back component. Or adding a component that an other handler already added.

All of this to say, i look for the simplest solution to feed the lake of notification. There is no problem to fully refuse this draft. I will keep the work for me.

warquys · 2026-08-22T00:49:04Z

And i added an entry to EntityRef, can be remove it's only add this page because i find the need to mention it in the doc of Signal.

GC_Drops_Signals_Once_Everyone_Has_Unsubscribed test will need a rewrite base on the anwser of the open question (GC one). Currently it's the only whay to check. Else it will imply relfection.

warquys · 2026-10-12T20:50:42Z

I forgot to rename the method in the doc 🤡 i will force push !!!

thygrrr · 2026-10-13T17:27:43Z

Questions:

Should the Expression follow a patern ? Or give a new Signale each time? Currently the way of storing Expression kind a bad. For exemple: 2 differente Expression matching a same case, it will be raised depending base on the first call of On.

This is a classic problem. I suggest each registered listener gets notified on "On".

A serious issue with this is that listeners must not be invoked while the world is in WorldMode.IMMEDIATE otherwise the state can change significantly for the other listeners, and refernece guarantees can't be made.

Should orphan Signals be added back to the World? Or should we only count alive signal and remove clean of the GC?

Orphans should, when the Archetype is forgotten (world calls Archetype.Forget()), become unreachable and be collected. A problem is if whatever registered these listeners still holds on to the listener, the whole Archetype stays reachable; so the event itself might need to be a WeakReference<T> or similar.

Should the Exception expose a method to allow for continuation of the operation?
Exceptions here should stop and be considered fatal. Maybe a later version of fennecs can allow custom exception handling here, but since we have no error handlers, if code fennecs calls on your behalf throws, the operation stops.

Same has always been true for runners.

thygrrr · 2026-10-13T17:35:00Z

Performance impacts:

P1: With 0 subscribers, this PR still has a noticeable performance impact.
10,000 per-entity add/remove cycles took 4.85 ms before, and 6.71 ms at the PR about 39% slower. This one is not okay.

P3: With batches, and actual handlers, even through these numbers are still small, we see an even stronger 59.6 µs becomes 349.8 µs, that's 600% or so. I think that one is actually understandable. Becuase some work has to be done.

However, The performance impact is quadratic - number of entities X number of handlers.

P1: Therefore I think maybe it is better to delegate this to the user side of things:

send them a span of entities and changed components, once
in the "single" entity case, send them a span with 1 entity. :)

thygrrr · 2026-10-13T17:36:46Z

P1: Removal-handler exceptions can corrupt World state. A throwing handler in a secondary aspect can leave world.Count == 1 while world.All.Count == 0

(it's fine for the operation to fail and stop there, but the world can't be left corrupt)

Also the world.Count can be inconsistent during a handler's processing.

P1: Spawning inside handlers invalidates live references (maybe). Template spawning executes immediately despite the World lock, because there's always logical space to append so we don't need to queue. However, I realized that fennecs can resize the array and then refs are invalid.

This is a 50% fennecs, 50% PR problem. In fact I may need to block spawning due to the array resizes. Oof. Thank you for inadvertently bringing this hard crash bug risk to light. :) I might have to do a fennecs update ASAP.

thygrrr · 2026-10-13T17:40:49Z

P1: This PR doesn't compile for me. Probably a rename refactor didn't go trhgou all the files, wasn't hard to fix.

thygrrr · 2026-10-13T17:41:52Z

Suggestion for the Lifetime of subscriptions:

using var subscription =
    world.SubscribeAdded<Position>(OnPositionAdded);

i.e. a disposable subscription, meaning the world can dispose it, too, but "orphans" don't really exist - they live per component / TypeExpression, not per archetype.

thygrrr · 2026-10-13T17:28:30Z

+A Batch only signals what actually *changes*. Re-writing a component that Entities already have (via `AddConflict.Replace`) is a value change, not an addition  –  so it stays silent. Likewise, a tolerated no-op removal (`RemoveConflict.Allow` on an Entity that never had the component) raises nothing.
+:::
+
+## Removed... but why?


Love this documentation style, very on-brand.

Add `On` method returning a Signale. `On` as the same signature than `Add`. Meaning you can specify if you whant to handle relation. // This an exemple, avoid lambda you can't remove the handler world.On<Position>().Added += (EntityRef e, ref Position p) => ...; world.On<Position>().Removed += (EntityRef e, in Position p) => ...; Signale are contained in a Dictionary with for key the type of the compoent tarrget. Then a list do the job to raise every matching (base on the Expression). World lock are by default on signal to avoid raising other signale will handling one. Open question: - Should the Expression follow a patern ? Or give a new `Signale` each time? Currently the way of storing Expression kind a bad. For 2 differente Expression matching a same case, it will be raised depending base on the first call of `On`. fix: prevent stack overflow when bulk deferred operations signal

Open question, should the Expcetion expose a method to allow for continutation of the operation? Or finishing the operation should not be an option and it should be donne whatever.

Open question: Should orphan Signals be added back to the World? Or should we only count alive signal and remove clean of the GC?

NB: I call this Event because most ECS use the term of Event, where it's a simple Signal.

GC_Drops_Signals_Once_Everyone_Has_Unsubscribed test will need a rewrite base on the anwser of the open question (GC one). Currently it's the only whay to check. Else it will imply relfection.

I run the benchmarks longueur, this to check if the last change on the benchmark change somthing. I use those metric for the doc.

warquys · 2026-10-14T16:27:35Z

of course i forgotten rebase copy past commits, anyway force with lease

warquys · 2026-10-14T16:34:19Z

A serious issue with this is that listeners must not be invoked while the world is in WorldMode.IMMEDIATE otherwise the state can change significantly for the other listeners, and refernece guarantees can't be made.

I'm thinking of creating a DisableSignal scope. So it catch up at the end and do not trigger Signal. Case like Remove<Postion> then Add<Position> Acting like a simple value change. However, I am not sure of this idea. There might be cases where the user absolutely wants to trigger the event.

With this solution it's simple to catch all entity moved across archetype allowing for the use of span.
This should also boost performance.

warquys · 2026-10-14T16:47:35Z

P1: This PR doesn't compile for me. Probably a rename refactor didn't go trhgou all the files, wasn't hard to fix.

I badly renamed Add and Remove i only renamed the main project and not the Test... I will fix it up
(Shame on my)

warquys · 2026-10-14T16:52:36Z

I fixed the syntax and ran all the tests. For some reason I can't identify, some tests failed. Rerunning them fixed the problem...

I suppose my test run exceeded the quota of concurrent active World by running them in parallel, i have no other hint.

…rks and the tests

warquys · 2026-10-14T17:27:59Z

I am working right on the Pr, i will continue this weekend.
Probably a full commit to apply your answers (like span); cleaner implementation, signal suspend scope and optimize the checking whether a signal is listening.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

warquys · 2026-10-16T17:10:54Z

I have simplified the code; I believe it would be possible to improve execution time by using well-defined collection types. Interfaces such as IReadOnlyList do not offer performance gains during enumeration and instead incur the overhead of virtual calls (vcalls).

…an orphan GC used to forget idle Signals outright; one kept in a field then accepted handlers and never fired. Now the registry only lets go of them: the World keeps a WeakReference per dropped Signal, On<T>() revives the very same instance while someone still holds it, and subscribing to a kept Signal re-registers it. Signals nobody holds are collected by the runtime. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

SignalOverheadBenchmarks and SignalHotpathBenchmarks use only API that also exists on main, so the very same file can be run on both trees to measure what merely having Signals costs when nobody subscribes. Hotpath splits Batch / Spawn / Despawn at two sizes to tell fixed from per-Entity cost. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Covers plain Remove, Batch removal, and Despawn with the throwing handler on the Main or on a secondary Aspect. The secondary-Aspect Despawn case currently fails: Main has already deleted the Entity's rows when the secondary Aspect's handler throws, leaving world.Count == 1 while world.All is empty. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…leted

EntityTemplate.Spawn ignored the World lock: there is always room to append, but appending can grow an Archetype's Storages and pull them out from under live references. A Signal handler spawning into the Archetype whose span it was handed then wrote into a discarded array; a runner spawning while iterating had the same hazard. While locked, the Entities are now minted at once (the caller needs the handles) and join only the Root; their Components follow as deferred Adds on catch-up, raising AfterAdded there like any other deferred Add. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

world.SubscribeAdded<T>(handler) / SubscribeRemoved<T>(handler) (and their Match overloads, and the same methods on Signal<T>) return a Subscription whose Dispose unsubscribes the handler. Lambdas can now be subscribed without leaving a Signal behind with a handler nobody can remove; once its last Subscription is disposed the Signal is idle and World.GC lets go of it. A Subscription lives as long as its owner keeps it, not as long as the Component: World.GC never drops a Signal that still has one, even when no Entity stores the Component. It keeps its World, its Signal, the handler and whether it was an Add or a Remove, and Dispose takes that handler back off directly, with no captured lambda. The World tracks the Subscriptions it handed out and disposes them when it is disposed itself: they report Active == false, and disposing them later is a no-op. Disposing the World also clears every Signal's handlers without counting down, so a -= outliving the World is harmless too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

World.Refresh only ever set the per-type watch bits, so a Component type stayed 'watched' after its last handler left: every Add and Remove of it kept taking the World Lock for a dispatch that found nobody. Refresh now recomputes both bits from scratch. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The Events page still showed the old per-Entity EntityRef handlers. It now documents span handlers, SubscribeAdded/SubscribeRemoved and their Subscription, deferred template spawns from handlers, and that a throwing BeforeRemoved handler leaves the World untouched. The cost section is re-measured against main, with no subscriber and with 1 and 4 handlers. EntityRef no longer claims Signal handlers hand it out, and the Glossary names the Subscribe methods. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Measured on 10 000 Entities with nobody subscribed (median of 3000 runs): DespawnAllWith took 390 us against 320 us on main. Two causes, both from the SignalException wrapper: - the try/catch sat inside the CatchUp loop, so every operation paid for the exception region; it now lives in ApplyFromSignal, called only for operations a handler queued; - FromSignal grew DeferredOperation by a padding slot; Opcode is now a byte, which packs it back to its former size. Neither is enough alone (370 us and 384 us); together the wave is back at ~325 us. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

With nobody subscribed, a 10 000-Entity Template spawn took 47 us against 36 us on main (median of 3000 runs). The Signal path's using-Lock, written inline in World.Spawn, put a try/finally in the method and slowed every spawn. It now lives in SignalSpawned, never inlined, behind a Signalling check: back at ~36 us. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

warquys · 2026-10-24T20:44:14Z

Maybe move away of events to give a stream of entityRef and allow to specify a priority when subscribing.

warquys marked this pull request as draft August 22, 2026 00:30

cubic-dev-ai Bot reviewed Aug 22, 2026

View reviewed changes

thygrrr requested changes Oct 13, 2026

View reviewed changes

warquys added 16 commits October 14, 2026 18:22

feat: Add RemoveCause for Signal

295ef83

feat: Expcetion wraper when Signal throw

320012f

Open question, should the Expcetion expose a method to allow for continutation of the operation? Or finishing the operation should not be an option and it should be donne whatever.

feat: Signal GC clean up

62d6fe5

Open question: Should orphan Signals be added back to the World? Or should we only count alive signal and remove clean of the GC?

docs: documentation for the EntityRef and Signal

ed203bb

NB: I call this Event because most ECS use the term of Event, where it's a simple Signal.

bench: SignalBenchmarks

6c0cf8c

perf: only pay for Signals that actually have subscribers

adb2245

docs: measured cost of Component Signals

0587607

perf: rent the Batch dispatch buffer instead of allocating it

2b3871a

test: Signals under a parallel Job runner

9e40da9

fix: four Signal defects found in review of outfox#52

0d2f384

GC_Drops_Signals_Once_Everyone_Has_Unsubscribed test will need a rewrite base on the anwser of the open question (GC one). Currently it's the only whay to check. Else it will imply relfection.

bench: make the Idle case measure what it claims

36ff013

docs: fix the EntityRef frontmatter description

27b4ef7

doc: Update and round off SignalBenchmarks.

3c4fe6b

I run the benchmarks longueur, this to check if the last change on the benchmark change somthing. I use those metric for the doc.

tweak: Clear name for events

8576fad

docs: Match new naming of method in the doc and fix md array

743e265

warquys force-pushed the feat/component-signals branch from 9c57a1c to 743e265 Compare October 14, 2026 16:26

Fix: Syntaxe fix matching the proper name of the event in the benchma…

a07bd6e

…rks and the tests

refactor: Signals are raised, and handled, on spans

121a4e7

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

warquys marked this pull request as ready for review October 16, 2026 17:08

warquys force-pushed the feat/component-signals branch from 245288c to 4dbf8c7 Compare October 16, 2026 17:18

warquys and others added 2 commits October 16, 2026 19:23

warquys force-pushed the feat/component-signals branch from 4dbf8c7 to f7c1a4b Compare October 16, 2026 17:23

warquys and others added 11 commits October 24, 2026 21:47

fix: rename Signal.BeforRemoved to BeforeRemoved

2c6b539

fix: a throwing Removed handler aborts a Despawn before any row is de…

ea037a6

…leted

refactor: SignalException.Entity becomes Entities

8d5d124

docs: Signal overhead re-measured after the spawn and despawn fixes

2a5ee29

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Conversation

warquys commented Aug 22, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by cubic

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

warquys commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

warquys commented Aug 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

warquys commented Oct 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thygrrr commented Oct 13, 2026

Uh oh!

thygrrr commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thygrrr commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thygrrr commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thygrrr commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thygrrr Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

warquys commented Oct 14, 2026

Uh oh!

warquys commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

warquys commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

warquys commented Oct 14, 2026

Uh oh!

warquys commented Oct 14, 2026

Uh oh!

warquys commented Oct 16, 2026

Uh oh!

warquys commented Oct 24, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

warquys commented Aug 22, 2026 •

edited by cubic-dev-ai Bot

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

warquys commented Aug 22, 2026 •

edited

Loading

warquys commented Aug 22, 2026 •

edited

Loading

warquys commented Oct 12, 2026 •

edited

Loading

thygrrr commented Oct 13, 2026 •

edited

Loading

thygrrr commented Oct 13, 2026 •

edited

Loading

thygrrr commented Oct 13, 2026 •

edited

Loading

thygrrr commented Oct 13, 2026 •

edited

Loading

warquys commented Oct 14, 2026 •

edited

Loading

warquys commented Oct 14, 2026 •

edited

Loading