Merge pull request #22 from YJack0000/feat/python-behavior-system

feat: add injectable Python behavior strategies for Organism

Author: YJack0000

bindings/core/Organism_bindings.cpp

@@ -1,5 +1,6 @@
 #include <pybind11/pybind11.h>
 #include <pybind11/functional.h>
+#include <pybind11/stl.h>
 
 #include <core/Organism.hpp>
 
@@ -17,9 +18,16 @@ void init_Organism(py::module &m) {
         .def("killed", &Organism::killed)
         .def("is_alive", &Organism::isAlive)
         .def("can_reproduce", &Organism::canReproduce)
-        // .def("is_full", &Organism::isFull)
+        .def("add_life_span", &Organism::addLifeSpan, py::arg("amount"))
         .def("reproduce", &Organism::reproduce)
         .def("get_reaction_radius", &Organism::getReactionRadius)
         .def("interact", &Organism::interact)
-        .def("post_iteration", &Organism::postIteration);
+        .def("react", &Organism::react)
+        .def("post_iteration", &Organism::postIteration)
+        .def("set_reaction_strategy", &Organism::setReactionStrategy, py::arg("strategy"),
+             "Set a custom reaction strategy. The callable receives (organism, nearby_objects) "
+             "and should return a (dx, dy) tuple for movement direction, or (0, 0) for no reaction.")
+        .def("set_interaction_strategy", &Organism::setInteractionStrategy, py::arg("strategy"),
+             "Set a custom interaction strategy. The callable receives (organism, nearby_objects) "
+             "and should perform interactions (e.g., eat food, kill organisms).");
 }

examples/custom_behavior.py

@@ -0,0 +1,146 @@
+"""
+Example: Custom Python Behavior Strategies
+
+Demonstrates how to define organism behavior entirely in Python
+without modifying the C++ engine. Two species coexist:
+- Herbivores: only eat food, flee from all organisms
+- Predators: ignore food, chase smaller organisms
+"""
+
+import random
+
+from simevopy import Environment, Food, Genes, Organism
+
+
+# --- Custom Reaction Strategies ---
+
+def herbivore_reaction(organism, nearby_objects):
+    """Herbivores prioritize food, flee from any organism."""
+    my_pos = organism.get_position()
+    nearest_food = None
+    nearest_food_dist = float("inf")
+    nearest_org = None
+    nearest_org_dist = float("inf")
+
+    for obj in nearby_objects:
+        dx = my_pos[0] - obj.get_position()[0]
+        dy = my_pos[1] - obj.get_position()[1]
+        dist = (dx * dx + dy * dy) ** 0.5
+
+        if hasattr(obj, "can_be_eaten") and obj.can_be_eaten():
+            if dist < nearest_food_dist:
+                nearest_food = obj
+                nearest_food_dist = dist
+        elif hasattr(obj, "is_alive") and obj.is_alive():
+            if dist < nearest_org_dist:
+                nearest_org = obj
+                nearest_org_dist = dist
+
+    # Flee from organisms if one is very close
+    if nearest_org and nearest_org_dist < 20:
+        org_pos = nearest_org.get_position()
+        return (my_pos[0] - org_pos[0], my_pos[1] - org_pos[1])
+
+    # Otherwise move toward food
+    if nearest_food:
+        food_pos = nearest_food.get_position()
+        return (food_pos[0] - my_pos[0], food_pos[1] - my_pos[1])
+
+    return (0.0, 0.0)
+
+
+def predator_reaction(organism, nearby_objects):
+    """Predators chase smaller organisms, ignore food."""
+    my_pos = organism.get_position()
+    my_size = organism.get_size()
+
+    nearest_prey = None
+    nearest_prey_dist = float("inf")
+
+    for obj in nearby_objects:
+        if not hasattr(obj, "is_alive") or not obj.is_alive():
+            continue
+        if not hasattr(obj, "get_size"):
+            continue
+        if obj.get_size() >= my_size:
+            continue
+
+        dx = my_pos[0] - obj.get_position()[0]
+        dy = my_pos[1] - obj.get_position()[1]
+        dist = (dx * dx + dy * dy) ** 0.5
+
+        if dist < nearest_prey_dist:
+            nearest_prey = obj
+            nearest_prey_dist = dist
+
+    if nearest_prey:
+        prey_pos = nearest_prey.get_position()
+        return (prey_pos[0] - my_pos[0], prey_pos[1] - my_pos[1])
+
+    return (0.0, 0.0)
+
+
+# --- Custom Interaction Strategies ---
+
+def herbivore_interaction(organism, nearby_objects):
+    """Herbivores only eat food, never attack other organisms."""
+    for obj in nearby_objects:
+        if hasattr(obj, "can_be_eaten") and obj.can_be_eaten():
+            organism.add_life_span(obj.get_energy())
+            obj.eaten()
+
+
+def predator_interaction(organism, nearby_objects):
+    """Predators eat smaller organisms, ignore food."""
+    for obj in nearby_objects:
+        if not hasattr(obj, "is_alive") or not obj.is_alive():
+            continue
+        if not hasattr(obj, "get_size"):
+            continue
+        if organism.get_size() > 1.2 * obj.get_size():
+            organism.add_life_span(obj.get_life_span())
+            obj.killed()
+
+
+def no_life_cost(organism):
+    """Zero life consumption for demo purposes."""
+    return 0
+
+
+def main():
+    env = Environment(500, 500)
+
+    # Create herbivores (small, fast, high awareness)
+    for _ in range(15):
+        dna = chr(60) + chr(15) + chr(80) + chr(0)  # fast, small, aware
+        org = Organism(Genes(dna), no_life_cost)
+        org.set_reaction_strategy(herbivore_reaction)
+        org.set_interaction_strategy(herbivore_interaction)
+        env.add_organism(org, random.uniform(10, 490), random.uniform(10, 490))
+
+    # Create predators (slower, bigger, less awareness)
+    for _ in range(5):
+        dna = chr(30) + chr(80) + chr(60) + chr(0)  # slow, big, moderate awareness
+        org = Organism(Genes(dna), no_life_cost)
+        org.set_reaction_strategy(predator_reaction)
+        org.set_interaction_strategy(predator_interaction)
+        env.add_organism(org, random.uniform(10, 490), random.uniform(10, 490))
+
+    # Add food
+    for _ in range(30):
+        env.add_food(Food(), random.uniform(10, 490), random.uniform(10, 490))
+
+    # Run simulation
+    env.simulate_iteration(200)
+
+    # Report results
+    alive = env.get_all_organisms()
+    print(f"\nAfter 200 iterations:")
+    print(f"  Surviving organisms: {len(alive)}")
+    print(f"  Remaining food: {len(env.get_all_foods())}")
+    print(f"  Food consumed: {env.get_food_consumption_in_iteration()}")
+    print(f"  Dead organisms: {len(env.get_dead_organisms())}")
+
+
+if __name__ == "__main__":
+    main()

include/core/Environment.hpp

@@ -15,9 +15,15 @@
  *
  * Environment owns all simulation objects, delegates spatial lookups to an
  * ISpatialIndex implementation, and drives the interact-react-move lifecycle
- * each iteration. The interaction phase runs single-threaded because it mutates
- * shared state (food eaten flags, organism lifespans). The reaction phase can
- * be parallelized since each organism only writes to its own movement fields.
+ * each iteration. Both phases currently run single-threaded so that Python
+ * strategy callbacks can safely acquire the GIL.
+ *
+ * TODO: Re-enable multi-threaded handleReactions(). The reaction phase only
+ * writes to each organism's own movement fields and is inherently parallelizable.
+ * When Python callbacks are involved, either release the GIL before spawning
+ * worker threads (using py::gil_scoped_release) or detect at runtime whether
+ * any organism has a custom strategy and only fall back to single-threaded in
+ * that case.
  */
 class Environment {
 public:
@@ -26,7 +32,7 @@ class Environment {
      * @param width  The horizontal extent of the simulation area.
      * @param height The vertical extent of the simulation area.
      * @param type   Spatial index implementation: "default" or "optimized".
-     * @param numThreads Number of threads for the parallelizable reaction phase.
+     * @param numThreads Reserved for future multi-threaded reaction phase.
      * @throws std::invalid_argument If type is not "default" or "optimized".
      */
     Environment(int width, int height, std::string type = "default", int numThreads = 1);
@@ -80,9 +86,9 @@ class Environment {
      * @param iterations Number of iterations to simulate.
      * @param on_each_iteration Optional callback invoked after each iteration.
      *
-     * Each iteration proceeds in order: interactions (single-threaded),
-     * reactions (optionally multi-threaded), then post-iteration (life
-     * consumption + movement). Stops early if no organisms or food remain.
+     * Each iteration proceeds in order: interactions, reactions, then
+     * post-iteration (life consumption + movement). Stops early if no
+     * organisms or food remain.
      */
     void simulateIteration(int iterations,
                            std::function<void(const Environment&)> on_each_iteration = nullptr);
@@ -112,7 +118,8 @@ class Environment {
     std::vector<std::shared_ptr<Organism>> deadOrganisms;  ///< Accumulated dead organisms
     unsigned long foodConsumption = 0;                      ///< Running food consumption counter
 
-    int numThreads = 1;  ///< Thread count for the parallelizable reaction phase
+    // TODO: use numThreads to re-enable multi-threaded handleReactions()
+    int numThreads = 1;  ///< Reserved for future multi-threaded reaction phase
     bool verbose = false;
 
     /**
@@ -137,9 +144,9 @@ class Environment {
     /**
      * @brief Run the reaction phase: organisms decide movement direction.
      *
-     * Safe to parallelize because each organism only writes to its own
-     * movement vector and reactionCounter. Uses numThreads worker threads
-     * when numThreads > 1.
+     * Currently runs single-threaded for GIL safety with Python callbacks.
+     * TODO: Re-enable multi-threading -- each organism only writes to its own
+     * movement/reactionCounter fields, so this phase is inherently parallelizable.
      */
     void handleReactions();
 

include/core/Organism.hpp

@@ -12,11 +12,13 @@
 /**
  * @brief A living entity in the simulation that can move, eat, fight, and reproduce.
  *
- * Organisms have gene-derived attributes (speed, size, awareness) that determine
- * their behavior and survival. Each iteration, organisms react to nearby objects
- * (deciding movement direction) and interact with overlapping objects (eating food,
- * killing smaller organisms). Reproduction creates a mutated offspring and halves
- * the parent's lifespan.
+ * Organism behaviour is driven by two pluggable strategy callbacks:
+ *  - **ReactionStrategy** -- decides movement direction based on nearby objects.
+ *  - **InteractionStrategy** -- performs close-range actions (eating, fighting).
+ *
+ * When no custom strategy is set, built-in defaults are used. Custom strategies
+ * are inherited by offspring produced via reproduce(), enabling Python-side
+ * behaviour injection that persists across generations.
  */
 class Organism : public EnvironmentObject {
 public:
@@ -28,6 +30,26 @@ class Organism : public EnvironmentObject {
      */
     using LifeConsumptionCalculator = std::function<uint32_t(const Organism &)>;
 
+    /**
+     * @brief Strategy that decides how an organism reacts to nearby objects.
+     *
+     * Given a reference to the organism and a list of nearby objects (within
+     * the reaction radius), the strategy returns a (dx, dy) movement direction.
+     * Returning {0, 0} signals "no reaction" and the organism keeps wandering.
+     */
+    using ReactionStrategy = std::function<std::pair<float, float>(
+        Organism &, const std::vector<std::shared_ptr<EnvironmentObject>> &)>;
+
+    /**
+     * @brief Strategy that defines close-range interactions with nearby objects.
+     *
+     * Given a reference to the organism and objects within its size radius,
+     * the strategy mutates state directly (e.g. consuming food, killing smaller
+     * organisms). The default eats food and preys on organisms less than 2/3 its size.
+     */
+    using InteractionStrategy = std::function<void(
+        Organism &, const std::vector<std::shared_ptr<EnvironmentObject>> &)>;
+
     /** @brief Construct a default organism with preset genes and 500 lifespan. */
     Organism();
 
@@ -84,32 +106,75 @@ class Organism : public EnvironmentObject {
      */
     bool canReproduce() const;
 
+    /**
+     * @brief Add (or subtract) life-span points.
+     *
+     * Exposed publicly so that custom InteractionStrategy callbacks (including
+     * those written in Python) can reward or penalise organisms.
+     *
+     * @param amount Points to add; negative values reduce life-span.
+     */
+    void addLifeSpan(float amount);
+
     ~Organism() {};
 
+    // ── Behaviour injection ─────────────────────────────────────────────
+
+    /**
+     * @brief Replace the reaction strategy with a custom implementation.
+     *
+     * The strategy is propagated to offspring during reproduce(). Pass nullptr
+     * or an empty std::function to revert to the built-in default.
+     *
+     * @param strategy Callable matching the ReactionStrategy signature.
+     */
+    void setReactionStrategy(ReactionStrategy strategy);
+
+    /**
+     * @brief Replace the interaction strategy with a custom implementation.
+     *
+     * The strategy is propagated to offspring during reproduce(). Pass nullptr
+     * or an empty std::function to revert to the built-in default.
+     *
+     * @param strategy Callable matching the InteractionStrategy signature.
+     */
+    void setInteractionStrategy(InteractionStrategy strategy);
+
+    /**
+     * @brief Check whether this organism has any custom (non-default) strategy set.
+     * @return true if either reactionStrategy or interactionStrategy is set.
+     *
+     * Used by Environment to decide whether multi-threaded execution is safe.
+     * Custom strategies may involve Python callbacks that require the GIL.
+     */
+    bool hasCustomStrategy() const;
+
+    // ── Actions ─────────────────────────────────────────────────────────
+
     /**
      * @brief Decide movement direction based on nearby objects within reaction radius.
      * @param reactableObjects Objects detected within the organism's reaction radius.
      *
-     * Finds the nearest valid object and sets movement direction accordingly:
-     * flee from larger organisms, chase smaller organisms, move toward food.
-     * Only triggers once per iteration (guarded by reactionCounter).
-     * Safe to call in parallel -- only writes to this organism's own fields.
+     * Delegates to the custom ReactionStrategy if one has been set, otherwise
+     * falls back to defaultReaction(). Only triggers once per iteration
+     * (guarded by reactionCounter).
      */
     void react(const std::vector<std::shared_ptr<EnvironmentObject>> &reactableObjects);
 
     /**
      * @brief Interact with objects within the organism's body size range.
      * @param interactableObjects Objects overlapping the organism's size radius.
      *
-     * Eats available food (gaining its energy) and kills smaller organisms
-     * (absorbing their remaining lifespan). Must run single-threaded because
-     * it mutates shared state (food eaten flags, other organisms' lifespans).
+     * Delegates to the custom InteractionStrategy if set, otherwise uses
+     * defaultInteraction(). Must run single-threaded because it mutates
+     * shared state (food eaten flags, other organisms' lifespans).
      */
     void interact(const std::vector<std::shared_ptr<EnvironmentObject>> &interactableObjects);
 
     /**
      * @brief Create a mutated offspring organism.
-     * @return A new organism with mutated genes, inheriting the life consumption calculator.
+     * @return A new organism with mutated genes, inheriting the life consumption
+     *         calculator and any custom behavior strategies.
      *
      * The parent's lifespan is halved. The child is placed at a small offset
      * from the parent's position.
@@ -124,6 +189,8 @@ class Organism : public EnvironmentObject {
 private:
     Genes genes;                                           ///< Genetic data driving attributes
     LifeConsumptionCalculator lifeConsumptionCalculator;   ///< Optional custom life drain formula
+    ReactionStrategy reactionStrategy;                     ///< Optional custom reaction behaviour
+    InteractionStrategy interactionStrategy;               ///< Optional custom interaction behaviour
     float lifeSpan;                                        ///< Remaining life points
 
     /**
@@ -144,6 +211,12 @@ class Organism : public EnvironmentObject {
      * not exceed the organism's speed.
      */
     void makeMove();
+
+    // Default built-in strategies
+    static std::pair<float, float> defaultReaction(
+        Organism &self, const std::vector<std::shared_ptr<EnvironmentObject>> &objects);
+    static void defaultInteraction(
+        Organism &self, const std::vector<std::shared_ptr<EnvironmentObject>> &objects);
 };
 
 #endif