@bettergi/utils 0.0.4 → 0.0.6

package/README.md

@@ -8,9 +8,27 @@ npm install @bettergi/utils
 
 ## 函数清单
 
+### 游戏内操作
+
+```ts
+import { openMenu, openMenuPage, openPaimonMenu, setTime } from "@bettergi/utils";
+
+// 打开派蒙菜单
+await openPaimonMenu();
+
+// 打开菜单
+await openMenu("邮件");
+
+// 打开菜单页面
+await openMenuPage("问卷");
+
+// 调整游戏时间
+await setTime("evening");
+```
+
 ### 图文识别
 
-> 对 RecognitionObject 代码的封装，对于简单的 OCR 操作，无需写复杂的代码。
+> 对 RecognitionObject 代码的封装，对于简单的找图、找字操作，不再需要编写复杂的代码。
 
 ```ts
 import {
@@ -41,7 +59,7 @@ const t2 = findTextInDirection("师傅", true, true, "east");
 const t3 = findTextWithinBounds("确认", false, true, 960, 540, 960, 540);
 ```
 
-### 行为
+### 行为流程
 
 > 对脚本开发过程中常见工作流的抽象，例如：等待 XXX 完成/出现/消失。
 
@@ -58,7 +76,44 @@ const done = await waitUntil(
 if (!done) throw new Error("关闭页面超时");
 ```
 
-### 存储
+### 鼠标操作
+
+> 对常见鼠标操作的封装，如鼠标滚动、拖拽等。
+
+```ts
+import {
+  mouseScrollDown,
+  mouseScrollDownLines,
+  mouseScrollUp,
+  mouseScrollUpLines,
+  mouseSlide,
+  mouseSlideX,
+  mouseSlideY
+} from "@bettergi/utils";
+
+// 鼠标滚轮向上滚动 175 像素
+await mouseScrollUp(175);
+
+// 鼠标滚轮向下滚动 175 像素
+await mouseScrollDown(175);
+
+// 鼠标滚轮向上滚动 99 行，行高 175（默认：背包物品行高）
+await mouseScrollUpLines(99);
+
+// 鼠标滚轮向下滚动 1 行，行高 115（自定义：商店物品行高）
+await mouseScrollDownLines(1, 115);
+
+// 鼠标从 (745, 610) 拖拽到 (1280, 610)
+await mouseSlide(745, 610, 1280, 610);
+
+// 鼠标从 (745, 610) 向右拖拽 435 像素
+await mouseSlideX(745, 610, 435);
+
+// 鼠标从 (1290, 140) 向下拖拽 175 像素
+await mouseSlideY(1290, 140, 175);
+```
+
+### 数据存储
 
 > 对象数据持久化，通过 Proxy 实现自动存储。从而可以无感知地读取/更新数据，而无需考虑如何持久化。
 

package/dist/flow.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 等待直到条件满足或超时
+ * @param condition 等待的条件判断函数，返回 true 表示条件满足
+ * @param timeout 超时时间（毫秒），默认 3000 毫秒
+ * @param interval 等待间隔（毫秒），默认 300 毫秒
+ * @param action 每次等待循环中执行的操作（可选）
+ * @returns - true  在超时前条件已满足
+ *          - false 在超时后条件仍未满足
+ */
+export declare const waitUntil: (condition: (context: Record<string, any>) => boolean, timeout?: number, interval?: number, action?: (context: Record<string, any>) => void) => Promise<boolean>;

package/dist/flow.js

@@ -0,0 +1,20 @@
+/**
+ * 等待直到条件满足或超时
+ * @param condition 等待的条件判断函数，返回 true 表示条件满足
+ * @param timeout 超时时间（毫秒），默认 3000 毫秒
+ * @param interval 等待间隔（毫秒），默认 300 毫秒
+ * @param action 每次等待循环中执行的操作（可选）
+ * @returns - true  在超时前条件已满足
+ *          - false 在超时后条件仍未满足
+ */
+export const waitUntil = async (condition, timeout, interval, action) => {
+    const context = {};
+    const deadline = Date.now() + (timeout ?? 3 * 1000);
+    while (Date.now() < deadline) {
+        if (condition(context))
+            return true;
+        action?.(context);
+        await sleep(interval ?? 300);
+    }
+    return false;
+};

package/dist/game.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 打开派蒙菜单
+ */
+export declare const openPaimonMenu: () => Promise<void>;
+/**
+ * 打开游戏菜单（左侧按钮）
+ * @param name 菜单名称
+ * @param reverse 是否反向搜索（可选）
+ * @param config 搜索参数（可选）
+ */
+export declare const openMenu: (name: "\u62CD\u7167" | "\u516C\u544A" | "\u90AE\u4EF6" | "\u65F6\u95F4" | "\u8BBE\u7F6E" | (string & {}), reverse?: boolean, config?: {
+    x?: number;
+    step?: number;
+    timeout?: number;
+}) => Promise<void>;
+/**
+ * 打开游戏菜单页面（菜单按钮列表）
+ * @param name 菜单页面名称
+ * @param config 菜单页面视图参数
+ */
+export declare const openMenuPage: (name: string, config?: {
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+    lineHeight?: number;
+}) => Promise<void>;
+/**
+ * 调整游戏时间
+ * @param period 时间段
+ * @param config 时钟参数
+ */
+export declare const setTime: (period: "night" | "morning" | "noon" | "evening", config?: {
+    centerX?: number;
+    centerY?: number;
+    radius?: number;
+    offset?: number;
+}) => Promise<void>;

package/dist/game.js

@@ -0,0 +1,103 @@
+import { waitUntil } from "./flow";
+import { mouseSlide } from "./mouse";
+import { findTextInDirection, findTextWithinBounds, findTextWithinListView } from "./ocr";
+/**
+ * 打开派蒙菜单
+ */
+export const openPaimonMenu = async () => {
+    // 1.返回主界面
+    await genshin.returnMainUi();
+    // 2.打开派蒙菜单
+    const findWorldLevel = () => findTextInDirection("世界等级", false, true, "north-west");
+    const ok = await waitUntil(() => findWorldLevel() !== undefined, 5000, 1000, () => keyPress("ESCAPE"));
+    if (!ok)
+        throw new Error("打开派蒙菜单超时");
+};
+/**
+ * 打开游戏菜单（左侧按钮）
+ * @param name 菜单名称
+ * @param reverse 是否反向搜索（可选）
+ * @param config 搜索参数（可选）
+ */
+export const openMenu = async (name, reverse, config) => {
+    // 1.打开派蒙菜单
+    await openPaimonMenu();
+    // 2.搜索菜单按钮
+    const { x = 50, step = 30, timeout = 3000 } = config || {};
+    const findTooltip = () => findTextWithinBounds(name, false, true, 0, 0, x + 150, genshin.height);
+    let result = undefined;
+    const steps = Math.ceil(genshin.height / step);
+    for (let i = 0; i < steps; i++) {
+        const o = i * step;
+        const y = reverse ? genshin.height - o : o;
+        moveMouseTo(x, y);
+        await sleep(30);
+        if ((result = findTooltip()) !== undefined)
+            break;
+    }
+    // 3.点击菜单按钮
+    if (result != undefined) {
+        const ok = await waitUntil(() => findTooltip() === undefined, timeout, 1000, () => {
+            click(x, result.y);
+        });
+        if (!ok)
+            throw new Error(`打开菜单 ${name} 超时`);
+    }
+    else {
+        throw new Error(`打开菜单 ${name} 失败`);
+    }
+};
+/**
+ * 打开游戏菜单页面（菜单按钮列表）
+ * @param name 菜单页面名称
+ * @param config 菜单页面视图参数
+ */
+export const openMenuPage = async (name, config) => {
+    // 1.打开派蒙菜单
+    await openPaimonMenu();
+    // 2.搜索菜单页面
+    const { x = 100, y = 330, w = 670, h = 730, lineHeight = 142 } = config || {};
+    const pageButton = await findTextWithinListView(name, false, true, {
+        x,
+        y,
+        w,
+        h,
+        maxListItems: 5,
+        lineHeight
+    });
+    if (!pageButton)
+        throw new Error(`搜索菜单页面 ${name} 失败`);
+    // 3.点击菜单页面
+    pageButton.click();
+};
+/**
+ * 调整游戏时间
+ * @param period 时间段
+ * @param config 时钟参数
+ */
+export const setTime = async (period, config) => {
+    // 1.打开时间页面
+    await openMenu("时间", true);
+    // 2.拨动指针
+    const { centerX = 1440, centerY = 502, radius = 400, offset = 5 } = config || {};
+    const index = ["night", "morning", "noon", "evening"].indexOf(period);
+    const periodsDirections = [
+        () => mouseSlide(centerX, centerY, centerX - offset, centerY + radius),
+        () => mouseSlide(centerX, centerY, centerX - radius, centerY - offset),
+        () => mouseSlide(centerX, centerY, centerX + offset, centerY - radius),
+        () => mouseSlide(centerX, centerY, centerX + radius, centerY + offset)
+    ];
+    const jobs = Array.from({ length: 4 }, (_, i) => periodsDirections[(index + i + 1) % periodsDirections.length]);
+    for (const job of jobs)
+        await job();
+    // 3.点击确认按钮，等待调整结束
+    const findTooShort = () => findTextInDirection("时间少于", true, true, "south-east");
+    const findConfirmButton = () => findTextInDirection("确认", false, true, "south-east");
+    const ok = await waitUntil(() => findTooShort() !== undefined, 20 * 1000, 1000, () => {
+        findConfirmButton()?.click();
+    });
+    if (!ok)
+        throw new Error("调整时间超时");
+    // 4.返回主界面
+    await genshin.returnMainUi();
+};

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export * from "./action";
+export * from "./flow";
+export * from "./game";
 export * from "./mouse";
 export * from "./ocr";
 export * from "./store";

package/dist/index.js

@@ -1,4 +1,5 @@
-export * from "./action";
+export * from "./flow";
+export * from "./game";
 export * from "./mouse";
 export * from "./ocr";
 export * from "./store";

package/dist/mouse.d.ts

@@ -22,3 +22,25 @@ export declare const mouseScrollUpLines: (lines: number, lineHeight?: number) =>
  * @param lineHeight 行高（默认值为175像素）
  */
 export declare const mouseScrollDownLines: (lines: number, lineHeight?: number) => Promise<void>;
+/**
+ * 鼠标拖拽滑动到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ */
+export declare const mouseSlide: (x1: number, y1: number, x2: number, y2: number) => Promise<void>;
+/**
+ * 鼠标水平拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 水平拖拽滑动距离（像素） 正数向右，负数向左
+ */
+export declare const mouseSlideX: (x: number, y: number, distance: number) => Promise<void>;
+/**
+ * 鼠标垂直拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 垂直拖拽滑动距离（像素） 正数向下，负数向上
+ */
+export declare const mouseSlideY: (x: number, y: number, distance: number) => Promise<void>;

package/dist/mouse.js

@@ -41,3 +41,37 @@ export const mouseScrollUpLines = (lines, lineHeight) => {
 export const mouseScrollDownLines = (lines, lineHeight) => {
     return mouseScrollDown(lines * (lineHeight ?? 175));
 };
+/**
+ * 鼠标拖拽滑动到指定位置
+ * @param x1 起始水平方向偏移量（像素）
+ * @param y1 起始垂直方向偏移量（像素）
+ * @param x2 终止水平方向偏移量（像素）
+ * @param y2 终止垂直方向偏移量（像素）
+ */
+export const mouseSlide = async (x1, y1, x2, y2) => {
+    moveMouseTo(x1, y1);
+    await sleep(50);
+    leftButtonDown();
+    await sleep(50);
+    moveMouseTo(x2, y2);
+    await sleep(50);
+    leftButtonUp();
+};
+/**
+ * 鼠标水平拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 水平拖拽滑动距离（像素） 正数向右，负数向左
+ */
+export const mouseSlideX = (x, y, distance) => {
+    return mouseSlide(x, y, x + distance, y);
+};
+/**
+ * 鼠标垂直拖拽滑动指定距离
+ * @param x 起始水平方向偏移量（像素）
+ * @param y 起始垂直方向偏移量（像素）
+ * @param distance 垂直拖拽滑动距离（像素） 正数向下，负数向上
+ */
+export const mouseSlideY = (x, y, distance) => {
+    return mouseSlide(x, y, x, y + distance);
+};

package/dist/ocr.d.ts

@@ -53,4 +53,22 @@ export declare const findTextWithinBounds: (text: string, contains: boolean, ign
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export declare const findTextInDirection: (text: string, contains: boolean, ignoreCase: boolean, direction: Direction) => Region | undefined;
+/**
+ * 在列表视图中滚动搜索文本
+ * @param text 待搜索文本
+ * @param contains 是否包含
+ * @param ignoreCase 是否忽略大小写
+ * @param listView 列表视图参数
+ * @param timeout 搜索超时
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ */
+export declare const findTextWithinListView: (text: string, contains: boolean, ignoreCase: boolean, listView: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    maxListItems: number;
+    lineHeight: number;
+    padding?: number;
+}, timeout?: number) => Promise<Region | undefined>;
 export {};

package/dist/ocr.js

@@ -1,3 +1,5 @@
+import { waitUntil } from "./flow";
+import { mouseScrollDownLines } from "./mouse";
 const findFirst = (ir, ro, predicate) => {
     const candidates = ir.findMulti(ro);
     for (let i = 0; i < candidates.count; i++) {
@@ -108,3 +110,40 @@ export const findTextInDirection = (text, contains, ignoreCase, direction) => {
     const { x, y, w, h } = directionToBounds(direction);
     return findTextWithinBounds(text, contains, ignoreCase, x, y, w, h);
 };
+/**
+ * 在列表视图中滚动搜索文本
+ * @param text 待搜索文本
+ * @param contains 是否包含
+ * @param ignoreCase 是否忽略大小写
+ * @param listView 列表视图参数
+ * @param timeout 搜索超时
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ */
+export const findTextWithinListView = async (text, contains, ignoreCase, listView, timeout) => {
+    const { x, y, w, h, maxListItems, lineHeight, padding = 10 } = listView;
+    const find = () => {
+        return findTextWithinBounds(text, contains, ignoreCase, x, y, w, h);
+    };
+    let firstRegion;
+    const isBottomTouched = () => {
+        const ro = RecognitionObject.ocr(x, y, w, h);
+        const list = captureGameRegion().findMulti(ro);
+        if (list.count > 0) {
+            if (firstRegion?.text === list[0].text && Math.abs(list[0].y - firstRegion.y) < lineHeight) {
+                return true;
+            }
+            else {
+                firstRegion = list[0];
+                return false;
+            }
+        }
+        else {
+            return true;
+        }
+    };
+    const ok = await waitUntil(() => find() != undefined || isBottomTouched(), timeout ?? 30 * 1000, 1000, async () => {
+        moveMouseTo(x + w - padding, y + padding);
+        await mouseScrollDownLines(maxListItems, lineHeight);
+    });
+    return ok ? find() : undefined;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Utils for BetterGI JavaScript Development",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",
@@ -33,7 +33,7 @@
     "build": "tsc"
   },
   "devDependencies": {
-    "@bettergi/types": "^0.0.5",
-    "typescript": "^5.6.3"
+    "@bettergi/types": "^0.0.10",
+    "typescript": "5.6.3"
   }
 }