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: add Networking guide (createSocket / NetChannel)

yhhaecb607922c6
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 4c9379071..0fd749f0d 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -77,6 +77,7 @@ export default defineConfig({
{ label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scene' },
{ label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'guides/localization' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
+ { label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },
],
},
{
diff --git a/docs/astro/src/content/docs/guides/networking.mdx b/docs/astro/src/content/docs/guides/networking.mdx
new file mode 100644
index 000000000..ef0d0685b
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/networking.mdx
@@ -0,0 +1,47 @@
+---
+title: Networking
+description: Cross-platform WebSocket with createSocket, plus NetChannel.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Estella ships a **cross-platform WebSocket**. `createSocket` returns the right
+implementation for the platform — a browser `WebSocket` on the web, and
+`wx.connectSocket` on WeChat MiniGames — behind one API.
+
+## Connect and exchange messages
+
+```typescript
+import { createSocket } from 'esengine';
+
+const socket = createSocket({ url: 'wss://example.com/game' });
+
+socket.onOpen = () => {
+ socket.send(JSON.stringify({ type: 'join', room: 'lobby' }));
+};
+socket.onMessage = (data) => {
+ const msg = JSON.parse(data as string);
+ // handle a message from the server
+};
+socket.onClose = (code, reason) => { /* reconnect? */ };
+socket.onError = (err) => { /* … */ };
+
+socket.connect();
+```
+
+- `send(data)` takes a `string` or `ArrayBuffer`; anything sent before the socket
+ is `open` is queued and flushed on connect.
+- `readyState` is `'connecting' | 'open' | 'closing' | 'closed'`.
+- `close(code?, reason?)` disconnects.
+
+## Higher-level channels
+
+`NetChannel` wraps a transport with **typed message handlers** and
+**request/response** (`MessageHandler` / `RequestHandler`) — reach for it when you
+want routed messages and RPC-style calls instead of a raw socket.
+
+<Aside type="note">
+ Networking is plain classes, not an ECS resource — create the socket wherever
+ it fits your app, and drive gameplay from its callbacks (for example, push
+ received state into components with `Commands`).
+</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx b/docs/astro/src/content/docs/zh-cn/guides/networking.mdx
new file mode 100644
index 000000000..1022a2124
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/networking.mdx
@@ -0,0 +1,44 @@
+---
+title: 联网
+description: 用 createSocket 的跨平台 WebSocket,以及 NetChannel。
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+Estella 自带一个**跨平台 WebSocket**。`createSocket` 会为当前平台返回正确的实现——Web
+上是浏览器的 `WebSocket`,微信小游戏上是 `wx.connectSocket`——都藏在同一套 API 后面。
+
+## 连接与收发消息
+
+```typescript
+import { createSocket } from 'esengine';
+
+const socket = createSocket({ url: 'wss://example.com/game' });
+
+socket.onOpen = () => {
+ socket.send(JSON.stringify({ type: 'join', room: 'lobby' }));
+};
+socket.onMessage = (data) => {
+ const msg = JSON.parse(data as string);
+ // 处理来自服务器的消息
+};
+socket.onClose = (code, reason) => { /* 重连? */ };
+socket.onError = (err) => { /* … */ };
+
+socket.connect();
+```
+
+- `send(data)` 接受 `string` 或 `ArrayBuffer`;在套接字 `open` 之前发送的内容会被排队,
+ 连接后再一并发出。
+- `readyState` 为 `'connecting' | 'open' | 'closing' | 'closed'`。
+- `close(code?, reason?)` 断开连接。
+
+## 更高层的通道
+
+`NetChannel` 在传输之上封装了**带类型的消息处理**与**请求/响应**(`MessageHandler` /
+`RequestHandler`)——当你想要路由消息和 RPC 风格的调用、而不是裸套接字时,用它。
+
+<Aside type="note">
+ 联网是普通类,不是 ECS 资源——在适合你 App 的地方创建套接字,并从它的回调驱动游戏
+ 逻辑(例如用 `Commands` 把收到的状态写进组件)。
+</Aside>