kotonebot 0.4.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/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: ...

kotonebot/core/entities/template_match.py

@@ -0,0 +1,198 @@
+from typing import TYPE_CHECKING, Generic
+from typing_extensions import Unpack, override
+
+from kotonebot.devtools.project.schema import BoolProp, FloatProp, ImageProp, RectProp
+from kotonebot.primitives import Rect, ImageSlice
+from kotonebot.devtools import EditorMetadata
+
+from .base import Prefab, FindKwargs, GameObjectType, ClickKwargs as _ClickKwargs, WaitKwargs as _WaitKwargs
+
+
+class TemplateMatchFindKargs(FindKwargs[GameObjectType], total=False):
+    threshold: float | None
+    """匹配阈值
+    
+    如果指定，则覆盖 TemplateMatchPrefab 中定义的 threshold 属性。
+    """
+    colored: bool | None
+    """是否匹配颜色
+    
+    如果指定，则覆盖 TemplateMatchPrefab 中定义的 colored 属性。
+    """
+    region: Rect | None
+    """搜索区域
+    
+    如果指定，则覆盖 TemplateMatchPrefab 中定义的 region 属性。
+    """
+
+class ClickKwargs(TemplateMatchFindKargs[GameObjectType], _ClickKwargs[GameObjectType], Generic[GameObjectType], total=False): pass
+class WaitKwargs(TemplateMatchFindKargs[GameObjectType], _WaitKwargs[GameObjectType], Generic[GameObjectType], total=False): pass
+
+
+class TemplateMatchPrefab(Prefab[GameObjectType]):
+    """基于模版匹配的 Prefab"""
+    template: ImageSlice
+    """[必填] 用于匹配的模版图像"""
+    fixed: bool = False
+    """[可选] 是否固定位置。
+
+    当 `fixed` 为 True 时，匹配将限定在 `template.slice_rect`（若存在）定义的区域内。
+    若 `template` 无 `slice_rect`，会在运行时抛出 ValueError，以提示生成代码或资源定义不完整。
+    """
+    region: Rect | None = None
+    """[可选] 限定搜索区域
+    
+    默认为 None（全屏搜索）。
+    """
+    threshold: float = 0.8
+    """[可选] 匹配阈值
+    
+    范围 0.0 - 1.0，默认为 0.8。
+    """
+    colored: bool = False
+    """[可选] 是否匹配颜色
+    
+    默认为 False（不匹配颜色）。
+    """
+
+    class _Editor(EditorMetadata):
+        name = '模版'
+        description = '基于模版匹配来寻找对象'
+        primary_prop = 'template'
+        icon = 'media'
+        shortcut = 't'
+        props = {
+            'template':  ImageProp(label='模版图像', description='用于匹配的模版图像', default_value=None),
+            'fixed': BoolProp(label='固定位置', description='对象位置是否固定不变，若固定可提升匹配速度', default_value=False),
+            'region': RectProp(label='搜索区域', description='限定搜索区域以提升匹配速度', default_value=None),
+            'threshold': FloatProp(label='匹配阈值', description='模版匹配的相似度阈值，范围 0.0 - 1.0', min=0.0, max=1.0, default_value=0.8),
+            'colored': BoolProp(label='匹配颜色', description='是否在匹配时考虑颜色信息', default_value=False),
+        }
+
+
+    @override
+    @classmethod
+    def find(cls, **kwargs: Unpack[TemplateMatchFindKargs[GameObjectType]]) -> GameObjectType | None:
+        from kotonebot import image
+        predicate = kwargs.get('predicate')
+        threshold_override = kwargs.get('threshold')
+        threshold = cls.threshold if threshold_override is None else threshold_override
+        colored_override = kwargs.get('colored')
+        colored = cls.colored if colored_override is None else colored_override
+        region = kwargs.get('region', cls.region)
+        # If prefab is fixed and no explicit region provided, use template.slice_rect
+        if region is None and cls.fixed:
+            slice_rect = cls.template.slice_rect
+            if slice_rect is None:
+                raise ValueError(f"Prefab {cls.__name__} is marked fixed but template has no slice_rect")
+            region = slice_rect
+        result = image.find(
+            cls.template.pixels,
+            rect=region,
+            threshold=threshold,
+            colored=colored,
+        )
+        if result is None:
+            return None
+        obj_class = cls._get_object_class()
+        obj = obj_class()
+        obj.rect = result.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[TemplateMatchFindKargs[GameObjectType]]) -> list[GameObjectType]:
+        from kotonebot import image
+        predicate = kwargs.get('predicate')
+        threshold_override = kwargs.get('threshold')
+        threshold = cls.threshold if threshold_override is None else threshold_override
+        colored_override = kwargs.get('colored')
+        colored = cls.colored if colored_override is None else colored_override
+        region = kwargs.get('region', cls.region)
+        if region is None and cls.fixed:
+            slice_rect = cls.template.slice_rect
+            if slice_rect is None:
+                raise ValueError(f"Prefab {cls.__name__} is marked fixed but template has no slice_rect")
+            region = slice_rect
+        results = image.find_all(
+            cls.template.pixels,
+            rect=region,
+            threshold=threshold,
+            colored=colored,
+        )
+        obj_class = cls._get_object_class()
+        objects: list[GameObjectType] = []
+        for r in results:
+            obj = obj_class()
+            obj.rect = r.rect
+            obj.prefab = cls
+            if predicate is None or predicate(obj):
+                objects.append(obj)
+        return objects
+
+    @override
+    @classmethod
+    def require(cls, **kwargs: Unpack[TemplateMatchFindKargs[GameObjectType]]) -> GameObjectType:
+        from kotonebot import image, device
+        from kotonebot.backend.image import TemplateNoMatchError
+        predicate = kwargs.get('predicate')
+        threshold_override = kwargs.get('threshold')
+        threshold = cls.threshold if threshold_override is None else threshold_override
+        colored_override = kwargs.get('colored')
+        colored = cls.colored if colored_override is None else colored_override
+        region = kwargs.get('region', cls.region)
+        if region is None and cls.fixed:
+            slice_rect = cls.template.slice_rect
+            if slice_rect is None:
+                raise ValueError(f"Prefab {cls.__name__} is marked fixed but template has no slice_rect")
+            region = slice_rect
+        if predicate is None:
+            # 直接使用 expect，未找到会抛出 TemplateNoMatchError
+            result = image.expect(
+                cls.template.pixels,
+                rect=region,
+                threshold=threshold,
+                colored=colored,
+            )
+            obj_class = cls._get_object_class()
+            obj = obj_class()
+            obj.rect = result.rect
+            obj.prefab = cls
+            return obj
+        else:
+            # 需要满足 predicate，则遍历所有匹配项
+            results = image.find_all(
+                cls.template.pixels,
+                rect=region,
+                threshold=threshold,
+                colored=colored,
+            )
+            obj_class = cls._get_object_class()
+            for r in results:
+                obj = obj_class()
+                obj.rect = r.rect
+                if predicate(obj):
+                    obj.prefab = cls
+                    return obj
+            # 没有任何匹配满足 predicate，抛出未找到异常
+            raise TemplateNoMatchError(device.screenshot(), cls.template.pixels)
+
+    if TYPE_CHECKING:
+        # 这些方法只需要重载声明，实际实现由基类提供不变
+        @classmethod
+        def exists(cls, **kwargs: Unpack[TemplateMatchFindKargs[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: ...

kotonebot/devtools/__init__.py

@@ -0,0 +1,42 @@
+from .resgen import (
+    CodeWriter,
+    ResourceNode,
+    ClassNode,
+    SchemaParser,
+    StandardGenerator,
+    ParserRegistry,
+    KotoneV1Parser,
+    BasicSpriteParser,
+    to_camel_case,
+    unify_path,
+    build_class_tree,
+    ImageProcessor,
+)
+
+from .project.schema import EditorMetadata
+
+__all__ = [
+    # core
+    "CodeWriter",
+    "ResourceNode",
+    "ClassNode",
+    "SchemaParser",
+
+    # generator
+    "StandardGenerator",
+
+    # parsers
+    "ParserRegistry",
+    "KotoneV1Parser",
+    "BasicSpriteParser",
+
+    # utils
+    "to_camel_case",
+    "unify_path",
+    "build_class_tree",
+    "ImageProcessor",
+
+    # plugin
+    "EditorMetadata",
+]
+