Bump to v7.2.0 — int-keyed components, system hot path optimizations, safe_iteration

Switch component dictionary keys from resource_path strings to
Script.get_instance_id() ints for faster lookups on every hot path.

- Entity: components dict keyed by int, new _comp_key() helper
- Archetype: columns/edges keyed by int (components) or String (rel://)
- System: FlushMode enum cached once in _internal_setup(), subsystem
  and non-structural filter results cached, lazy CommandBuffer init
- QueryBuilder: cache_version counter detects stale results without
  signal reliance
- New safe_iteration export on System — skip snapshot copy when all
  structural changes go through CommandBuffer
- has_relationship() fast path avoids get_relationship() overhead
- Network addon iterates components.values() instead of .keys()
- Test and example updates for new keying scheme

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

Author: csprance

addons/gecs/docs/TROUBLESHOOTING.md

@@ -140,8 +140,8 @@ func query():
 # Debug what components an entity actually has
 func debug_entity_components(entity: Entity):
     print("Entity components:")
-    for component_path in entity.components.keys():
-        print("  ", component_path)
+    for component in entity.components.values():
+        print("  ", component.get_script().resource_path)
 ```
 
 **Solution**: Ensure components are added correctly:
@@ -382,13 +382,12 @@ func _on_inspect_button_pressed():
     for i in range(min(10, entities.size())):  # Show first 10
         var entity = entities[i]
         print("Entity ", i, ":")
-        print("  Components: ", entity.components.keys())
+        print("  Components: ", entity.components.values().map(func(c): return c.get_script().resource_path))
         print("  Groups: ", entity.get_groups())
 
         # Show component values
-        for comp_path in entity.components.keys():
-            var comp = entity.components[comp_path]
-            print("    ", comp_path, ": ", comp)
+        for comp in entity.components.values():
+            print("    ", comp.get_script().resource_path, ": ", comp)
 ```
 
 ## Getting More Help

addons/gecs/ecs/archetype.gd

@@ -33,7 +33,7 @@ extends RefCounted
 ## Generated by QueryCacheKey.build() from sorted component types
 var signature: int = 0
 
-## Sorted array of component resource paths (e.g., ["res://c_position.gd", "res://c_velocity.gd"])
+## Array of component/relationship keys (ints for components, Strings for rel:// keys)
 ## Used for debugging and archetype matching logic
 var component_types: Array = []
 
@@ -54,15 +54,14 @@ var entity_to_index: Dictionary = {} # Entity -> int
 var enabled_bitset: PackedInt64Array = []
 
 ## OPTIMIZATION: Structure of Arrays (SoA) column storage for cache-friendly iteration
-## Maps component_path -> Array of component instances
+## Maps script_instance_id (int) -> Array of component instances
 ## Enables Flecs-style direct array iteration without dictionary lookups
-## Example: columns["res://c_velocity.gd"] = [vel1, vel2, vel3, ...]
-var columns: Dictionary = {} # String (component_path) -> Array of components
+var columns: Dictionary = {} # int (script_instance_id) -> Array of components
 
-## Archetype edges for fast component add/remove (future optimization)
-## Maps: component_path -> Archetype (the archetype you get by adding/removing that component)
-var add_edges: Dictionary = {} # String -> Archetype
-var remove_edges: Dictionary = {} # String -> Archetype
+## Archetype edges for fast component add/remove
+## Maps: Variant (int for components, String for relationships) -> Archetype
+var add_edges: Dictionary = {} # Variant (int|String) -> Archetype
+var remove_edges: Dictionary = {} # Variant (int|String) -> Archetype
 
 ## Reverse-edge tracking: which archetypes hold an add_edge or remove_edge pointing to this one.
 ## Keyed by source archetype instance_id for O(1) operations.
@@ -75,12 +74,12 @@ func _init(p_signature: int, p_component_types: Array):
 	component_types = p_component_types.duplicate()
 	component_types.sort() # Ensure sorted for consistent matching
 
-	# Separate relationship slot keys from component paths
+	# Separate relationship slot keys (Strings) from component keys (ints)
 	for comp_type in component_types:
-		if (comp_type as String).begins_with("rel://"):
+		if comp_type is String and comp_type.begins_with("rel://"):
 			relationship_types.append(comp_type)
 		else:
-			# Only create columns for component paths, NOT relationship slots
+			# Only create columns for component keys, NOT relationship slots
 			columns[comp_type] = []
 
 
@@ -98,14 +97,14 @@ func add_entity(entity: Entity) -> void:
 
 	# OPTIMIZATION: Populate column arrays from entity.components
 	# Iterate columns keys (skips rel:// keys which have no columns)
-	for comp_path in columns:
-		if entity.components.has(comp_path):
-			(columns[comp_path]
-				.append(entity.components[comp_path]))
+	for comp_key in columns:
+		if entity.components.has(comp_key):
+			(columns[comp_key]
+				.append(entity.components[comp_key]))
 		else:
 			# Entity doesn't have this component yet (might be mid-initialization)
 			# Push null placeholder, will be fixed when component is added
-			columns[comp_path].append(null)
+			columns[comp_key].append(null)
 
 
 ## Remove an entity from this archetype using swap-remove
@@ -125,8 +124,8 @@ func remove_entity(entity: Entity) -> bool:
 		entity_to_index[last_entity] = index
 
 		# OPTIMIZATION: Swap in column arrays too (maintain same ordering)
-		for comp_path in columns:
-			columns[comp_path][index] = columns[comp_path][last_index]
+		for comp_key in columns:
+			columns[comp_key][index] = columns[comp_key][last_index]
 
 		# OPTIMIZATION: Swap enabled bit
 		var last_enabled = _get_enabled_bit(last_index)
@@ -137,8 +136,8 @@ func remove_entity(entity: Entity) -> bool:
 	entity_to_index.erase(entity)
 
 	# OPTIMIZATION: Remove last element from all columns
-	for comp_path in columns:
-		columns[comp_path].pop_back()
+	for comp_key in columns:
+		columns[comp_key].pop_back()
 
 	# OPTIMIZATION: Update bitset size (no need to clear the bit, just reduce logical size)
 	# The bit will be overwritten when a new entity is added
@@ -167,8 +166,8 @@ func clear() -> void:
 	entity_to_index.clear()
 
 	# OPTIMIZATION: Clear column arrays
-	for comp_path in columns:
-		columns[comp_path].clear()
+	for comp_key in columns:
+		columns[comp_key].clear()
 
 	# OPTIMIZATION: Clear bitset
 	enabled_bitset.clear()
@@ -234,10 +233,13 @@ func matches_relationship_query(required_rel_keys: Array, excluded_rel_keys: Arr
 func _to_string() -> String:
 	var comp_names = []
 	for comp_type in component_types:
-		# Extract just the class name from the path
-		var parts = comp_type.split("/")
-		var filename = parts[parts.size() - 1].replace(".gd", "")
-		comp_names.append(filename)
+		if comp_type is String:
+			# Relationship slot key — extract readable name from path
+			var parts = comp_type.split("/")
+			var filename = parts[parts.size() - 1].replace(".gd", "")
+			comp_names.append(filename)
+		else:
+			comp_names.append(str(comp_type))
 
 	return "Archetype[sig=%d, comps=%s, entities=%d]" % [
 		signature,
@@ -248,43 +250,43 @@ func _to_string() -> String:
 
 ## Set up an edge to another archetype when a component is added
 ## Enables O(1) archetype transitions when components change
-func set_add_edge(component_path: String, target_archetype: Archetype) -> void:
-	add_edges[component_path] = target_archetype
+func set_add_edge(comp_key: Variant, target_archetype: Archetype) -> void:
+	add_edges[comp_key] = target_archetype
 	target_archetype.neighbors[get_instance_id()] = self
 
 
 ## Set up an edge to another archetype when a component is removed
 ## Enables O(1) archetype transitions when components change
-func set_remove_edge(component_path: String, target_archetype: Archetype) -> void:
-	remove_edges[component_path] = target_archetype
+func set_remove_edge(comp_key: Variant, target_archetype: Archetype) -> void:
+	remove_edges[comp_key] = target_archetype
 	target_archetype.neighbors[get_instance_id()] = self
 
 
 ## Get the target archetype when adding a component (if edge exists)
-func get_add_edge(component_path: String) -> Archetype:
-	return add_edges.get(component_path, null)
+func get_add_edge(comp_key: Variant) -> Archetype:
+	return add_edges.get(comp_key, null)
 
 
 ## Get the target archetype when removing a component (if edge exists)
-func get_remove_edge(component_path: String) -> Archetype:
-	return remove_edges.get(component_path, null)
+func get_remove_edge(comp_key: Variant) -> Archetype:
+	return remove_edges.get(comp_key, null)
 
 
 ## OPTIMIZATION: Get component column array for cache-friendly iteration
 ## Enables Flecs-style direct array access instead of dictionary lookups per entity
-## [param component_path] The resource path of the component type (e.g., C_Velocity.resource_path)
+## [param comp_key] The component key (Script.get_instance_id()) or relationship slot key (String)
 ## [returns] Array of component instances in entity index order, or empty array if not found
 ##
 ## Example:
 ## [codeblock]
-## var velocities = archetype.get_column(C_Velocity.resource_path)
+## var velocities = archetype.get_column(C_Velocity.get_instance_id())
 ## for i in range(velocities.size()):
 ##     var velocity = velocities[i]
 ##     var entity = archetype.entities[i]
 ##     # Process with cache-friendly sequential access
 ## [/codeblock]
-func get_column(component_path: String) -> Array:
-	return columns.get(component_path, [])
+func get_column(comp_key: Variant) -> Array:
+	return columns.get(comp_key, [])
 
 
 ## OPTIMIZATION: Get entities filtered by enabled state using bitset

addons/gecs/ecs/ecs.gd

@@ -89,7 +89,7 @@ func process(delta: float, group: String = "") -> void:
 func get_components(entities, component_type, default_component = null) -> Array:
 	var components = []
 	for entity in entities:
-		var component = entity.components.get(component_type.resource_path, null)
+		var component = entity.components.get(component_type.get_instance_id() if component_type is Script else component_type.get_script().get_instance_id(), null)
 		if not component and not default_component:
 			assert(component, "Entity does not have component: " + str(component_type))
 		if not component and default_component:

addons/gecs/ecs/entity.gd

@@ -67,14 +67,22 @@ signal relationships_batch_removed(entity: Entity, _relationships: Array)
 #endregion Exported Variables
 
 #region Public Variables
-## [Component]s attached to the [Entity] in the form of Dict[resource_path:String, Component]
+## [Component]s attached to the [Entity] in the form of Dict[int (script_instance_id), Component]
 var components: Dictionary = {}
 
 ## Relationships attached to the entity
 var relationships: Array[Relationship] = []
 
-## Cache for component resource paths to avoid repeated .get_script().resource_path calls
-var _component_path_cache: Dictionary = {}
+## Cache for component keys to avoid repeated .get_script().get_instance_id() calls
+var _component_key_cache: Dictionary = {}
+
+
+## Returns the int key used for component dictionary lookups.
+## Accepts either a Script (class reference) or a Component instance.
+static func _comp_key(c) -> int:
+	if c is Script:
+		return c.get_instance_id()
+	return c.get_script().get_instance_id()
 
 ## Logger for entities to only log to a specific domain
 var _entityLogger = GECSLogger.new().domain("Entity")
@@ -162,22 +170,22 @@ func get_effective_serialize_config() -> GECSSerializeConfig:
 ## [b]Example[/b]:
 ## [codeblock]entity.add_component(HealthComponent)[/codeblock]
 func add_component(component: Resource) -> void:
-	# Cache the resource path to avoid repeated calls
-	var resource_path = component.get_script().resource_path
+	# Cache the component key to avoid repeated calls
+	var comp_key = _comp_key(component)
 
 	# If a component of this type already exists, remove it first
-	if components.has(resource_path):
-		var existing_component = components[resource_path]
+	if components.has(comp_key):
+		var existing_component = components[comp_key]
 		remove_component(existing_component)
 
-	_component_path_cache[component] = resource_path
-	components[resource_path] = component
+	_component_key_cache[component] = comp_key
+	components[comp_key] = component
 	component.parent = self
 	if not component.property_changed.is_connected(_on_component_property_changed):
 		component.property_changed.connect(_on_component_property_changed)
 	## Adding components happens through a signal
 	component_added.emit(self , component)
-	_entityLogger.trace("Added Component: ", resource_path)
+	_entityLogger.trace("Added Component: ", comp_key)
 
 
 func _on_component_property_changed(
@@ -202,9 +210,9 @@ func add_components(_components: Array):
 	for component in _components:
 		if component == null:
 			continue
-		var component_path = component.get_script().resource_path
-		if not components.has(component_path):
-			components[component_path] = component
+		var comp_key = _comp_key(component)
+		if not components.has(comp_key):
+			components[comp_key] = component
 			added_components.append(component)
 
 	# If no new components were actually added, return early
@@ -232,9 +240,9 @@ func add_components(_components: Array):
 		else:
 			# Same archetype - just update the column data for new components
 			for component in added_components:
-				var comp_path = component.get_script().resource_path
+				var comp_key = _comp_key(component)
 				var entity_index = old_archetype.entity_to_index[ self ]
-				old_archetype.columns[comp_path][entity_index] = component
+				old_archetype.columns[comp_key][entity_index] = component
 
 	# Emit signals for all added components
 	for component in added_components:
@@ -246,21 +254,20 @@ func add_components(_components: Array):
 ## [b]Example:[/b]
 ##     [codeblock]entity.remove_component(HealthComponent)[/codeblock]
 func remove_component(component: Resource) -> void:
-	# Use cached path if available, otherwise get it from the component class
-	var resource_path: String
-	if _component_path_cache.has(component):
-		resource_path = _component_path_cache[component]
-		_component_path_cache.erase(component)
+	# Use cached key if available, otherwise derive it
+	var comp_key: int
+	if _component_key_cache.has(component):
+		comp_key = _component_key_cache[component]
+		_component_key_cache.erase(component)
 	else:
-		# Component parameter should be a class/script, consistent with has_component
-		resource_path = component.resource_path
+		comp_key = _comp_key(component)
 
-	if components.has(resource_path):
-		var component_instance = components[resource_path]
-		components.erase(resource_path)
+	if components.has(comp_key):
+		var component_instance = components[comp_key]
+		components.erase(comp_key)
 
 		# Clean up cache entry for the component instance
-		_component_path_cache.erase(component_instance)
+		_component_key_cache.erase(component_instance)
 
 		# OBS-03: Disconnect property_changed before emitting removal signal.
 		# Without this, phantom on_component_changed callbacks arrive whenever
@@ -270,7 +277,7 @@ func remove_component(component: Resource) -> void:
 
 		component_removed.emit(self , component_instance)
 		# ARCHETYPE: Signal handler (_on_entity_component_removed) handles archetype update
-		_entityLogger.trace("Removed Component: ", resource_path)
+		_entityLogger.trace("Removed Component: ", comp_key)
 
 
 func deferred_remove_component(component: Resource) -> void:
@@ -303,12 +310,12 @@ func remove_components(_components: Array):
 			comp_to_remove = _component
 
 		if comp_to_remove:
-			var component_path = comp_to_remove.get_script().resource_path
-			if components.has(component_path):
-				components.erase(component_path)
+			var comp_key = _comp_key(comp_to_remove)
+			if components.has(comp_key):
+				components.erase(comp_key)
 				# Clean up cache entries for both the class and instance
-				_component_path_cache.erase(_component)
-				_component_path_cache.erase(comp_to_remove)
+				_component_key_cache.erase(_component)
+				_component_key_cache.erase(comp_to_remove)
 				# OBS-03: Disconnect property_changed before emitting removal signal.
 				if comp_to_remove.property_changed.is_connected(_on_component_property_changed):
 					comp_to_remove.property_changed.disconnect(_on_component_property_changed)
@@ -356,14 +363,14 @@ func remove_all_components() -> void:
 ## [b]Example:[/b]
 ##     [codeblock]var transform = entity.get_component(Transform)[/codeblock]
 func get_component(component: Resource) -> Component:
-	return components.get(component.resource_path, null)
+	return components.get(_comp_key(component), null)
 
 
 ## Check to see if an entity has a  specific component on it.[br]
 ## This is useful when you're checking to see if it has a component and not going to use the component itself.[br]
 ## If you plan on getting and using the component, use [method get_component] instead.
 func has_component(component: Resource) -> bool:
-	return components.has(component.resource_path)
+	return components.has(_comp_key(component))
 
 #endregion Components
 
@@ -517,9 +524,13 @@ func get_relationships(relationship: Relationship) -> Array[Relationship]:
 
 
 ## Checks if the entity has a specific relationship.[br]
+## Fast path — skips validation/cleanup (use get_relationship when you need the value).[br]
 ## [param relationship] The [Relationship] to check for.
 func has_relationship(relationship: Relationship) -> bool:
-	return get_relationship(relationship) != null
+	for rel in relationships:
+		if rel.matches(relationship):
+			return true
+	return false
 
 #endregion Relationships