GECS Entity Component System

The GECS Network Addon provides several high-level features for multiplayer development:

• Declarative sync priorities: Use @export_group("HIGH"), "MEDIUM", "LOW", "SPAWN_ONLY", or "LOCAL" on component properties to manage bandwidth without external config.
• Native transform sync: Adding CN_NativeSync to an entity triggers NativeSyncHandler to manage a MultiplayerSynchronizer with interpolation support.
• Authority markers: The framework automatically injects CN_LocalAuthority, CN_RemoteEntity, and CN_ServerAuthority at spawn. Use these in ECS queries to gate systems based on ownership.
• Relationship sync: Entity relationships are synchronized across peers with deferred resolution to handle non-deterministic spawn ordering.
• Periodic reconciliation: Configurable full-state broadcasts correct state drift automatically.
• Custom sync handlers: You can register per-component-type send/receive handlers at the system level for custom serialization or server correction blending.
• Zero overhead in single-player: NetworkSync detects offline mode and skips all RPC and synchronization logic.

When using dependency tracking, be aware of the following performance characteristics and limitations:

• Performance (Inactive vs Active):
  • Inactive (Default): When not tracking, there is minimal overhead (a single static boolean branch in QueryBuilder.execute(), Entity.get_component(), and has_component()). No allocations or callables are invoked.
  • Active: When track() is running, there is a cost of one static callback per query execution or component read, but only for the duration of the tracked call.
• No Re-entrancy: You must not nest track() calls. The system uses a single static accumulator, so nested tracking is not supported.
• Custom Instrumentation: While GECSTracker.track() is the intended entry point, the low-level hooks QueryBuilder.set_execute_tracker and Entity.set_read_tracker are public if you need to implement custom instrumentation.

GECS provides two modes for matching relationships in queries:

1. Type Matching (Default)

Matches relationships by the component type, ignoring specific property values. Use this to find entities with "any fire damage" or "any buff of this type".

# Matches any fire damage effect by type
ECS.world.query.with_relationship([Relationship.new(C_Damaged.new(), C_FireDamage)])

2. Component Query Matching

Matches relationships by specific property criteria using dictionaries. This allows you to filter by values like amount, duration, or level.

Supported Operators:

• _eq (equal)
• _ne (not equal)
• _gt (greater than)
• _lt (less than)
• _gte (greater than or equal)
• _lte (less than or equal)
• _in (in list)
• _nin (not in list)
• func (custom function)

Example of matching a relation property and a target property:

# Match C_Damaged relationships where amount >= 50
ECS.world.query.with_relationship([
    Relationship.new(C_Damaged.new(), {C_FireDamage: {'amount': {'_gte': 50}}})
])

# Match C_Damaged relationships where amount >= 50
var high_fire_damaged = ECS.world.query.with_relationship([
    Relationship.new(C_Damaged.new(), {C_FireDamage: {'amount': {'_gte': 50}}})
]).execute()

# Match both relation AND target with queries
var strong_buffs = ECS.world.query.with_relationship([
    Relationship.new(
        {C_Buff: {'duration': {'_gt': 10}}},
        {C_Player: {'level': {'_gte': 5}}}
    )
]).execute()

Relationship queries have different performance characteristics based on how they are structured:

1. Prefer Specific Targets (O(1))

Queries that specify an exact target entity resolve in O(1) time because the archetype cache returns the result instantly. Relationship.new(C_X, target_entity) is highly efficient.

2. Avoid Wildcard Scans (O(N))

Queries using a null target (wildcards) must scan all matching archetypes, which scales linearly with the number of entities (O(N)).

3. Use Component Filtering to Narrow Wildcards

To optimize wildcard queries, always combine them with a with_all() component filter. This narrows the search space to a small set of archetypes before the wildcard scan begins.

Slow (Wildcard scan on all archetypes):

var all_poisoned = ECS.world.query.with_relationship([Relationship.new(C_Poison.new(), null)]).execute()

Fast (Narrowed by component first):

var all_poisoned = ECS.world.query.with_all([C_Alive]).with_relationship([Relationship.new(C_Poison.new(), null)]).execute()

# Fast - component query narrows to small set first, wildcard only runs on those
var all_poisoned = ECS.world.query
    .with_all([C_Alive])  # structural O(1) archetype lookup first
    .with_relationship([Relationship.new(C_Poison.new(), null)])
    .execute()

Be aware of these two specific limitations regarding monitors (on_match / on_unmatch):

1. Godot Groups: Monitors do not react to Godot's built-in group changes. A query like q.with_group("x").on_match().on_unmatch() only re-evaluates on component or relationship mutations. Calling node.add_to_group("x") will not trigger the monitor. To fix this, pair group filters with a component marker (e.g., C_Target).
2. Relation Component Properties: Monitors using property-query relationships (e.g., checking a property on a relationship component) do not transition when that property changes. They only re-evaluate on structural mutations (adding or removing the relationship).
   • Example of what fails: q.with_relationship([Relationship.new({C_Buff: {"duration": {"_gt": 0}}}, null)]).on_match().on_unmatch() will not trigger when duration changes.
   • Workaround: Mirror the relevant property onto a direct component on the entity and monitor that component instead.