🚀 AppNative Game Engine

下一代工业级移动端 Web 混合游戏开发引擎
无需 Node.js、无需 Webpack，在 Android 手机上直接运行、转译并打包你的 TypeScript 游戏！

---

✨ 核心特性 (Features)

• ⚡ 极致的极速编译 (Rust SWC)：底层集成 Rust 编写的 SWC 引擎，支持在 Android 手机内存中对 TypeScript/TSX 进行 AST 实时降级转译。无需任何预构建步骤！
• 📦 免后缀模块解析 (ESM Resolution)：自带类 Vite 的路径推断算法，写代码就像在桌面端一样舒适：import { foo } from './utils'，引擎会自动回退寻找 .ts, .js, /index.ts。
• 🛡️ 原生系统提权 (Native Bridge)：彻底打破 Web 浏览器的沙盒限制，提供纯原生的 SQLite 数据库操作、本地文件系统读写、手柄/陀螺仪硬件感应，以及原生音频流层。
• 🔒 防破解内存级加密 (XOR Security)：内置资源混淆系统，封包时对 HTML/JS/CSS/PNG/GLB 进行高强度加密，运行时在内存中流式解密（XorInputStream），极难被提取代码。
• 📱 真机一键打包 (On-Device APK Packer)：无需电脑，在手机端即可给你的 Web 项目配置图标、启动图、版本号并直接签名生成 APK 安装包！
• 🛠️ 开发者体验拉满 (DX)：
  • Live Reload：代码变动自动局部热刷新的 WebSocket 服务。
  • Error Overlay：媲美 Vite 的“红屏报错”，精准定位 TS 错误与 WebGL 显存溢出。
  • Remote DevTools：开启局域网 TCP 9222 端口，用电脑 Chrome 直接审查手机运行中的游戏元素！

---

🎮 快速上手 (For Game Developers)

1. 准备你的游戏项目

在你的手机存储或电脑上，新建一个文件夹，包含基础的 Web 文件：

MyGame/
 ├── index.html        # 游戏入口
 ├── main.ts           # 直接写 TypeScript！引擎会处理它
 └── dev-preview.ts    # (可选) 桌面端预览垫片

2. 导入引擎与预览

1. 打开 AppNative App。
2. 点击右下角的 ➕ 导入项目，选择你刚刚创建的 MyGame 文件夹。
3. 进入控制台，点击 ▶️ 运行预览。

3. 在电脑上断点调试

运行预览后，控制台会显示一个局域网地址（如 http://192.168.1.100:9222）。 在电脑的 Chrome 浏览器中打开该地址，即可使用开发者工具（DevTools）进行断点调试、查看 Network 和控制台日志！

---

💻 核心 API 概览

为了保证极致的性能，请弃用 localStorage 或 Web Audio API，转而使用注入在全局的 window.AppNative 特权接口。引擎已为你抹平了复杂的异步与原生线程调度：

📁 高性能文件系统 (File System)

支持直接读写本地沙盒目录，完美支持二进制 Blob，规避 Base64 带来的内存抖动。

// 存档写入
AppNative.fs.saveFile("saves/slot1.json", JSON.stringify(data));

// 读取用户设备上的巨型文件夹（已彻底解决 OOM 内存溢出问题）
const { id, files } = await AppNative.fs.pickDirectory();
// 懒加载读取，避免内存爆炸
const blob = await AppNative.fs.readPickedBlob(id, files[0].path);

🗄️ 工业级 SQLite 数据库 (Database)

支持原生事务、批量执行，以及为千万级结果集设计的流式读取 (Async Generator)。

AppNative.db.transaction(() => {
    AppNative.db.execute("INSERT INTO users VALUES (?)", ["admin"]);
});

// 流式查询千万级数据，内存占用永远处于安全水位
for await (const chunk of AppNative.db.queryStream("SELECT * FROM massive_table", [], 1000)) {
    console.log("加载了一千条数据:", chunk);
}

🎵 零延迟音频引擎 (Audio)

使用 Android 底层 SoundPool 与 MediaPlayer，支持 BGM 无缝淡入淡出。

AppNative.audio.preload("atk", "assets/sounds/attack.wav");
AppNative.audio.play("atk", 1.0);

// BGM 交叉平滑过渡
AppNative.audio.crossfade("bgm_town", "bgm_boss", 1500); // 1.5秒渐变

💡 提示：想要在 VSCode 里获得完美的代码提示和桌面端独立运行能力？请查看应用内【开发指南】获取 appnative.d.ts 和 dev-preview-shim.ts 垫片！

---

🏗️ 硬核架构解析 (给 Android & 前端架构师)

本项目并不是一个简单的 "WebView 套壳"。为了让 Web 游戏达到接近原生的性能，我们对底层链路进行了深度改造：

1. 拦截链路与请求代理 (Request Interception)

传统的 Webview loadUrl("file://...") 存在严重的跨域和读取限制。 AppNative 使用了 WebViewAssetLoader.PathHandler 和 shouldInterceptRequest 劫持了所有的 https://appassets.androidplatform.net/ 请求。通过 InputStream 直接将本地或内存池中的字节流作为 WebResourceResponse 喂给 V8 引擎。

2. Rust JNI + SWC 高速转译

lib/ 目录下集成了 Rust 编写的 SWC。在 TsCompiler.kt 中，我们在专属线程池中调用 JNI 的 NativeBridge.compileTs。 利用 Android 多核 CPU 的优势，能够在数十毫秒内完成 AST 语法树分析，剥离 Type 并在内存中将 TypeScript 转换为 V8 能够立即执行的 JavaScript。转换结果带有 LRU 缓存，二次加载实现毫秒级热启动。

3. 大内存与 OOM (Out Of Memory) 攻防战

针对复杂 Web 游戏极易触发 Android 显存与堆内存溢出的问题，本项目实施了多维度的保护：

• WebView 独立沙盒：拦截了所有的恶意第三方 IFrame。
• 文件流式处理：在最新的 fs.pickDirectory() 和 db.queryStream() 设计中，废弃了“一次性载入内存转 JSON 字符串”的陈旧方案。改用 UUID 指针映射与协程（Coroutine）分块回传，把内存消耗从 O(N) 降维至 O(1)。
• 动态资源加密：打包生成的 XorInputStream 在读取字节的同时完成与 encKey 的异或解密运算，避免了产生临时解密文件的 IO 损耗。

---

🛠️ 如何编译本引擎源码

如果你想克隆本仓库并二次开发引擎本身（例如增加微信 SDK 桥接，或者增加 AdMob 广告等），请按以下步骤配置你的开发环境：

环境要求

• Android Studio Ladybug (2024.x) 或更高版本
• Java JDK 17
• Android NDK (25.0.x 或更高，用于编译 Rust C++ Bridge)
• Rust Toolchain (执行 rustup default stable 安装)

编译步骤

1. 克隆项目

   git clone https://github.com/YourName/AppNative.git
   cd AppNative

2. 初始化 Rust 模块
   若你修改了 lib/ 目录下的 Rust 代码，你需要确保系统能够将其编译为动态链接库 (.so)： (通常 Android Studio 配置好 NDK 和 CMake 路径后，Gradle 会自动处理，但你需要确保本地 cargo 命令可用)。

3. 打开 Android Studio

   • 点击 Open 并选择本项目的根目录。
   • 等待 Gradle 同步依赖 (包含 Jetpack Compose, DocumentFile, APKSigner 等)。
   • 连接你的 Android 真机或模拟器。
   • 点击绿色的 Run 按钮 🚀。

---

🛣️ Roadmap / 未来规划

• 基于协程的 SQLite 流式读取，根绝大查询 OOM。
• TS 扩展名智能推断回退。
• window.addEventListener 生命周期下发联动 (Pause/Resume/LowMemory)。
• 封装 ServiceWorker 与 Cache API，实现真·离线断网秒开。
• WebRTC/WebSocket 本地内网联机穿透模块。
• 增加 AppNative Plugin API 标准，允许开发者将第三方 AAR（如广告、支付）动态桥接给 Web。

---

🤝 参与贡献 (Contributing)

欢迎提交 Issue 和 Pull Request！无论你是想反馈一个 WebView 在特定机型上的闪退 Bug，还是想为底层提供性能优化，我们都非常欢迎。

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 发起一个 Pull Request

---

📄 开源协议 (License)

本项目基于 MIT License 开源，允许任何形式的商业与非商业应用。但请注意，若你使用本引擎打包违法、侵权游戏，后果由开发者自行承担。

---

Powered by Kotlin, Rust & ☕. Made with ❤️ for Web & Android Developers.