chartflow 0.1__py3-none-any.whl

chartflow/fsm/demo_tree.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+import time
+from random import random
+from chartflow.fsm import *
+
+
+class MyLogic(Logic):
+    NAME = "My"
+
+    @sequence("second", "third")
+    def first(self, it):
+        it.now = self.now  # 在 BlackBoard 上动态添加 now 属性
+        return random() < 0.7
+
+    
+    def second(self, it):
+        if it.now == self.now:
+            return None
+        return random() > 0.5
+    
+    
+    @selector("A", "B")
+    def third(self, it):
+        return random() < 0.5
+    
+    def A(self, it):
+        if random() < 0.25: return
+        return random() < 0.5
+    
+    def B(self, it):
+        if random() < 0.25: return
+        return random() < 0.5
+    
+
+    @listen("system")
+    def my_handle(self, data):
+        print(f"{self.name} recv event: {data}")
+
+
+# 创建调度器
+sch = Scheduler()
+cl0 = Logic("My")  # inst 默认是 BlackBoard()
+
+for i in range(10):
+    print("TICK{}".format(sch.tick))
+    sch.handle()

chartflow/fsm/logic.py

@@ -0,0 +1,447 @@
+from __future__ import annotations
+"""
+qfsm Logic Module - Scheduled state machine instances
+
+This module provides the Logic class which extends Stage with scheduler
+integration, lifecycle management, and instance referencing capabilities.
+"""
+
+
+from typing import Any, ClassVar, Self
+
+from chartflow.fsm.stage import Stage
+from chartflow.fsm.scheduler import Scheduler
+
+
+class Logic(Stage):
+    """
+    Scheduled state machine instance with lifecycle management.
+    
+    Logic extends Stage with:
+    - Automatic registration with the Scheduler singleton
+    - 4-phase lifecycle (_check, _enter, _step, _exit)
+    - Instance referencing (ref, refLast, refNext, etc.)
+    - Priority-based execution
+    
+    Class Attributes:
+        NAME: The display name for this logic type (required)
+        PRIORITY: Execution priority (higher = earlier, default: 0)
+        LOG: Whether to log state transitions (default: True)
+    
+    Instance Attributes:
+        alive: Whether instance should continue processing
+        enabled: Whether instance is currently enabled
+        uid: Unique instance identifier
+        priority: Execution priority for this instance
+    
+    Example:
+        class EnemyAI(Logic):
+            NAME = "EnemyAI"
+            PRIORITY = 10
+            
+            def __init__(self, enemy):
+                super().__init__(enemy)
+                self.health = 100
+            
+            def idle(self):
+                if self._inst.player_nearby:
+                    return "chase"
+            
+            def chase(self):
+                if not self._inst.player_nearby:
+                    return "idle"
+                self._inst.move_toward_player()
+    
+    Lifecycle:
+        1. __init__ -> auto-registers with Scheduler
+        2. _check -> validate if should run
+        3. _enter -> first-time initialization (calls onStart)
+        4. _step -> per-tick execution (calls handleStage, onStep)
+        5. _exit -> cleanup when dead (calls onStop)
+    """
+    
+    # Class attributes
+    NAME: ClassVar[str] = "Logic"
+    PRIORITY: ClassVar[int] = 0
+    LOG: ClassVar[bool] = True
+    
+    # Class-level instance tracking by name (name -> {uid: instance})
+    # Using explicit mangled name to allow tests to reset state
+    _Logic__names__: ClassVar[dict[str, dict[int, Logic]]] = {}
+    
+    def __init__(self, inst: Any = None) -> None:
+        """
+        Initialize Logic and auto-register with Scheduler.
+        
+        Args:
+            inst: The bound instance (e.g., game entity)
+            
+        Note:
+            Automatically calls Scheduler().add(self) to register
+            for scheduled execution.
+        """
+        # Instance lifecycle attributes
+        self._alive: bool = True
+        self._enabled: bool = True
+        self._isEntered: bool = False
+
+        super().__init__(inst)
+
+        # Register in __names__ dictionary for instance referencing
+        if self.NAME not in Logic._Logic__names__:
+            Logic._Logic__names__[self.NAME] = {}
+        Logic._Logic__names__[self.NAME][self.uid] = self
+
+        # Auto-register with scheduler
+        Scheduler().add(self)
+
+    
+    # ========================================================================
+    # Lifecycle Methods (called by Scheduler)
+    # ========================================================================
+    
+    def _check(self, is_seek: bool) -> bool:
+        """
+        Check if instance should run this tick.
+        
+        Called by Scheduler during the check phase.
+        
+        Args:
+            is_seek: Whether this is a seek/check-only pass
+            
+        Returns:
+            True if instance should continue processing
+            
+        Override this to add custom validation logic.
+        Example:
+            def _check(self, is_seek):
+                # Only run if entity is active
+                return self._alive and self._inst.is_active
+        """
+        return self._alive and self._enabled
+    
+    def _enter(self) -> None:
+        """
+        Called on first entry (before first _step).
+        
+        Called by Scheduler during the enter phase.
+        Override onStart() for custom initialization.
+        """
+        self._isEntered = True
+        self.onStart(self._inst)
+
+    def _step(self) -> None:
+        """
+        Called each tick during execution.
+        
+        Called by Scheduler during the step phase.
+        Executes handleStage() and calls onStep().
+        """
+        self.handleStage(log=self.LOG)
+        self.onStep(self._inst)
+    
+    def _exit(self) -> None:
+        """
+        Called when instance is removed (alive=False).
+        
+        Called by Scheduler during the exit phase.
+        Unregisters instance and calls onStop().
+        """
+        self.onStop(self._inst)
+    
+    # ========================================================================
+    # Lifecycle Hooks (override in subclasses)
+    # ========================================================================
+    
+    def onStart(self, inst:Any) -> None:
+        """Hook called on first entry. Override for initialization."""
+        pass
+    
+    def onStep(self, inst:Any) -> None:
+        """Hook called each tick after handleStage. Override for per-tick logic."""
+        pass
+    
+    def onStop(self, inst:Any) -> None:
+        """Hook called on removal. Override for cleanup."""
+        pass
+    
+    def onKilled(self, inst:Any) -> None:
+        """Hook called when instance is killed. Override for death handling."""
+        pass
+    
+    # ========================================================================
+    # Reference Methods
+    # ========================================================================
+    
+    def ref(self, name: str) -> Logic | list[Logic] | None:
+        """
+        Get instance(s) by name.
+        
+        Args:
+            name: The NAME of the Logic class to find
+            
+        Returns:
+            - Single Logic instance if only one exists
+            - List of Logic instances if multiple exist
+            - None if no instances exist
+            
+        Example:
+            >>> enemy = self.ref("EnemyAI")
+            >>> players = self.ref("PlayerController")  # May return list
+        """
+        # First try to find by NAME (e.g., "TestLogic")
+        instances = Logic._Logic__names__.get(name, {})
+        if instances:
+            values = list(instances.values())
+            if len(values) == 1:
+                return values[0]
+            return values.copy()
+
+        # If not found, try to find by full name (e.g., "TestLogic0")
+        # Parse name to extract NAME and uid
+        for name_key, name_instances in Logic._Logic__names__.items():
+            for uid, instance in name_instances.items():
+                if instance.name == name:
+                    return instance
+
+        return None
+    
+    def refLast(self) -> Logic | None:
+        """
+        Get the previous instance with the same NAME.
+
+        Returns:
+            Previous instance in the same NAME group, or None
+
+        Example:
+            >>> prev = self.refLast()  # Get previous EnemyAI instance
+        """
+        instances = Logic._Logic__names__.get(self.NAME, {})
+        if not instances:
+            return None
+
+        # Get sorted list of uids to find previous
+        uids = sorted(instances.keys())
+        try:
+            idx = uids.index(self.uid)
+            if idx > 0:
+                return instances[uids[idx - 1]]
+        except ValueError:
+            pass
+        return None
+    
+    def refNext(self) -> Logic | None:
+        """
+        Get the next instance with the same NAME.
+
+        Returns:
+            Next instance in the same NAME group, or None
+
+        Example:
+            >>> next_enemy = self.refNext()  # Get next EnemyAI instance
+        """
+        instances = Logic._Logic__names__.get(self.NAME, {})
+        if not instances:
+            return None
+
+        # Get sorted list of uids to find next
+        uids = sorted(instances.keys())
+        try:
+            idx = uids.index(self.uid)
+            if idx < len(uids) - 1:
+                return instances[uids[idx + 1]]
+        except ValueError:
+            pass
+        return None
+    
+    def refAdjacent(self) -> tuple[Logic | None, Logic | None]:
+        """
+        Get both previous and next instances with the same NAME.
+        
+        Returns:
+            Tuple of (previous_instance, next_instance)
+            
+        Example:
+            >>> prev, next = self.refAdjacent()
+            >>> if prev:
+            ...     print(f"Previous: {prev.uid}")
+            >>> if next:
+            ...     print(f"Next: {next.uid}")
+        """
+        return (self.refLast(), self.refNext())
+    
+    def refHead(self) -> Logic | None:
+        """
+        Get the first instance with the same NAME.
+
+        Returns:
+            First instance in the NAME group, or None
+
+        Example:
+            >>> first_enemy = self.refHead()  # Get first EnemyAI
+        """
+        instances = Logic._Logic__names__.get(self.NAME, {})
+        if not instances:
+            return None
+        # Return instance with smallest uid
+        min_uid = min(instances.keys())
+        return instances[min_uid]
+
+    def refEnd(self) -> Logic | None:
+        """
+        Get the last instance with the same NAME.
+
+        Returns:
+            Last instance in the NAME group, or None
+
+        Example:
+            >>> last_enemy = self.refEnd()  # Get last EnemyAI
+        """
+        instances = Logic._Logic__names__.get(self.NAME, {})
+        if not instances:
+            return None
+        # Return instance with largest uid
+        max_uid = max(instances.keys())
+        return instances[max_uid]
+    
+    # ========================================================================
+    # Properties
+    # ========================================================================
+    
+    @property
+    def scheduler(self):
+        return Scheduler()
+    
+    @property
+    def alive(self) -> bool:
+        """Whether instance should continue processing."""
+        return self._alive
+    
+    @alive.setter
+    def alive(self, value: bool) -> None:
+        """Set alive state. Setting to False triggers removal."""
+        self._alive = value
+        if not value:
+            self.onKilled(self._inst)
+    
+    @property
+    def enabled(self) -> bool:
+        """Whether instance is currently enabled."""
+        return self._enabled
+    
+    @enabled.setter
+    def enabled(self, value: bool) -> None:
+        """Enable or disable instance processing."""
+        self._enabled = value
+    
+    @property
+    def priority(self) -> int:
+        """Execution priority (higher = earlier)."""
+        return self.PRIORITY
+    
+    # ========================================================================
+    # Control Methods
+    # ========================================================================
+    
+    def kill(self) -> None:
+        """Mark instance for removal (sets alive=False)."""
+        self._alive = False
+        # Remove from __names__ registry
+        if self.NAME in Logic._Logic__names__:
+            if self.uid in Logic._Logic__names__[self.NAME]:
+                del Logic._Logic__names__[self.NAME][self.uid]
+            # Clean up empty dicts
+            if not Logic._Logic__names__[self.NAME]:
+                del Logic._Logic__names__[self.NAME]
+    
+    def enable(self) -> None:
+        """Enable instance processing."""
+        self._enabled = True
+    
+    def disable(self) -> None:
+        """Disable instance processing."""
+        self._enabled = False
+
+    
+    # ========================================================================
+    # Scheduling Methods
+    # ========================================================================
+    
+    def schedule(self, delay: int, callback: Any) -> None:
+        """
+        Schedule a callback to run after a delay.
+        
+        Args:
+            delay: Number of ticks to wait
+            callback: Function to call
+        """
+        # Store scheduled callback (implementation depends on scheduler)
+        if not hasattr(self, '_scheduled'):
+            self._scheduled: list[tuple[int, Any]] = []
+        self._scheduled.append((delay, callback))
+    
+    def cancelSchedule(self, callback: Any | None = None) -> bool:
+        """
+        Cancel scheduled callbacks.
+        
+        Args:
+            callback: Specific callback to cancel (None = all)
+            
+        Returns:
+            True if any callbacks were cancelled
+        """
+        if not hasattr(self, '_scheduled'):
+            return False
+        
+        if callback is None:
+            removed = len(self._scheduled) > 0
+            self._scheduled.clear()
+            return removed
+        
+        original_len = len(self._scheduled)
+        self._scheduled = [(d, cb) for d, cb in self._scheduled if cb != callback]
+        return len(self._scheduled) < original_len
+    
+    # ========================================================================
+    # Queue Methods (for priority queue manipulation)
+    # ========================================================================
+    
+    def productQueue(self) -> None:
+        """Move to front of priority queue (highest priority)."""
+        # This would be implemented by the scheduler
+        pass
+    
+    def showQueue(self) -> None:
+        """Show current position in queue (for debugging)."""
+        scheduler = Scheduler()
+        if self in scheduler.updates:
+            idx = scheduler.updates.index(self)
+            print(f"{self._name} at position {idx}")
+    
+    def jumpQueue(self, target: Logic) -> None:
+        """Jump to position relative to target instance."""
+        # Implementation depends on scheduler internals
+        pass
+    
+    def accelerate(self, amount: int = 1) -> None:
+        """Increase priority temporarily."""
+        # Implementation depends on scheduler internals
+        pass
+    
+    def __repr__(self) -> str:
+        """Detailed string representation."""
+        return (
+            f"{self.__class__.__name__}("
+            f"name='{self._name}', "
+            f"uid={self._uid}, "
+            f"alive={self._alive}, "
+            f"enabled={self._enabled}, "
+            f"state={self._current}, "
+            f"priority={self.PRIORITY}"
+            f")"
+        )
+
+
+__all__ = [
+    'Logic',
+]