kotonebot 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

kotonebot/config/config.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Callable
+from contextvars import ContextVar
+
+if TYPE_CHECKING:
+    from kotonebot import Loop
+    from kotonebot.client.scaler import AbstractScaler
+from kotonebot.primitives import Size
+
+@dataclass
+class DeviceConfig:
+    default_scaler_factory: 'Callable[[], AbstractScaler]'
+    """Device 类默认使用缩放方法类的构造器。
+    
+    构造 Device 实例时，可以在构造方法中指定 scaler。若未指定，则使用此处的默认值。
+    默认使用的 scaler 为 :class:`ProportionalScaler`，即等比例缩放。对于非等比例缩放，
+    会直接抛出异常。
+    """
+    default_logic_resolution: Size | None
+    """Device 默认逻辑分辨率。
+    
+    若为 None，则不进行缩放。
+    """
+
+
+@dataclass
+class LoopConfig:
+    loop_callbacks: 'list[Callable[[Loop], None]]' = field(default_factory=list)
+    """全局 Loop 回调函数。
+    
+    每次 Loop 循环一次时，都会调用此处的处理函数。
+    可以在这里放置一些需要全局处理的内容，如网络错误等。
+    """
+
+@dataclass
+class Config:
+    device: DeviceConfig
+    loop: LoopConfig
+
+
+_global_config: ContextVar[Config | None] = ContextVar('kotonebot_global_config', default=None)
+
+def conf(*, auto_create: bool = True) -> Config:
+    """获取全局配置对象。
+
+    :return: 全局配置对象。
+    """
+    c = _global_config.get()
+    if c is None:
+        if not auto_create:
+            raise RuntimeError('Global config is not set.')
+        from kotonebot.client.scaler import ProportionalScaler
+        c = Config(
+            device=DeviceConfig(
+                default_scaler_factory=lambda: ProportionalScaler(),
+                default_logic_resolution=None
+            ),
+            loop=LoopConfig()
+        )
+        _global_config.set(c)
+    return c

kotonebot/config/manager.py

@@ -1,36 +1,36 @@
-import os
-from typing import Type, Generic, TypeVar
-
-from .base_config import RootConfig, UserConfig
-
-T = TypeVar('T')
-
-def load_config(
-    config_path: str,
-    *,
-    type: Type[T],
-    use_default_if_not_found: bool = True
-) -> RootConfig[T]:
-    """
-    从指定路径读取配置文件
-
-    :param config_path: 配置文件路径
-    :param use_default_if_not_found: 如果配置文件不存在，是否使用默认配置
-    """
-    if not os.path.exists(config_path):
-        if use_default_if_not_found:
-            return RootConfig[type]()
-        else:
-            raise FileNotFoundError(f"Config file not found: {config_path}")
-    
-    with open(config_path, 'r', encoding='utf-8') as f:
-        return RootConfig[type].model_validate_json(f.read())
-
-def save_config(
-    config: RootConfig[T],
-    config_path: str,
-):
-    """将配置保存到指定路径"""
-    RootConfig[T].model_validate(config)
-    with open(config_path, 'w+', encoding='utf-8') as f:
-        f.write(config.model_dump_json(indent=4))
+import os
+from typing import Type, Generic, TypeVar
+
+from .base_config import RootConfig, UserConfig
+
+T = TypeVar('T')
+
+def load_config(
+    config_path: str,
+    *,
+    type: Type[T],
+    use_default_if_not_found: bool = True
+) -> RootConfig[T]:
+    """
+    从指定路径读取配置文件
+
+    :param config_path: 配置文件路径
+    :param use_default_if_not_found: 如果配置文件不存在，是否使用默认配置
+    """
+    if not os.path.exists(config_path):
+        if use_default_if_not_found:
+            return RootConfig[type]()
+        else:
+            raise FileNotFoundError(f"Config file not found: {config_path}")
+    
+    with open(config_path, 'r', encoding='utf-8') as f:
+        return RootConfig[type].model_validate_json(f.read())
+
+def save_config(
+    config: RootConfig[T],
+    config_path: str,
+):
+    """将配置保存到指定路径"""
+    RootConfig[T].model_validate(config)
+    with open(config_path, 'w+', encoding='utf-8') as f:
+        f.write(config.model_dump_json(indent=4))

kotonebot/core/__init__.py

@@ -0,0 +1,13 @@
+from .entities.base import Prefab
+from .entities.template_match import TemplateMatchPrefab, TemplateMatchFindKargs
+from .entities.ocr import OcrPrefab, OcrFindKargs
+from .entities.base import GameObject
+from .entities.base import GameObjectType
+from .entities.compound import AnyOf
+
+__all__ = [
+    'Prefab', 'TemplateMatchPrefab', 'OcrPrefab',
+    'GameObject',
+    'GameObjectType',
+    'AnyOf'
+]

kotonebot/core/entities/base.py

@@ -0,0 +1,182 @@
+import time
+from abc import ABC
+from typing import Any, Callable, Type, cast, get_args
+from typing_extensions import Generic, TypeVar, Unpack, TypedDict
+
+from kotonebot.primitives import Rect
+from kotonebot.backend.context.context import manual_context
+
+GameObjectType = TypeVar('GameObjectType', bound='GameObject', default='GameObject')
+
+class FindKwargs(TypedDict, Generic[GameObjectType], total=False):
+    predicate: 'Callable[[GameObjectType], bool] | None'
+
+
+class ClickKwargs(FindKwargs[GameObjectType], Generic[GameObjectType], total=False):
+    pass
+
+class WaitKwargs(FindKwargs[GameObjectType], Generic[GameObjectType], total=False):
+    timeout: float | None
+    interval: float | None
+
+
+class Prefab(Generic[GameObjectType], ABC):
+    __object_class__: Type[GameObjectType] | None = None
+    display_name: str | None = None
+    """展示名称
+    
+    可选，用于在编辑器或日志中显示更友好的名称。
+    如果未设置，则使用类名。
+    """
+
+    @classmethod
+    def _get_object_class(cls) -> Type[GameObjectType]:
+        """
+        核心魔法：获取用于实例化的类。
+        优先使用显式定义的 object_class，
+        如果没有，则尝试从泛型定义中推断。
+        """
+        # 1. 如果用户手动定义了，直接用
+        if cls.__object_class__ is not None:
+            return cls.__object_class__
+
+        # 2. 尝试从 __orig_bases__ 推断
+        # 遍历基类，寻找 Prefab[T] 的定义
+        for base in getattr(cls, "__orig_bases__", []):
+            origin = getattr(base, "__origin__", None)
+            # 检查这个基类是不是 Prefab (或者其子类)
+            if origin is not None and issubclass(origin, Prefab):
+                args = get_args(base)
+                if args and isinstance(args[0], type) and issubclass(args[0], GameObject):
+                    # 缓存结果，下次不用再推断
+                    cls.__object_class__ = args[0]
+                    return cls.__object_class__
+        # 3. 如果都失败了，回退到默认的 GameObject
+        # (这通常发生在用户没有指定泛型参数时，如 class MyPrefab(TemplateMatchPrefab): ...)
+        return cast(Type[GameObjectType], GameObject)
+
+    @classmethod
+    def find(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> GameObjectType | None:
+        """在屏幕画面中寻找当前 Prefab，并返回对应的第一个 GameObject 实例。
+
+        :return: 寻找结果。如果没有找到，返回 None。
+        """
+        raise NotImplementedError
+    
+    @classmethod
+    def find_all(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> list[GameObjectType]:
+        """在屏幕画面中寻找当前 Prefab，并返回对应的所有 GameObject 实例。
+
+        :return: 寻找结果列表。如果没有找到，返回空列表。
+        """
+        raise NotImplementedError
+    
+    @classmethod
+    def require(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> GameObjectType:
+        """在屏幕画面中寻找当前 Prefab，并返回对应的第一个 GameObject 实例。
+        
+        此方法与 find 类似，但如果没有找到任何结果，则会抛出异常。
+
+        :raises: 如果没有找到，抛出异常。
+        :return: 寻找结果。
+        """
+        raise NotImplementedError
+    
+    @classmethod
+    def exists(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> bool:
+        """判断当前 Prefab 是否存在于屏幕画面中。
+        
+        此方法为 find 的简化版，仅返回是否存在。
+        相当于 ``Prefab.find(...) is not None``。
+        
+        :return: 如果存在，返回 True；否则返回 False。
+        """
+        return cls.find(**kwargs) is not None
+
+    @classmethod
+    def click(cls, **kwargs: Unpack[ClickKwargs[GameObjectType]]) -> None:
+        """在屏幕画面中寻找当前 Prefab，并点击第一个找到的 GameObject 实例。
+        
+        该方法会调用 require 方法，因此如果没有找到任何结果，则会抛出异常。
+        """
+        return cls.require(**kwargs).click()
+    
+    @classmethod
+    def try_click(cls, **kwargs: Unpack[ClickKwargs[GameObjectType]]) -> bool:
+        """尝试点击当前 Prefab 的第一个找到的 GameObject 实例。
+        
+        :return: 如果找到了对象并成功点击，返回 True；否则返回 False。
+        """
+        obj = cls.find(**kwargs)
+        if obj is not None:
+            obj.click()
+            return True
+        return False
+    
+    @classmethod
+    def wait(
+        cls,
+        **kwargs: Unpack[WaitKwargs[GameObjectType]],
+    ) -> GameObjectType:
+        """等待当前 Prefab 出现。
+        
+        若指定时间内未找到，则抛出超时异常（wait 不再返回 None）。
+        """
+        # 从 kwargs 中分离出用于等待控制的参数，剩下的传递给 `find`
+        timeout = kwargs.pop("timeout", None)
+        interval = kwargs.pop("interval", None)
+        start_time = time.time()
+        ctx = manual_context('auto')
+        with ctx:
+            while True:
+                obj = cls.find(**kwargs)
+                if obj is not None:
+                    return obj
+                from kotonebot import sleep
+                sleep(interval or 1.0)
+                if timeout is not None:
+                    elapsed = time.time() - start_time
+                    if elapsed >= timeout:
+                        raise TimeoutError(f"Timeout when waiting for {cls.__name__}（{timeout} s）")
+
+    @classmethod
+    def try_wait(
+        cls,
+        **kwargs: Unpack[WaitKwargs[GameObjectType]],
+    ) -> GameObjectType | None:
+        """尝试等待当前 Prefab 出现。
+
+        若指定时间内未找到，则返回 None。
+        """
+        try:
+            return cls.wait(**kwargs)
+        except TimeoutError:
+            return None
+
+class GameObject:
+    """## GameObject
+    GameObject（游戏对象），游戏物体/UI 的基类，所有通过一系列方式从屏幕画面上寻找到的结果都应以 GameObject 的形式展示。
+    
+    GameObject 本身仅包含基础属性。如果你需要自定义 GameObject 的属性或行为，可以继承 GameObject 并使用你自己的类。
+    """
+    rect: Rect
+    """对象在屏幕上的范围"""
+    display_name: str | None = None
+    """展示名称
+    
+    可选，用于在编辑器或日志中显示更友好的名称。
+    如果未设置，则使用类名。
+    """
+    prefab: type[Prefab[Any]]
+    """当前对象对应的 Prefab 类"""
+
+    def click(self) -> None:
+        """点击当前对象的中心位置。"""
+        from kotonebot import device
+        device.click(self.rect.center)
+
+    def double_click(self) -> None:
+        """双击当前对象的中心位置。"""
+        from kotonebot import device
+        device.double_click(*self.rect.center)
+

kotonebot/core/entities/compound.py

@@ -0,0 +1,75 @@
+from typing import Type, Sequence, cast, Any
+from typing_extensions import Unpack, override
+from kotonebot.core.entities.base import FindKwargs, GameObjectType
+from .base import Prefab
+
+
+class AnyOf(Prefab[Any]):
+    """
+    复合 Prefab，用于匹配给定的任意一个 Prefab。
+    
+    作为一个 Class，它可以通过两种方式使用：
+    1. 继承定义：
+       class MyButton(AnyOf):
+           options = [ConfirmButton, CancelButton]
+           
+    2. 动态泛型（推荐）：
+       MyButton = AnyOf[ConfirmButton, CancelButton]
+    """
+    options: Sequence[Type[Prefab]] = []
+
+    def __class_getitem__(cls, items: Type[Prefab] | tuple[Type[Prefab], ...]):
+        """
+        允许使用 AnyOf[PrefabA, PrefabB] 的语法动态生成子类。
+        """
+        if not isinstance(items, tuple):
+            items = (items,)
+            
+        # 动态创建一个新的类，名字由所有子 Prefab 的名字拼接而成
+        name = f"AnyOf_{'_'.join(i.__name__ for i in items)}"
+        return type(name, (cls,), {'options': items})
+
+    @override
+    @classmethod
+    def find(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> GameObjectType | None:
+        # Cast kwargs to Any to bypass contravariance checks on predicate
+        unsafe_kwargs = cast(dict[str, Any], kwargs)
+        
+        for prefab in cls.options:
+            obj = prefab.find(**unsafe_kwargs)
+            if obj is not None:
+                # 强制转换为 GameObjectType，假设用户定义的 options 均符合泛型约束
+                return cast(GameObjectType, obj)
+        return None
+
+    @override
+    @classmethod
+    def find_all(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> list[GameObjectType]:
+        unsafe_kwargs = cast(dict[str, Any], kwargs)
+        results: list[GameObjectType] = []
+        for prefab in cls.options:
+            found = prefab.find_all(**unsafe_kwargs)
+            # 列表协变问题，需要强制转换
+            results.extend(cast(list[GameObjectType], found))
+        return results
+
+    @override
+    @classmethod
+    def exists(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> bool:
+        unsafe_kwargs = cast(dict[str, Any], kwargs)
+        for prefab in cls.options:
+            if prefab.exists(**unsafe_kwargs):
+                return True
+        return False
+
+    @override
+    @classmethod
+    def require(cls, **kwargs: Unpack[FindKwargs[GameObjectType]]) -> GameObjectType:
+        unsafe_kwargs = cast(dict[str, Any], kwargs)
+        for prefab in cls.options:
+            obj = prefab.find(**unsafe_kwargs)
+            if obj is not None:
+                return cast(GameObjectType, obj)
+        
+        names = ", ".join([p.__name__ for p in cls.options])
+        raise RuntimeError(f"AnyOf: Could not find any of the following prefabs: [{names}]")

kotonebot/core/entities/ocr.py

@@ -0,0 +1,117 @@
+from typing import Generic, TYPE_CHECKING
+from typing_extensions import Unpack, override
+
+from kotonebot.devtools.project.schema import StrProp, RectProp
+from kotonebot.primitives import Rect
+from kotonebot.devtools import EditorMetadata
+
+from .base import Prefab, FindKwargs, GameObjectType, ClickKwargs as _ClickKwargs, WaitKwargs as _WaitKwargs
+
+
+class OcrFindKargs(FindKwargs[GameObjectType], total=False):
+    region: Rect | None
+    """搜索区域
+    
+    如果指定，则覆盖 OcrPrefab 中定义的 region 属性。
+    """
+
+class ClickKwargs(OcrFindKargs[GameObjectType], _ClickKwargs[GameObjectType], Generic[GameObjectType], total=False): pass
+class WaitKwargs(OcrFindKargs[GameObjectType], _WaitKwargs[GameObjectType], Generic[GameObjectType], total=False): pass
+
+
+class OcrPrefab(Prefab[GameObjectType]):
+    """基于 Ocr 的 Prefab"""
+    pattern: str
+    region: Rect | None = None
+
+    class _Editor(EditorMetadata):
+        name = 'OCR'
+        description = '基于 OCR + 文字匹配来识别对象'
+        primary_prop = 'region'
+        icon = 'search-text'
+        shortcut = 'o'
+        props = {
+            'pattern':  StrProp(label='匹配文本', description='用于匹配的文本内容', default_value=''),
+            'region': RectProp(label='搜索区域', description='限定搜索区域以提升识别速度', default_value=None),
+        }
+
+    @override
+    @classmethod
+    def find(cls, **kwargs: Unpack[OcrFindKargs[GameObjectType]]) -> GameObjectType | None:
+        from kotonebot import ocr
+        predicate = kwargs.get('predicate')
+        region = kwargs.get('region', cls.region)
+        result = ocr.find(cls.pattern, rect=region)
+        if result is None:
+            return None
+        obj_class = cls._get_object_class()
+        obj = obj_class()
+        # 使用原图坐标
+        obj.rect = result.original_rect
+        obj.prefab = cls
+        if predicate is not None and not predicate(obj):
+            return None
+        return obj
+
+    @override
+    @classmethod
+    def find_all(cls, **kwargs: Unpack[OcrFindKargs[GameObjectType]]) -> list[GameObjectType]:
+        from kotonebot import ocr
+        predicate = kwargs.get('predicate')
+        region = kwargs.get('region', cls.region)
+        # 获取所有 OCR 结果后按文本过滤
+        results = ocr.ocr(rect=region)
+        obj_class = cls._get_object_class()
+        objects: list[GameObjectType] = []
+        for r in results:
+            if r.text == cls.pattern:
+                obj = obj_class()
+                obj.rect = r.original_rect
+                obj.prefab = cls
+                if predicate is None or predicate(obj):
+                    objects.append(obj)
+        return objects
+
+    @override
+    @classmethod
+    def require(cls, **kwargs: Unpack[OcrFindKargs[GameObjectType]]) -> GameObjectType:
+        from kotonebot import ocr, device
+        from kotonebot.backend.ocr import TextNotFoundError
+        predicate = kwargs.get('predicate')
+        region = kwargs.get('region', cls.region)
+        if predicate is None:
+            result = ocr.expect(cls.pattern, rect=region)
+            obj_class = cls._get_object_class()
+            obj = obj_class()
+            obj.rect = result.original_rect
+            obj.prefab = cls
+            return obj
+        else:
+            # 扫描所有 OCR 结果，匹配文本并套用 predicate
+            results = ocr.ocr(rect=cls.region)
+            obj_class = cls._get_object_class()
+            for r in results:
+                if r.text == cls.pattern:
+                    obj = obj_class()
+                    obj.rect = r.original_rect
+                    if predicate(obj):
+                        obj.prefab = cls
+                        return obj
+            raise TextNotFoundError(cls.pattern, device.screenshot())
+    
+    if TYPE_CHECKING:
+        # 这些方法只需要重载声明，实际实现由基类提供不变
+        @classmethod
+        def exists(cls, **kwargs: Unpack[OcrFindKargs[GameObjectType]]) -> bool: ...
+        
+        @classmethod
+        def click(cls, **kwargs: Unpack[ClickKwargs[GameObjectType]]) -> None: ...
+
+        @classmethod
+        def wait(cls, **kwargs: Unpack[WaitKwargs[GameObjectType]]) -> GameObjectType: ...
+        
+        @classmethod
+        def try_click(cls, **kwargs: Unpack[ClickKwargs[GameObjectType]]) -> bool: ...
+        
+        @classmethod
+        def try_wait(cls, **kwargs: Unpack[WaitKwargs[GameObjectType]]) -> GameObjectType | None: ...