75 lines
3.4 KiB
GDScript
75 lines
3.4 KiB
GDScript
## An Observer is like a system that reacts when specific component events happen
|
|
## It has a query that filters which entities are monitored for these events
|
|
## Observers can respond to component add/remove/change events on specific sets of entities
|
|
##
|
|
## [b]Important:[/b] For property changes to trigger [method on_component_changed], you must
|
|
## manually emit the [signal Component.property_changed] signal from within your component.
|
|
## Simply setting properties does not automatically trigger observers.
|
|
##
|
|
## [b]Example of triggering property changes:[/b]
|
|
## [codeblock]
|
|
## # In your component class
|
|
## class_name MyComponent
|
|
## extends Component
|
|
##
|
|
## @export var health: int = 100 : set = set_health
|
|
##
|
|
## func set_health(new_value: int):
|
|
## var old_value = health
|
|
## health = new_value
|
|
## # This is required for observers to detect the change
|
|
## property_changed.emit(self, "health", old_value, new_value)
|
|
## [/codeblock]
|
|
@icon("res://addons/gecs/assets/observer.svg")
|
|
class_name Observer
|
|
extends Node
|
|
|
|
## The [QueryBuilder] object exposed for conveinence to use in the system and to create the query.
|
|
var q: QueryBuilder
|
|
|
|
|
|
## Override this method and return a [QueryBuilder] to define the required [Component]s the entity[br]
|
|
## must match for the observer to trigger. If empty this will match all [Entity]s
|
|
func match() -> QueryBuilder:
|
|
return q
|
|
|
|
|
|
## Override this method and provide a single component to watch for events.[br]
|
|
## This means that the observer will only react to events on this component (add/remove/change)[br]
|
|
## assuming the entity matches the query defined in the [method match] method
|
|
func watch() -> Resource:
|
|
assert(false, "You must override the watch() method in your system")
|
|
return
|
|
|
|
|
|
## Override this method to define the main processing function for the observer when a component is added to an [Entity].[br]
|
|
## [param entity] The [Entity] the component was added to.[br]
|
|
## [param component] The [Component] that was added. Guaranteed to be the component defined in [method watch].[br]
|
|
func on_component_added(entity: Entity, component: Resource) -> void:
|
|
pass
|
|
|
|
|
|
## Override this method to define the main processing function for the observer when a component is removed from an [Entity].[br]
|
|
## [param entity] The [Entity] the component was removed from.[br]
|
|
## [param component] The [Component] that was removed. Guaranteed to be the component defined in [method watch].[br]
|
|
func on_component_removed(entity: Entity, component: Resource) -> void:
|
|
pass
|
|
|
|
|
|
## Override this method to define the main processing function for property changes.[br]
|
|
## This method is called when a property changes on the watched component.[br]
|
|
## [br]
|
|
## [b]Note:[/b] This method only triggers when the component explicitly emits its
|
|
## [signal Component.property_changed] signal for performance reasons. Setting properties directly will
|
|
## [b]not[/b] automatically trigger this method.[br]
|
|
## [br]
|
|
## [param entity] The [Entity] the component that changed is attached to.
|
|
## [param component] The [Component] that changed. Guaranteed to be the component defined in [method watch].
|
|
## [param property] The name of the property that changed on the [Component].
|
|
## [param old_value] The old value of the property.
|
|
## [param new_value] The new value of the property.
|
|
func on_component_changed(
|
|
entity: Entity, component: Resource, property: String, new_value: Variant, old_value: Variant
|
|
) -> void:
|
|
pass
|