feat: Trackable creation of entities in sapphire-jecs references

- Users are now able to track whenever an entity gets created through a reference via the sapphire_jecs.on_created signal. This is useful, for example, for tracking freshly replicated entities and setting them up.

crates/sapphire-jecs/lib/init.luau

@@ -22,7 +22,9 @@ local pair = jecs.pair
 local world = require(script.world)
 local handle = require(script.handle)
 export type handle = handle.handle
-local ref = require(script.ref)
+local _ref = require(script.ref)
+local ref = _ref.ref
+local ref_on_created = _ref.on_created
 local spawner_type = require(script.spawner_type)
 
 local SapphireJecs = {}
@@ -128,6 +130,7 @@ function SapphireJecs.handle(entity: entity): handle
 end
 
 SapphireJecs.ref = ref
+SapphireJecs.on_created = ref_on_created
 
 --- Creates a new entity and returns its id.
 --- @return entity

crates/sapphire-jecs/lib/ref.luau

@@ -1,4 +1,10 @@
 --!strict
+local signal = require(script.Parent.Parent.signal)
+--- Fires whenever a reference with a given key creates a new entity.
+--- Useful to track freshly replicated entities.
+--- @type signal<<number> entity, <any> key>
+local on_created: signal.Signal<number, any> = signal()
+
 local world = require(script.Parent.world)
 local handle = require(script.Parent.handle)
 local refs = {}
@@ -17,9 +23,13 @@ local function ref(key: any): handle.handle
     if not entity then
         entity = world:entity()
         refs[key] = entity
+        on_created:Fire(entity, key)
     end
 
     return handle.new(entity)
 end
 
-return ref
+return {
+    ref = ref,
+    on_created = on_created,
+}

crates/sapphire-jecs/wally.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mark-marks/sapphire-jecs"
-version = "0.1.2"
+version = "0.1.3"
 registry = "https://github.com/UpliftGames/wally-index"
 realm = "shared"
 license = "MIT"