game-sdk-builder

v2.0.0

Published

17 days ago

Black-box React H5 and self-contained SDK build tool.

0High
0Medium
0Low

game-sdk-builder

game-sdk-builder 将 React H5 和 script 标签 SDK 的开发、类型检查、样式处理与打包过程封装为一个 npm 包。业务项目不需要安装或维护 Vite、Rollup、PostCSS、Tailwind 和 TypeScript 构建配置。

更新日志

当前版本为 2.0.0。完整版本历史请参阅 CHANGELOG.md。

安装

首版通过本地 tarball 使用：

npm install /path/to/game-sdk-builder-1.0.0.tgz

业务项目只需要直接依赖 game-sdk-builder，其余构建与运行依赖由本包安装。

初始化项目

game-sdk-builder init
game-sdk-builder init my-game

不传目录时初始化当前目录；默认从 xiao0916/template-mini-game-react 的 main 分支下载完整项目模板。
构建器会先解析远程提交 SHA，再下载该提交中的文件，避免下载期间分支更新造成项目文件不一致。
初始化只创建文件，不自动安装依赖。完成后执行 npm install 和 npm run dev。
允许目标目录存在无关文件；如任一模板路径已经存在，会列出全部冲突并且不写入任何模板文件。
模板的 package-lock.json 不会复制；生成的 package.json 会将 game-sdk-builder 依赖同步为当前构建器版本。

默认模板目录

project/
├── src/
├── resources/
├── sprite-atlas/
├── game-sdk.config.ts
└── package.json

远程模板包含 React Three Fiber、Three.js、资源图集与测试配置；首次初始化后按模板 README 执行 npm install。

命令

game-sdk-builder --help
game-sdk-builder --version
game-sdk-builder init [directory]
game-sdk-builder dev
game-sdk-builder build
game-sdk-builder build --resources
game-sdk-builder build --target sdk
game-sdk-builder preview

不传参数以及使用 -h、--help、help 时会输出完整帮助。
使用 -v、--version、version 时会输出当前安装版本。
build 生成使用相对资源链接的 dist/。
build --resources 额外复制 resources/ 到 dist/resources/。
dev、H5 build 和 SDK build 都从 game-sdk.config.ts 的 css.unit 读取 CSS 单位；默认 vw。rem SDK 生成 sdk-dist/game-sdk.rem.js。
所有构建先写 staging，成功后再替换正式目录；失败会保留上一次成功产物。
dev 和 preview 默认只监听 127.0.0.1；需要在局域网访问时显式传入 --host 0.0.0.0。

可选配置

需要修改入口、输出或设计尺寸时，在项目根目录创建 game-sdk.config.ts：

import { defineConfig } from "game-sdk-builder";

export default defineConfig({
  appEntry: "src/game/GameApp.tsx",
  styleEntry: "src/game/tailwind.css",
  resourcesDir: "resources",
  external: {
    "demo-external": {
      h5Url: "https://cdn.example.com/demo-external.esm.js",
      sdkGlobal: "DemoExternal",
    },
  },
  h5: {
    title: "My Game",
    outDir: "dist",
    htmlTemplate: "shell/index.html",
    resourceBaseUrl: "https://cdn.example.com/game-assets/",
  },
  sdk: {
    globalName: "GameSDK",
    outDir: "sdk-dist",
    fileName: "game-sdk.[unit].js",
  },
  css: {
    unit: "rem",
    designWidth: 750,
    remRootValue: 75,
  },
});

输出目录必须位于项目根目录内，不得与 src/、资源目录、入口文件或另一个输出目录重叠；SDK 文件名必须包含 [unit]。css.unit 支持 px、vw 和 rem：px 保留原始尺寸，vw 和 rem 分别执行对应转换，并生成 game-sdk.[unit].js。构建器不管理任何页面或 SDK 宿主的根字号；使用 rem 时由业务页面或宿主自行实现根字号策略。首版不支持业务方注入 Vite/Rollup/PostCSS hook，也不读取自定义 Tailwind 插件或 theme；业务样式可使用标准 Tailwind 类、任意值类和普通 CSS。

h5.resourceBaseUrl 会在 dev 和 H5 build 时原样传给 GameApp 的 options.resourceBaseUrl，默认是 ./resources/。它可指向相对路径、站内路径或 CDN；resourcesDir 仍只表示本地源目录，build --resources 仍显式控制是否复制本地资源。

外置模块

external 以裸模块名精确匹配 import，并要求每项同时提供 H5 的绝对 http(s) ESM URL 与 SDK 的全局变量名。H5 build 会把模块保留在产物外，并在 HTML 的 <head> 注入 import map；SDK build 会引用宿主全局变量，因此宿主必须先加载对应库。自定义模块的 TypeScript 类型仍由业务项目安装依赖或声明文件提供。

dev 不使用 external 的远程 URL 或 import map，继续按项目本地依赖运行，避免开发服务器与远程 ESM 的兼容问题。three 始终保持 SDK 的 window.THREE 宿主协议；只有显式配置 external.three 时 H5 才会外置 Three.js，且其 sdkGlobal 必须为 THREE。

自定义 H5 HTML 模板

h5.htmlTemplate 可指定项目根目录内任意子目录中的 index.html。模板必须且只能包含一次 ，构建器会在该位置插入 React 挂载容器和入口；其余 meta、script、title、body 内容由模板完全控制，h5.title 仅用于未配置模板时的默认页面。本地模块、样式和资源按 Vite HTML 规则处理，外部与内联 script 会保留。

dev 和 build 都会在 Vite 的 HTML 转换阶段插入挂载容器和入口，模板文件始终保持不变。模板路径必须在项目内、文件名必须为 index.html，且不能位于输出目录中。

SDK 宿主协议

SDK 将 React、ReactDOM 和 GLTFLoader 打入 bundle，Three.js 核心继续由宿主通过 window.THREE 提供。默认全局 API 为：

window.GameSDK.mount("#game", {
  resourceBaseUrl: "https://cdn.example.com/game-assets/",
  styleNonce: "optional-csp-nonce",
});

window.GameSDK.destroy();

同一时刻只允许一个活跃实例；同容器重复 mount 会先销毁旧实例，destroy 可重复调用。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

game-sdk-builder

更新日志

安装

初始化项目

默认模板目录

命令

可选配置

外置模块

自定义 H5 HTML 模板

SDK 宿主协议