Components¶
Event and Action¶
Event¶
Event job is to trig Actions when conditions matches.
_mechanism
Mechanism class can be specified in _mechanism
class attribute. Event parameters will be prepared by this Mechanism.
_concern
Event can observe specified objects. You can specify COL identifier in the _concern
class attribute. By default, Event
observe all synergies objects.
_prepare
Write here conditions who determine if looked object is concerned by this event. If yes, you must return parameters given to Action. If event is not concerned, you must raise NotConcernedEvent exception.
The Event class¶
Events must be child class of synergine.synergy.event.Event.Event
:
-
class
synergine.synergy.event.Event.
Event
(actions)[source]¶ Event are called by mechanisms and trig associated actions if conditions matches.
-
_concern
= 1¶ The COL id of concerned synergies objects
-
_each_cycle
= 1¶ Event ca be executed each x cycle if needed
-
_first_cycle_force
= False¶ Event will be executed at first cycle regardless of _each_cycle
-
_mechanism
¶ Mechanism class who run this event with prepared parameters
alias of
Mechanism
-
_prepare
(object_id, context, parameters={})[source]¶ Return dict with parameters for actions
Parameters: - object_id – The id of observed synergy object
- context – The Context
- parameters – Mechanism prepared dict of parameters
Raise: NotConcernedEvent
Returns:
-
Example¶
You can found here an example of implemented Event
:
from synergine_lifegame.synergy.event.AliveAroundEvent import AliveAroundEvent
from synergine.core.exceptions import NotConcernedEvent
from synergine_xyz.mechanism.AroundMechanism import AroundMechanism
from synergine_lifegame.cst import ALIVE, COL_DIED
class GoodConditionToBornEvent(AliveAroundEvent):
"""
This event is applied when born condition are here. So when exactly 3 alive cell are around of observed cell.
"""
_mechanism = AroundMechanism
"""This event need to know what is around concerned cell. So we use AroundMechanism who give us list of around
objects ids."""
_concern = COL_DIED
"""This event only concern died cells."""
def _prepare(self, object_id, context, parameters={}):
"""
According to “Conway’s Game of Life”, event match if exactly 3 around cell are alive.
"""
cell_near_count = self._get_alive_cell_around_count(context, parameters)
if cell_near_count is 3:
return parameters
# If event not match, we must raise an NotConcernedEvent.
raise NotConcernedEvent()
Action¶
Action
own the code intended for modify synergies objects.
_listen
They have to listen an Event. Action _listen
class attribute must be contain an Event class.
_depend
If the Action
must be executed after other actions, you can list them in Action _depend
class attribute.
run
The execution code of Action
have to be write in run
method.
The Action class¶
Actions must be child class of synergine.synergy.event.Action.Action
.
-
class
synergine.synergy.event.Action.
Action
(object_id, parameters)[source]¶ Action
own the code intended for modify synergies objects.-
_depend
= []¶ List of
Action
who need to be executed before this.
-
_listen
= None¶ The
Event
class to listen.
-
classmethod
cycle_pre_run
(context, synergy_manager)[source]¶ This class method will be executed each cycle, one time by action class. Useful fo apply some tricks before this synergies objects action.
Parameters: - context –
- synergy_manager –
Returns:
-
classmethod
get_dependencies
()[source]¶ Returns: List of Action
who need to be executed before this.Return type: list (of Action
)
-
Example¶
You can found here an example of implemented Action
:
from synergine.synergy.event.Action import Action
from synergine_lifegame.synergy.event.GoodConditionToBornEvent import GoodConditionToBornEvent
class BornAction(Action):
"""
This action change state of Cell into alive.
"""
_listen = GoodConditionToBornEvent
"""This action listen the GoodConditionToBornEvent"""
def run(self, obj, context, synergy_manager):
obj.set_alive(True)
Mechanism¶
Mechanism prepare data for associated Events. It’s role is to compute once what multiple Events will need.
Mechanisms must be child of:
-
class
synergine.core.simulation.mechanism.Mechanism.
Mechanism
(events)[source]¶ Mechanism prepare data for associated events. The principle: One mechanism compute once what multiple events need.
-
_get_computed_object_event_parameters
(object_id, context)[source]¶ (You must override this method in child-class.) Compute concerned object event parameters.
Parameters: - object_id – Concerned object id
- context – The Context
Returns: Concerned object event parameters
-
_get_object_parameters
(object_id, context)[source]¶ Return concerned object parameters for event.
Parameters: - object_id – Concerned object if
- context – The Context
Returns: parameters who will be used by event
-
Example¶
You can found here an example of implemented Mechanism
:
from synergine.core.exceptions import UselessMechanism
from synergine.core.simulation.mechanism.Mechanism import Mechanism
from synergine_xyz.cst import POSITION
class AroundMechanism(Mechanism):
"""
Compute near object ids of concerned object.
"""
def _get_computed_object_event_parameters(self, object_id, context):
"""
:param object_id: Concerned object id
:param context: Context object
:return: Near objects ids: {'objects_ids_near': [0, 1, 2, 3, ...]}
:rtype: dict
"""
object_point = context.metas.value.get(POSITION, object_id)
objects_ids_near = context.get_objects_ids_near_point(object_point, 1)
# If we not have near object, this mechanism is useless. So we raise a UselessMechanism: Synergine will not
# run associated events in this case.
if not objects_ids_near:
raise UselessMechanism()
return {'objects_ids_near': objects_ids_near}
Context, Metas¶
Context is designed to contain data (in metas attribute
) and method representing simulation. You can found information about it here, example of Context class here and usage example in HowTo documentation.
COL¶
For performance reason, an event can compute for specified list of SynergyObject. When his _concern
attribute is configured with a COL_XXX
, only SynergyObjects
contained in this COL_XXX
will be concerned.
You can see _concern
usage example here.
SynergyObject¶
SynergyObject is a representation of your simulation subject.
-
class
synergine.synergy.object.SynergyObject.
SynergyObject
(collection, context)[source]¶ Variables: - _collection – Foo
- _cycle_frequency – Bar
-
_add_col
(col, **kwargs)[source]¶ Shortcut to self._context.metas.collections.add
Parameters: col – COL Returns:
-
_add_state
(state, **kwargs)[source]¶ Shortcut to self._context.metas.states.add
Parameters: state – State Returns:
-
_remove_col
(col, **kwargs)[source]¶ Shortcut to self._context.metas.collections.remove
Parameters: col – COL Returns:
-
_remove_state
(state, **kwargs)[source]¶ Shortcut to self._context.metas.states.remove
Parameters: state – State Returns:
-
get_collection
()[source]¶ Return the Collection who contain this
Returns: The Collection who contain this Return type: SynergyCollection
Display¶
Ready-to-use DisplayObjects are available:
- synergine_xyz.display.Pygame.Pygame (you can found example usage here)
- xywold.display.CursesDisplay.CursesDisplay
Signals¶
Hook are available. To trig hook:
>>> Signals.signal(<HOOK NAME>).send(<PARAMETERS>)
Where <HOOK NAME>
is anything you want and <PARAMETERS>
according your callbacks parameters definitions.
To define callback:
>>> Signals.signal(<HOOK NAME>).connect(<A CALLABLE>)
Existing signals are (list of hook names):
- An
Action
class: Trig just afterAction
have been executed. Callback parameters definition is.send(obj: SynergyObject, context: Context)
- synergine.synergy.collection.SynergyCollection.SynergyCollection.SIGNAL_ADD_OBJECT: When object add to a
SynergyCollection
. Callback parameters definition is.send(collection:: SynergyCollection, obj: SynergyObject)
- synergine.synergy.collection.SynergyCollection.SynergyCollection.SIGNAL_REMOVE_OBJECT: When object removed from a
SynergyCollection
. Callback parameters definition is.send(collection:: SynergyCollection, obj: SynergyObject)