Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: using an npm package, in both languages

yhhb53aa0c39cc2
diff --git a/docs/astro/src/content/docs/guides/scripting.mdx b/docs/astro/src/content/docs/guides/scripting.mdx
index cd560b212..2b639f14e 100644
--- a/docs/astro/src/content/docs/guides/scripting.mdx
+++ b/docs/astro/src/content/docs/guides/scripting.mdx
@@ -118,6 +118,59 @@ before the file exists. A few things worth knowing:
revealed in the Content Browser, not opened: the editor has no code editor of its
own.
+## Using an npm package
+
+Your scripts are bundled with esbuild, and it resolves dependencies out of the
+project's own `node_modules` — so a library is an ordinary install:
+
+```bash
+cd my-game
+npm install protobufjs
+```
+
+```typescript
+import { Writer, Reader } from 'protobufjs/minimal';
+
+const packet = Writer.create().uint32(42).string('hello').finish();
+```
+
+It ships with the game on **every target** — the web and desktop builds, the
+mini-game package (down-levelled to the syntax that host accepts), the native
+content payload, and the editor's own Play realm. There is no separate step and
+no per-platform configuration: what you import is what gets bundled.
+
+New projects come with a `package.json`. An older project made before that may
+not have one — `npm init -y` once, and it works the same afterwards.
+
+### What cannot come along
+
+**Anything that needs Node.** A game runs in a browser or a mini-game host,
+neither of which has `fs`, `crypto`, `path` or the rest, so a package that
+reaches for one fails the build rather than shipping broken:
+
+```
+Could not resolve "crypto" (imported by src/net/sign.ts). "crypto" is a Node
+built-in, and a game does not run in Node…
+```
+
+If the import is yours, reach for a web API (`crypto.subtle`, `fetch`,
+`localStorage`) or the engine's own equivalent — [Assets](/guides/assets/) for
+files, [Save & Load](/guides/save/) for player data, both of which work
+everywhere. If a *dependency* is the one reaching, the fix is on the package:
+many publish a browser-safe entry point — `protobufjs/minimal` above is exactly
+that — and some ship a `browser` field that esbuild picks up on its own.
+
+**And it costs package size.** A dependency is bundled whole, which matters most
+where the limit is hardest: WeChat caps a mini-game's main package at 4MB. After
+a build, the [size report](/guides/build-export/#package-size) breaks the package
+down — a library that grew shows up under **Scripts**.
+
+<Aside type="tip">
+ Prefer packages that say they work in browsers. A library written for Node will
+ either fail the build outright (which is fine — you find out immediately) or
+ pull in a polyfill big enough to be its own problem on a 4MB budget.
+</Aside>
+
## The lifecycle
Each hook is optional; define only the ones you need.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx b/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
index b2d80951f..6b9f8dc6f 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
@@ -100,6 +100,54 @@ export * from './components/health';
- **对话框一关,组件就已在 Add Component 里**——创建会立即重新提取 schema,不等文件
监视器。新文件是在内容浏览器里**定位**而非打开:本编辑器自身没有代码编辑器。
+## 使用 npm 包
+
+你的脚本由 esbuild 打包,而它会从项目自己的 `node_modules` 解析依赖——所以装一个库就是
+普通的安装:
+
+```bash
+cd my-game
+npm install protobufjs
+```
+
+```typescript
+import { Writer, Reader } from 'protobufjs/minimal';
+
+const packet = Writer.create().uint32(42).string('hello').finish();
+```
+
+它会**随游戏发到每一个目标**——网页与桌面构建、小游戏包(并降级到该宿主接受的语法)、
+原生内容负载,以及编辑器自己的 Play。没有额外步骤,也没有逐平台配置:你 import 了什么,
+打包进去的就是什么。
+
+新建的项目自带 `package.json`。此前创建的老项目可能没有——`npm init -y` 一次即可,之后
+行为完全相同。
+
+### 哪些东西带不进来
+
+**任何需要 Node 的东西。** 游戏跑在浏览器或小游戏宿主里,两者都没有 `fs`、`crypto`、
+`path` 之类,所以伸手去拿它们的包会让构建失败,而不是发出一个坏掉的包:
+
+```
+Could not resolve "crypto" (imported by src/net/sign.ts). "crypto" is a Node
+built-in, and a game does not run in Node…
+```
+
+如果这个 import 是你自己写的,改用 Web API(`crypto.subtle`、`fetch`、`localStorage`)
+或引擎自己的等价物——文件用 [资产](/zh-cn/guides/assets/)、玩家数据用
+[存档](/zh-cn/guides/save/),它们在所有平台都能用。如果伸手的是**某个依赖**,那修法在
+包那一侧:很多包都发布了浏览器安全的入口——上面的 `protobufjs/minimal` 正是——还有些带
+`browser` 字段,esbuild 会自动选用。
+
+**而且它要占包体。** 依赖是被整个打进去的,而这在上限最紧的地方最要命:微信把小游戏主包
+限制在 4MB。构建完成后,[体积报告](/zh-cn/guides/build-export/#包体体积)会把包体拆开给你
+看——涨上去的库会出现在**脚本**那一类里。
+
+<Aside type="tip">
+ 优先选明确支持浏览器的包。为 Node 写的库要么直接让构建失败(这其实是好事——你立刻就
+ 知道了),要么拖进来一堆 polyfill,在 4MB 的预算下那本身就是个问题。
+</Aside>
+
## 生命周期
每个钩子都是可选的;只定义你需要的那些。