@bettergi/utils 0.0.2 → 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/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,7 +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
  */
@@ -9,8 +9,8 @@ export declare const findImage: (path: string) => Region | undefined;
 /**
  * 在指定区域内搜索图片
  * @param path 图片路径
- * @param x - 水平移动偏移量（像素）
- * @param y - 垂直移动偏移量（像素）
+ * @param x - 水平方向偏移量（像素）
+ * @param y - 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
  * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
@@ -24,7 +24,7 @@ export declare const findImageWithinBounds: (path: string, x: number, y: number,
  */
 export declare const findImageInDirection: (path: string, direction: Direction) => Region | undefined;
 /**
- * 搜索文本
+ * 在整个画面内搜索文本
  * @param text 待搜索文本
  * @param contains 是否包含
  * @param ignoreCase 是否忽略大小写
@@ -36,9 +36,9 @@ 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

package/dist/ocr.js

@@ -14,7 +14,7 @@ const directionToBounds = (direction) => {
     return { x, y, w, h };
 };
 /**
- * 搜索图片
+ * 在整个画面内搜索图片
  * @param path 图片路径
  * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
  */
@@ -31,8 +31,8 @@ export const findImage = (path) => {
 /**
  * 在指定区域内搜索图片
  * @param path 图片路径
- * @param x - 水平移动偏移量（像素）
- * @param y - 垂直移动偏移量（像素）
+ * @param x - 水平方向偏移量（像素）
+ * @param y - 垂直方向偏移量（像素）
  * @param w 宽度
  * @param h 高度
  * @returns 如果找到匹配的图片区域，则返回该区域，否则返回 undefined
@@ -58,7 +58,7 @@ export const findImageInDirection = (path, direction) => {
     return findImageWithinBounds(path, x, y, w, h);
 };
 /**
- * 搜索文本
+ * 在整个画面内搜索文本
  * @param text 待搜索文本
  * @param contains 是否包含
  * @param ignoreCase 是否忽略大小写
@@ -79,9 +79,9 @@ 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

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.2",
+  "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);
-    }
-};