World: modernize ECS usage with Flecs idioms

[Segfaultd]

Summary

Sweep through the ECS layer replacing legacy patterns with idiomatic Flecs v4 features. No behavioral changes intended; all 93 RunFrameworkTests pass.

Tags, relations, observers

• Convert PendingRemoval and RemovedOnResourceReload from [[maybe_unused]] uint8_t stubs to true zero-size tags.
• Introduce a DependsOn relation marked Acyclic with (OnDeleteTarget, Remove); the Streamable::dependentEntities vector is gone and the (DependsOn, *) graph is walked via entity::each<DependsOn>.
• Engine::GetEntityByGUID and ClientEngine::GetEntityByServerID are now O(1), backed by OnSet/OnRemove observer-maintained caches with reverse maps so reassignments do not leave stale forward entries.
• The interval-based RemoveEntities system is now an OnAdd observer on PendingRemoval; streamer cleanup and e.destruct() happen the instant removal is requested.
• TickRateRegulator no longer inherits from Transform — composition with a snapshot member — and its system uses a plain .each(...).

Custom streaming events

• The framework's per-entity Streamable::events.spawnProc/despawnProc/updateProc/ownerUpdateProc/selfUpdateProc function pointers are replaced with custom flecs events (StreamSpawnEvent, StreamDespawnEvent, StreamUpdateEvent, StreamOwnerUpdateEvent, StreamSelfUpdateEvent). The streaming loop emits them with a {peer, targetGuid} payload; RegisterServerStreamObservers / RegisterClientStreamObservers translate them into network messages and still invoke each entity's modEvents.* callback. Mods can subscribe additional observers to the same events.
• Streamable factory's per-entity SetupServerEmitters/SetupClientEmitters calls are replaced by OnAdd observers registered once at engine init.

Pipeline and infrastructure

• Custom OwnershipPhase and StreamingPhase declared with flecs::Phase + depends_on; the three server systems express order through the type system instead of all crowding into PostUpdate.
• _findAllStreamerEntities, _allStreamableEntities, and _findAllResourceEntities are built with .cached() so they stop rebuilding their match set every iteration.
• TickRateRegulator system is tagged .multi_threaded() — gated by world.set_threads(N), no-op at N=1.
• Active NetworkPeer is now a flecs::Singleton (NetworkPeerHandle); Engine::GetNetworkPeer() wraps the lookup. Old _networkPeer member removed.
• defer_begin/defer_end pairs replaced with world.defer([&]{ ... }) for RAII-style scoping.
• OwnedResource{Resource*} back-pointer component removed; callers look up the C++ Resource via ResourceManager::GetResource(entity.name()).
• Reflection member<>() registrations lifted out of #ifdef _WIN32 so the Flecs explorer / REST API can introspect components on every platform.

Explicitly not changed, with rationale

• Streamer::entities (per-frame mutating std::unordered_map) was not converted to a (StreamingTo, target) relation: per-pair archetype churn every spawn/despawn outweighs the structural benefit.
• Per-entity strategy callbacks (assignOwnerProc, isVisibleProc, collectRangeExemptEntitiesProc) remain fu2::functions on the component — a singleton policy cannot express per-entity choice and a tag/observer scheme adds ceremony without a real win.

Test plan

• cmake --build build --target RunFrameworkTests — 93/93 pass.
• Manual smoke test on a downstream project (MafiaMP needs its modEvents consumers re-verified; the in-tree copy already cannot build on this branch for an unrelated flecs/flecs.h include-path issue).

Version impact

Touches shared ECS modules and the network-side streaming event surface — MAJOR bump per CONTRIBUTING.md. Requires matching client + server updates.

Summary by CodeRabbit

• Refactor
  • Overhauled entity streaming and synchronization architecture using event-driven observers instead of direct callbacks.
  • Improved entity caching mechanisms for faster lookups during client-server communication.
  • Simplified entity dependency tracking with automatic lifecycle management.
  • Enhanced network peer management through centralized singleton pattern.

[coderabbitai]

Warning

Rate limit exceeded

@Segfaultd has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 32 minutes and 7 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 922f4a84-d1fb-41bb-91be-2b866acc0c18

📥 Commits

Reviewing files that changed from the base of the PR and between 2242ace and d37252e.

📒 Files selected for processing (10)

• code/framework/src/world/client.cpp
• code/framework/src/world/client.h
• code/framework/src/world/engine.cpp
• code/framework/src/world/engine.h
• code/framework/src/world/modules/base.hpp
• code/framework/src/world/modules/modules_impl.cpp
• code/framework/src/world/server.cpp
• code/framework/src/world/types/streaming.hpp
• code/tests/framework_ut.cpp
• code/tests/modules/streaming_ut.h

Walkthrough

This PR refactors the streaming architecture to use Flecs observers and event emission instead of stored callbacks and direct function invocation. OwnedResource tracking is removed, new event-driven components replace stored procedures, observer-maintained caches enable efficient GUID/ServerID lookups, and server streaming systems now emit events that trigger observer-based network synchronization.

Changes

Observer-based Streaming

Layer / File(s)	Summary
OwnedResource removal code/framework/src/scripting/resource/resource.cpp, resource.h, code/tests/modules/resource_ut.h	Removes OwnedResource component from root entity creation, simplifies child entity destruction to use defer lambda, and updates test to validate entity name instead of component membership.
Event components and module registration code/framework/src/world/modules/base.hpp	Introduces tag components (PendingRemoval, RemovedOnResourceReload, DependsOn, NetworkPeerHandle) and streaming event types (StreamEventBase with peer/targetGuid, and derived Stream*Event variants). Refactors TickRateRegulator to contain Transform snapshot instead of inheriting. Simplifies Streamable by removing base event storage and dependent-entity member. Updates Base constructor to register event components, set up DependsOn as acyclic relation with cleanup, and declare observer registration functions.
GUID and ServerID observer-based caching code/framework/src/world/engine.cpp, engine.h, client.cpp, client.h	Implements observer-maintained lookup caches: Engine maintains _guidToEntity/_entityToGuid for Streamer components (reacting to OnSet/OnRemove with reassignment handling), and ClientEngine maintains _serverIDToEntity/_entityToServerID for ServerID components. Both GetEntityByGUID and GetEntityByServerID resolve through maps returning flecs::entity::null() when missing or not alive. Includes GetNetworkPeer() accessor returning peer from singleton.
Observer-based streaming event wiring code/framework/src/world/modules/modules_impl.cpp	Implements server observers for ServerStreamSpawn/Despawn/SelfUpdate/Update/OwnerUpdate and client observer for ClientStreamUpdate, extracting typed event payloads, validating peer/payload, constructing/sending network messages with guid targeting, and invoking mod procedures. Replaces removed SetupServerEmitters/SetupClientEmitters callbacks.
Server streaming pipeline refactoring code/framework/src/world/server.cpp, server.h	Introduces custom Flecs phases (OwnershipPhase, StreamingPhase) and registers server stream observers during init. Replaces polling-based RemoveEntities system with observer reacting to PendingRemoval, removing stream registrations and emitting StreamDespawnEvent before entity destruction. Moves visibility/entity systems to streamingPhase. Rewrites TickRateRegulator system as multi-threaded Flecs each() lambda updating snapshot and updateInterval. Refactors StreamEntities to emit framework events (gated by performTickUpdates) instead of calling base procedures. Updates dependent-visibility check to traverse DependsOn relations via Flecs instead of stored list. Removes removeEntitiesTickInterval from config.
Factory updates for component modification notification code/framework/src/world/types/player.hpp, streaming.hpp	Updates PlayerFactory::SetupDefaults and SetupServer to emit modified<Streamer>() after setting guid/hardwareId, triggering observer cache updates. Updates StreamingFactory::SetupClient/SetupServer to remove explicit emitter wiring and rely on Streamable OnAdd observers registered at engine init time.

Sequence Diagram

sequenceDiagram
    participant ServerInit as ServerEngine::Init
    participant Flecs as Flecs World
    participant StreamObs as StreamObservers
    participant ServerSync as GameSyncEntity Network
    participant Client as ClientEngine

    ServerInit->>Flecs: Import Base module
    Flecs->>Flecs: Register event components<br/>(StreamSpawnEvent, etc.)
    ServerInit->>Flecs: Create phases<br/>(OwnershipPhase, StreamingPhase)
    ServerInit->>Flecs: Register server stream observers
    
    Note over ServerInit,Flecs: Entity creation triggers observer chain
    ServerInit->>+Flecs: Create entity with Streamer component
    Flecs->>Flecs: OnSet observer updates<br/>_guidToEntity cache
    Flecs->>Flecs: Streamable OnAdd observer<br/>wires mod events
    Flecs-->>-ServerInit: Entity ready
    
    Note over Flecs,Client: Streaming update loop
    Flecs->>Flecs: StreamEntities system runs<br/>in StreamingPhase
    Flecs->>Flecs: Emit StreamUpdateEvent
    Flecs->>StreamObs: Observer receives event
    StreamObs->>ServerSync: Build GameSyncEntityUpdate
    ServerSync->>Client: Send to client with<br/>ServerID + Transform
    StreamObs->>StreamObs: Invoke mod update proc

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• MafiaHub/Framework#190: Removes OwnedResource struct that was added in PR #190; both PRs modify Resource root-entity creation code path.
• MafiaHub/Framework#178: Both PRs refactor streaming/visibility subsystem; PR #178 added Streamable.dependentEntities and visibility methods while this PR replaces them with DependsOn relations and observer-based architecture.

Suggested reviewers

• zpl-zak

Poem

🐰 Observers dance where callbacks once stood still,
Events flow like streams down Flecs' windmill.
Dependencies bloom in relations so fine,
Cache maps keep GUID and ID in line. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 5.13% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'World: modernize ECS usage with Flecs idioms' is fully related to the main changes in the changeset, which systematically convert the ECS layer to use idiomatic Flecs v4 features.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/ecs-modernization

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@code/framework/src/world/modules/modules_impl.cpp`:
- Around line 130-137: The code constructs
Framework::Networking::Messages::GameSyncEntityUpdate msg and only populates it
when e.try_get<Transform>() (tr) and e.try_get<ServerID>() (sid) are present,
but still calls payload->peer->Send(msg, payload->targetGuid) unconditionally;
change the logic so the send is guarded by the same condition (e.g., only call
payload->peer->Send(...) inside the if (tr && sid) block or return/skip when tr
or sid are missing) to avoid transmitting unpopulated/invalid
GameSyncEntityUpdate messages.

In `@code/framework/src/world/server.cpp`:
- Around line 121-133: The code treats a generation mismatch (t.GetGeneration()
!= reg.lastGenID), which is deliberately triggered by WakeEntity(), as a reason
to slow updates; instead treat it as a wake event and keep the
high-rate/defaultUpdateInterval. Modify the logic around t.GetGeneration(),
reg.lastGenID and decreaseRate so that a generation mismatch does NOT set
decreaseRate = true (either set decreaseRate = false or directly set
s.updateInterval = s.defaultUpdateInterval when the generations differ), then
update reg.lastGenID and proceed; ensure s.updateInterval only increases when
decreaseRate is legitimately true, not on a WakeEntity() generation bump.
- Around line 187-207: The code is checking rs[i].performTickUpdates but that
flag belongs to the streamed entity otherS, so replace uses of
rs[i].performTickUpdates with otherS.performTickUpdates and gate both the
StreamUpdateEvent and StreamOwnerUpdateEvent emission on
otherS.performTickUpdates; locate the checks around the emission blocks (the
blocks that call _world->event<Modules::Base::StreamUpdateEvent>() and
_world->event<Modules::Base::StreamOwnerUpdateEvent>() and the variable
map_it->second) and change the conditional so the entity's performTickUpdates
(otherS.performTickUpdates) controls whether the events are emitted.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1b78d40f-f75c-4941-8d5d-b407bc2c135b

📥 Commits

Reviewing files that changed from the base of the PR and between e10a7a2 and 2242ace.

📒 Files selected for processing (13)

• code/framework/src/scripting/resource/resource.cpp
• code/framework/src/scripting/resource/resource.h
• code/framework/src/world/client.cpp
• code/framework/src/world/client.h
• code/framework/src/world/engine.cpp
• code/framework/src/world/engine.h
• code/framework/src/world/modules/base.hpp
• code/framework/src/world/modules/modules_impl.cpp
• code/framework/src/world/server.cpp
• code/framework/src/world/server.h
• code/framework/src/world/types/player.hpp
• code/framework/src/world/types/streaming.hpp
• code/tests/modules/resource_ut.h

💤 Files with no reviewable changes (3)

• code/tests/modules/resource_ut.h
• code/framework/src/scripting/resource/resource.h
• code/framework/src/world/server.h