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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxindex 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 itsown.+## 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 lifecycleEach 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.mdxindex 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>+## 生命周期每个钩子都是可选的;只定义你需要的那些。