@bettergi/utils 0.0.1 → 0.0.3

package/README.md

@@ -1,21 +1,81 @@
-Utils for [Better Genshin Impact](https://github.com/babalae/better-genshin-impact) JavaScript development.
+本项目是一个为[Better Genshin Impact](https://github.com/babalae/better-genshin-impact) 设计的 JavaScript 开发工具函数，旨在帮助开发者简化代码。
 
-## Installation
+## 安装
 
 ```shell
 npm install @bettergi/utils
 ```
 
-## Example
+## 函数清单
+
+### 图文识别
+
+> 对 RecognitionObject 代码的封装，对于简单的 OCR 操作，无需写复杂的代码。
 
 ```ts
-import { findImage } from "@bettergi/utils";
+import {
+  findImage,
+  findImageInDirection,
+  findImageWithinBounds,
+  findText,
+  findTextInDirection,
+  findTextWithinBounds
+} from "@bettergi/utils";
+
+// 在整个画面内搜索图片，找不到返回 undefined
+const f1 = findImage("assets/关闭.png");
+
+// 在指定方向上搜索图片，找不到返回 undefined
+const f2 = findImageInDirection("assets/关闭.png", "north-east");
+
+// 在指定区域内搜索图片，找不到返回 undefined
+const f3 = findImageWithinBounds("assets/关闭.png", 960, 0, 960, 1080);
+
+// 在整个画面内搜索文本（不包含、忽略大小写），找不到返回 undefined
+const t1 = findText("购买", false, true);
+
+// 在指定方向上搜索文本（包含、忽略大小写），找不到返回 undefined
+const t2 = findTextInDirection("师傅", true, true, "east");
+
+// 在指定区域内搜索文本（不包含、忽略大小写），找不到返回 undefined
+const t3 = findTextWithinBounds("确认", false, true, 960, 540, 960, 540);
+```
+
+### 行为
 
-const mailIcon = findImage("./assets/mail.png");
+> 对脚本工作流中常见行为的抽象，例如：等待 XXX 完成/出现/消失。
+
+```ts
+import { findImageInDirection, waitUntil } from "@bettergi/utils";
 
-mailIcon?.click();
+// 等待直到找不到[关闭按钮] 或 5秒后超时，每隔1秒检查一次，期间按 Esc 键
+const done = await waitUntil(
+  () => findImageInDirection("assets/关闭.png", "north-east") !== undefined,
+  5000,
+  1000,
+  () => keyPress("ESCAPE")
+);
+if (!done) throw new Error("关闭页面");
 ```
 
-## Related Tools
+### 存储
 
-[@bettergi/create-script](https://www.npmjs.com/package/@bettergi/create-script)
+> 对象数据持久化，通过代理实现自动存储。可以无感知地读取/更新数据，而无需考虑如何持久化。
+
+```ts
+import { useStore } from "@bettergi/utils";
+
+// 创建/读取存储对象，保存到存储文件 store/state.json 中
+// 通过Proxy来实现：对存储对象的操作会同步保存到存储文件
+const state = useStore<{ lastUsedTime?: number; count: number }>("state");
+if (state?.lastUsedTime) {
+  log.info(`欢迎回来！上次使用时间：${state.lastUsedTime}，计数器已累计至：${state.count}`);
+}
+try {
+  for (let i = 0; i < Math.floor(Math.random() * 100); i++) {
+    state.count = (state.count || 0) + 1; // 同步保存到文件
+  }
+} finally {
+  state.lastUsedTime = Date.now(); // 同步保存到文件
+}
+```

package/dist/action.d.ts

@@ -4,7 +4,7 @@
  * @param timeout 超时时间（毫秒），默认 5000 毫秒
  * @param interval 等待间隔（毫秒），默认 200 毫秒
  * @param action 每次等待循环中执行的操作（可选）
- * @returns - true 在超时前条件已满足
+ * @returns - true  在超时前条件已满足
  *          - false 在超时后条件仍未满足
  */
-export declare const waitUntil: (condition: () => boolean, timeout?: number, interval?: number, action?: () => void) => Promise<boolean>;
+export declare const waitUntil: (condition: (context: Record<string, any>) => boolean, timeout?: number, interval?: number, action?: (context: Record<string, any>) => void) => Promise<boolean>;

package/dist/action.js

@@ -4,15 +4,16 @@
  * @param timeout 超时时间（毫秒），默认 5000 毫秒
  * @param interval 等待间隔（毫秒），默认 200 毫秒
  * @param action 每次等待循环中执行的操作（可选）
- * @returns - true 在超时前条件已满足
+ * @returns - true  在超时前条件已满足
  *          - false 在超时后条件仍未满足
  */
 export const waitUntil = async (condition, timeout, interval, action) => {
+    const context = {};
     const deadline = Date.now() + (timeout ?? 5 * 1000);
     while (Date.now() < deadline) {
-        if (condition())
+        if (condition(context))
             return true;
-        action?.();
+        action?.(context);
         await sleep(interval ?? 200);
     }
     return false;

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/ocr.d.ts

@@ -1,6 +1,7 @@
 import { type Region } from "@bettergi/types/csharp/BetterGenshinImpact/GameTask/Model/Area/Region";
+type Direction = "north" | "north-east" | "east" | "south-east" | "south" | "south-west" | "west" | "north-west";
 /**
- * 搜索图片
+ * 在整个画面内搜索图片
  * @param path 图片路径
  * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
@@ -8,15 +9,22 @@ export declare const findImage: (path: string) => Region | undefined;
 /**
  * 在指定区域内搜索图片
  * @param path 图片路径
- * @param x - 水平移动偏移量（像素）
- * @param y - 垂直移动偏移量（像素）
+ * @param x - 水平方向偏移量（像素）
+ * @param y - 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
  * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export declare const findImageWithinBounds: (path: string, x: number, y: number, w: number, h: number) => Region | undefined;
 /**
- * 搜索文本
+ * 在指定方向上搜索图片
+ * @param path 图片路径
+ * @param direction 搜索方向
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ */
+export declare const findImageInDirection: (path: string, direction: Direction) => Region | undefined;
+/**
+ * 在整个画面内搜索文本
  * @param text 待搜索文本
  * @param contains 是否包含
  * @param ignoreCase 是否忽略大小写
@@ -28,11 +36,21 @@ export declare const findText: (text: string, contains: boolean, ignoreCase: boo
  * @param text 待搜索文本
  * @param contains 是否包含
  * @param ignoreCase 是否忽略大小写
- * @param x 水平移动偏移量（像素）
- * @param x - 水平移动偏移量（像素）
- * @param y - 垂直移动偏移量（像素）
+ * @param x 水平方向偏移量（像素）
+ * @param x - 水平方向偏移量（像素）
+ * @param y - 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export declare const findTextWithinBounds: (text: string, contains: boolean, ignoreCase: boolean, x: number, y: number, w: number, h: number) => Region | undefined;
+/**
+ * 在指定方向上搜索文本
+ * @param text 待搜索文本
+ * @param contains 是否包含
+ * @param ignoreCase 是否忽略大小写
+ * @param direction 搜索方向
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ */
+export declare const findTextInDirection: (text: string, contains: boolean, ignoreCase: boolean, direction: Direction) => Region | undefined;
+export {};

package/dist/ocr.js

@@ -1,22 +1,28 @@
-const findFirst = (im, ro, predicate) => {
-    const candidates = im.findMulti(ro);
+const findFirst = (ir, ro, predicate) => {
+    const candidates = ir.findMulti(ro);
     for (let i = 0; i < candidates.count; i++) {
-        if (predicate(candidates[i])) {
+        if (predicate(candidates[i]))
             return candidates[i];
-        }
     }
     return undefined;
 };
+const directionToBounds = (direction) => {
+    const x = direction.includes("east") ? genshin.width / 2 : 0;
+    const y = direction.includes("south") ? genshin.height / 2 : 0;
+    const w = direction === "north" || direction === "south" ? genshin.width : genshin.width / 2;
+    const h = direction === "west" || direction === "east" ? genshin.height : genshin.height / 2;
+    return { x, y, w, h };
+};
 /**
- * 搜索图片
+ * 在整个画面内搜索图片
  * @param path 图片路径
  * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export const findImage = (path) => {
     try {
-        const im = captureGameRegion();
+        const ir = captureGameRegion();
         const ro = RecognitionObject.templateMatch(file.readImageMatSync(path));
-        return findFirst(im, ro, region => region.isExist());
+        return findFirst(ir, ro, region => region.isExist());
     }
     catch (err) {
         err?.message && log.warn(`${err.message}`);
@@ -25,24 +31,34 @@ export const findImage = (path) => {
 /**
  * 在指定区域内搜索图片
  * @param path 图片路径
- * @param x - 水平移动偏移量（像素）
- * @param y - 垂直移动偏移量（像素）
+ * @param x - 水平方向偏移量（像素）
+ * @param y - 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
  * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
 export const findImageWithinBounds = (path, x, y, w, h) => {
     try {
-        const im = captureGameRegion();
+        const ir = captureGameRegion();
         const ro = RecognitionObject.templateMatch(file.readImageMatSync(path), x, y, w, h);
-        return findFirst(im, ro, region => region.isExist());
+        return findFirst(ir, ro, region => region.isExist());
     }
     catch (err) {
         err?.message && log.warn(`${err.message}`);
     }
 };
 /**
- * 搜索文本
+ * 在指定方向上搜索图片
+ * @param path 图片路径
+ * @param direction 搜索方向
+ * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
+ */
+export const findImageInDirection = (path, direction) => {
+    const { x, y, w, h } = directionToBounds(direction);
+    return findImageWithinBounds(path, x, y, w, h);
+};
+/**
+ * 在整个画面内搜索文本
  * @param text 待搜索文本
  * @param contains 是否包含
  * @param ignoreCase 是否忽略大小写
@@ -50,9 +66,9 @@ export const findImageWithinBounds = (path, x, y, w, h) => {
  */
 export const findText = (text, contains, ignoreCase) => {
     const searchText = ignoreCase ? text.toLowerCase() : text;
-    const im = captureGameRegion();
+    const ir = captureGameRegion();
     const ro = RecognitionObject.ocrThis;
-    return findFirst(im, ro, region => {
+    return findFirst(ir, ro, region => {
         const itemText = ignoreCase ? region.text.toLowerCase() : region.text;
         const isMatch = contains ? itemText.includes(searchText) : itemText === searchText;
         return isMatch && region.isExist();
@@ -63,20 +79,32 @@ export const findText = (text, contains, ignoreCase) => {
  * @param text 待搜索文本
  * @param contains 是否包含
  * @param ignoreCase 是否忽略大小写
- * @param x 水平移动偏移量（像素）
- * @param x - 水平移动偏移量（像素）
- * @param y - 垂直移动偏移量（像素）
+ * @param x 水平方向偏移量（像素）
+ * @param x - 水平方向偏移量（像素）
+ * @param y - 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
  * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
  */
 export const findTextWithinBounds = (text, contains, ignoreCase, x, y, w, h) => {
     const searchText = ignoreCase ? text.toLowerCase() : text;
-    const im = captureGameRegion();
+    const ir = captureGameRegion();
     const ro = RecognitionObject.ocr(x, y, w, h);
-    return findFirst(im, ro, region => {
+    return findFirst(ir, ro, region => {
         const itemText = ignoreCase ? region.text.toLowerCase() : region.text;
         const isMatch = contains ? itemText.includes(searchText) : itemText === searchText;
         return isMatch && region.isExist();
     });
 };
+/**
+ * 在指定方向上搜索文本
+ * @param text 待搜索文本
+ * @param contains 是否包含
+ * @param ignoreCase 是否忽略大小写
+ * @param direction 搜索方向
+ * @returns 如果找到匹配的文本区域，则返回该区域，否则返回 undefined
+ */
+export const findTextInDirection = (text, contains, ignoreCase, direction) => {
+    const { x, y, w, h } = directionToBounds(direction);
+    return findTextWithinBounds(text, contains, ignoreCase, x, y, w, h);
+};

package/dist/store.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 创建一个持久化存储对象，用于管理应用状态数据
+ * 该函数会创建一个代理对象，对该对象的所有属性的修改都会自动同步到相应的JSON文件（脚本的 `store` 目录下）中。
+ * @param name 存储对象的名称，将作为文件名（不包扩展名）
+ */
+export declare const useStore: <T extends Record<string, any>>(name: string) => T;

package/dist/store.js

@@ -0,0 +1,20 @@
+/**
+ * 创建一个持久化存储对象，用于管理应用状态数据
+ * 该函数会创建一个代理对象，对该对象的所有属性的修改都会自动同步到相应的JSON文件（脚本的 `store` 目录下）中。
+ * @param name 存储对象的名称，将作为文件名（不包扩展名）
+ */
+export const useStore = (name) => {
+    const path = `store/${name}.json`;
+    const obj = (() => {
+        try {
+            const text = file.readTextSync(path);
+            return JSON.parse(text);
+        }
+        catch {
+            return {};
+        }
+    })();
+    return new Proxy(obj, {
+        set: (target, key, value) => Reflect.set(target, key, value) && file.writeTextSync(path, JSON.stringify(target, null, 2))
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettergi/utils",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Utils for BetterGI JavaScript Development",
   "type": "module",
   "author": "Bread Grocery<https://github.com/breadgrocery>",

package/dist/polyfill.d.ts

@@ -1 +0,0 @@
-export declare const verticalScroll: (scrollAmountInClicks: number) => void;

package/dist/polyfill.js

@@ -1,10 +0,0 @@
-import { _simulateScroll } from "./mouse";
-export const verticalScroll = (scrollAmountInClicks) => {
-    // @ts-ignore
-    if (globalThis.verticalScroll) {
-        globalThis.verticalScroll(scrollAmountInClicks);
-    }
-    else {
-        _simulateScroll(scrollAmountInClicks, 1);
-    }
-};