# gdx-web **Repository Path**: lauset/gdx-web ## Basic Information - **Project Name**: gdx-web - **Description**: 为 Godot Wasm + Rust GdExt 应用提供的Web集成 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-23 - **Last Updated**: 2026-05-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Gdx Vue 对 **Godot WebAssembly + rust gdext** 应用的集成。将 Godot Web 导出的生命周期（初始化 → 预加载 → 启动 → 清理）封装为 Vue 插件，提供组合式函数和画布组件。 --- ## 有啥 - **无路径硬编码** — 所有资源路径初始化时可配置 - **`createGdx(config)`** — 插件引擎实例 - **`useGdxCanvas()`** — 组合式函数，自动处理挂载/卸载 - **``** — 开箱即用的组件，支持 loading 和 error 插槽 --- ## 安装本地打包安装 ```bash pnpm pack ``` 远程（未发布） ```bash pnpm add @lauset/gdx-vue # 或 npm install @lauset/gdx-vue ``` 依赖于 `vue ^3.3`. --- ## 快速开始 ### 1. 在 `index.html` 中引入 `gd_core.js` Godot JS（emscripten 胶水层）必须在引擎初始化**之前全局可用**。用普通的 ` ``` > **JS文件来源：** Godot 项目导出时自动生成，与导出 HTML 文件同名的 JS 文件。例如 gd_core.html 对应 gd_core.js > **为什么不能打包？** `gd_core.js` 是由 Godot 导出流程生成的文件，名称与导出的程序名称一致，其中包含依赖副作用和全局作用域的 emscripten 引导代码。它不是个 ES 模块。 --- ### 2. 在 `main.ts` 中配置插件 ```ts import { createGdx } from '@lauset/gdx-vue' import { createApp } from 'vue' import App from './App.vue' import '@lauset/gdx-vue/dist/style.css' const gdx = createGdx({ // 以项目根目录为基准，相对路径 paths: { execPath: '/static/gds/gd_core', // Godot 执行程序（无扩展名） mainPck: '/static/gds/gd_core.pck', // 主要的 PCK extraPcks: [ // 预加载 PCK '/pcks/p1.pck', '/pcks/p2.pck', ], }, // 可选： gdext 的 wasm 文件（相对 public/ 路径） gdextensionLibs: ['baas_visual.wasm'], // 可选：覆盖 Godot 引擎的构造函数参数 engineOptions: { unloadAfterInit: true, canvasResizePolicy: 0, }, // 可选：传递给 gd 场景的自定义命令行参数。默认值："--route" routeFlag: '--route', }) const app = createApp(App) app.use(gdx) // 启动时预加载所有程序包 gdx.engine.init().catch(console.error) app.mount('#app') ``` --- ### 3a. 使用 `` 组件 (简单) ```vue ``` **Props** | 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | `route` | `string` | — | 场景路由名称（作为 `--route ` 传递给 Godot） | | `width` | `number` | `1920` | 画布渲染分辨率宽 | | `height` | `number` | `1080` | 画布渲染分辨率高 | | `extraArgs` | `string[]` | `[]` | 额外传递给 Godot 的 CLI 参数 | **Slots** | 插槽 | 作用域 | 说明 | |------|--------|------| | `loading` | — | 引擎启动期间显示 | | `error` | `{ error: Error, retry: () => void }` | 启动失败时显示 | --- ### 3b. 使用 `useGdxCanvas()` （高级） ```vue ``` --- ## API 参考 ### `createGdx(config): GdxPlugin` | 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | `config.paths.execPath` | `string` | Y | Godot 执行文件路径（无扩展名） | | `config.paths.mainPck` | `string` | Y | 主 `.pck` 文件 URL | | `config.paths.extraPcks` | `string[]` | — | 额外预加载的 `.pck` URL 列表 | | `config.gdextensionLibs` | `string[]` | — | GDExtension wasm 文件路径列表 | | `config.engineOptions` | `object` | — | 传递给 `new Engine(...)` 的选项 | | `config.routeFlag` | `string` | — | 路由对应的 CLI 标志，默认 `"--route"` | ### `useGdx(): GdxEngine` 返回注入的 `GdxEngine` 对象。必须在 `app.use(gdx)` 组件内部调用。 ### `GdxEngine` | 成员 | 类型 | 说明 | |------|------|------| | `init()` | `Promise` | 初始化 + 预加载（幂等） | | `start(route, canvas?, extraArgs?)` | `Promise` | 启动一个场景 | | `cleanup()` | `Promise` | 退出并重置 | | `isReady` | `boolean` | 初始化是否完成 | | `state` | `'idle' \| 'initializing' \| 'ready' \| 'error'` | 当前引擎状态 | | `raw()` | `GodotEngineInstance` | 底层引擎句柄 | --- ## 项目结构 ``` your-web-project/ ├── public/ │ └── static/ │ └── gds/ │ ├── gd_core.pck ← paths.mainPck │ ├── gd_core.side.wasm │ ├── gd_core.wasm ← paths.execPath (no ext) │ └── ... │ └── js/ │ └── gd_core.js ← loaded via