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
feat(net): a protobuf message can be the wire form of a type the game already has
yhh8257f38ca87e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex fecbab43a..2ad93a420 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,7 +18,7 @@ published separately; it ships inside the editor.- **Optional tools a project switches on, fetched and checked by the engine.** A project names a tool in `project.esproject` (`tools.luban.enabled`); until it does, the engine does not look for it, mention it or download it. Luban, the industry's configuration tool, turns the Excel tables a game's designers keep into JSON and the TypeScript that reads it, with references between tables checked (a site that produces an item that does not exist fails with the table, the record and the field). It is a .NET program, so the engine also fetches the .NET runtime it runs on. When either is missing, `estella tools install luban` shows exactly what it would download (name, version, licence, size, and where from) and asks before it does; `--yes` agrees in advance for CI. Each tool is pinned in `external-tools.manifest.json` to one vendor file, and a release publishes those files, repackaged as `.zip`, beside an index naming each one's size and SHA-256 and the vendor file it was made from: the engine takes them from the release mirror first and the release itself second, refuses a file that does not match, and refuses an index built from a different vendor file than it pins, so an engine version always runs the tool versions it was built against. There is no fallback to the vendor's own site. `estella luban gen` writes the tables (only the files that changed, and it removes what a deleted table used to produce), `estella luban check` fails when they are out of date, and an export of a project that has Luban on rebuilds them first. Windows, macOS (both architectures) and Linux (both architectures).- **Protobuf as a second optional tool: .proto files become TypeScript types and a binary codec.** `tools.protobuf.enabled` in `project.esproject` (folders `proto` and `src/proto` unless the project says otherwise) makes the engine fetch the pinned `protoc` the same way it fetches Luban, asking first, and turn the project's `.proto` files into TypeScript: an interface and an `encode`/`decode` pair per message, written against one small `_runtime.ts` beside them, so the game carries no protobuf library. proto3 is supported, with scalars, enums, nested messages, `repeated`, `optional`, `oneof` and `map`; 64-bit integers are numbers and a value past 2^53 throws instead of rounding, and proto2 is refused by name. The output is checked against `protoc` itself, in both directions, byte for byte. `estella proto gen` writes only the files that changed, `estella proto check` fails when they are stale, and an export of a project with Protobuf on regenerates them first. A session can carry it (next entry).-- **A session can speak protobuf, with the JSON wire kept for debugging.** `ClientSession({ wire: 'pb' })` asks for it in the hello and `SessionHost({ wire })` decides: `'json'` (the default, nothing changes), `'pb'` (a client that asks gets binary frames, and one that asks for JSON still gets text, which is how a session is read in a debugger) or `'pb-only'` (a client that asks for JSON is turned away and JSON frames are dropped afterwards). A message from a `.proto` file is a contract type with `proto(Order)`: the generated code brings its binary codec, a checked JSON form for the debugging wire, and a `shape` that goes into the contract fingerprint, so changing the `.proto` changes it. On the binary wire every control message is one fixed envelope on binary channel 255, which is now reserved (0-254 stay the game's); the frame limit, the rate limit and retry-safe requests apply to it as before, and a retried request is answered from its stored result on either wire. Types written with `s` keep working on both wires.+- **A session can speak protobuf, with the JSON wire kept for debugging.** `ClientSession({ wire: 'pb' })` asks for it in the hello and `SessionHost({ wire })` decides: `'json'` (the default, nothing changes), `'pb'` (a client that asks gets binary frames, and one that asks for JSON still gets text, which is how a session is read in a debugger) or `'pb-only'` (a client that asks for JSON is turned away and JSON frames are dropped afterwards). A message from a `.proto` file is a contract type with `proto(Order)`, or `protoAs(Order, { to, from })` to keep the game's own types on either side of it: the generated code brings its binary codec, a checked JSON form for the debugging wire, and a `shape` that goes into the contract fingerprint, so changing the `.proto` changes it. On the binary wire every control message is one fixed envelope on binary channel 255, which is now reserved (0-254 stay the game's); the frame limit, the rate limit and retry-safe requests apply to it as before, and a retried request is answered from its stored result on either wire. Types written with `s` keep working on both wires.- **A text field can accept only digits.** `TextInput.inputFilter` (`TextInputFilter.Digits`) keeps a field to 0-9 for a count or a price: a letter typed or pasted never reaches `value`, and the caret stays where the kept characters put it. A script that cleaned the value itself each frame lost to the field: while a field is being edited its own editor is the source of `value`, so the cleaned value was overwritten with what was typed and the screen kept showing the letters. The filter runs where the editor's text is read in, beside `maxLength`, so what is on screen and what a script reads are the same. Off by default; a `maxLength` still applies after it.- **A web build can say which servers its game connects to.** The exported page's Content-Security-Policy let a game talk only to the page it came from, so a game with a server of its own could not reach it: the browser refused the connection and said nothing the game could see. A project now lists the origins in `packaging.platforms.web.connect` (`wss://play.example.com`, `ws://127.0.0.1:*` for any port on a host, or a bare `wss:` for any secure WebSocket) and each becomes a `connect-src` source. An entry is checked rather than pasted in: a path, a wildcard host, a space, a semicolon or a quote fails the export and names the entry, so no entry can end the directive and start another. Web only; a mini-game's server addresses are the platform's own list.- **A session can be told to redial now, and says why its link ended.** `ClientSession.retryNow()` dials at once instead of waiting out the backoff, for a player who pressed "try again"; it does nothing when the session is ready, already dialling, or closed. `lastClose` is the WebSocket close code of the last link that ended (4003, `SessionCloseCode.unavailable`, is the server saying it is full or going away) until the next one is ready, and `attempts` counts dials since the session was last ready, so a screen can tell "reconnecting" from "the server is full" and say which attempt this is.diff --git a/sdk/etc/session.api.md b/sdk/etc/session.api.mdindex 68422eebd..b3b5cf731 100644--- a/sdk/etc/session.api.md+++ b/sdk/etc/session.api.md@@ -1,7 +1,7 @@# API surface — esengine/session<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 0 public · 0 beta · 56 experimental · 0 deprecated+Symbols: 0 public · 0 beta · 57 experimental · 0 deprecated## AcceptWebSocketOptions — interface @experimental```@@ -410,6 +410,11 @@ PayloadCodec<unknown><T>(message: ProtoMessage<T>, check?: (value: T) => void): ProtoSchema<T>```+## protoAs — function @experimental+```+<T, W>(message: ProtoMessage<W>, view: { to(value: T): W; from(wire: W): T; }, check?: (value: T) => void): ProtoSchema<T>+```+## s — const @experimental```{ string(opts?: { min?: number; max?: number; pattern?: RegExp; }): Schema<string>; int(opts?: { min?: number; max?: number; }): Schema<number>; number(opts?: { min?: number; max?: number; }): Schema<number>; boolean(): Schema<boolean>; literal<const T extends string | number | boolean | null>(value: T): Schema<T>; enum<const T extends readonly [string, ...string[]]>(values: T): Schema<T[number]>; array<T>(item: Schema<T>, opts?: { max?: number; }): Schema<T[]>; object<S extends Shape>(shape: S): Schema<ObjectOf<S>>; record<T>(value: Schema<T>, opts?: { maxKeys?: number; }): Schema<Record<string, T>>; optional<T>(inner: Schema<T>): Schema<T | undefined>; nullable<T>(inner: Schema<T>): Schema<T | null>; unknown(): Schema<unknown>; }diff --git a/sdk/src/net/session/index.ts b/sdk/src/net/session/index.tsindex 235b83e35..6a9c58abc 100644--- a/sdk/src/net/session/index.ts+++ b/sdk/src/net/session/index.ts@@ -60,7 +60,7 @@ export {} from './ClientSession';export { acceptWebSocket, type WebSocketLike, type AcceptWebSocketOptions } from './acceptWebSocket';export { s, SchemaError, type Schema, type Infer } from './schema';-export { proto, jsonCodec, type ProtoMessage, type ProtoSchema } from './proto';+export { proto, protoAs, jsonCodec, type ProtoMessage, type ProtoSchema } from './proto';export {defineContract,type Contract,diff --git a/sdk/src/net/session/proto.ts b/sdk/src/net/session/proto.tsindex f3ed24914..871750044 100644--- a/sdk/src/net/session/proto.ts+++ b/sdk/src/net/session/proto.ts@@ -35,6 +35,27 @@ export function proto<T>(message: ProtoMessage<T>, check?: (value: T) => void):};}+/**+ * Use a generated message as the wire form of a type the game already has. `view.to` turns the game's value into+ * the message to send, `view.from` the message that arrived into the game's value, so game code keeps its own types+ * (string unions, records) and only the contract knows the message. `check` runs on the game's value.+ */+export function protoAs<T, W>(message: ProtoMessage<W>, view: { to(value: T): W; from(wire: W): T }, check?: (value: T) => void): ProtoSchema<T> {+ return {+ codec: {+ encode: (value) => message.encode(view.to(value)),+ decode: (bytes) => view.from(message.decode(bytes)),+ toJSON: (value) => message.toJSON(view.to(value)),+ fromJSON: (json) => view.from(message.fromJSON(json)),+ },+ parse(value) {+ check?.(value as T);+ return value as T;+ },+ describe: () => `proto(${message.shape})`,+ };+}+const utf8 = new TextEncoder();const utf8Back = new TextDecoder();diff --git a/sdk/tests/net-wire-pb.test.ts b/sdk/tests/net-wire-pb.test.tsindex 6599a80c5..d7ea59138 100644--- a/sdk/tests/net-wire-pb.test.ts+++ b/sdk/tests/net-wire-pb.test.ts@@ -8,7 +8,7 @@ import { CONTROL_CHANNEL, decodeEnvelope, encodeEnvelope } from '../src/net/wireimport { ClientSession } from '../src/net/session/ClientSession';import { SessionHost, type AcceptedConnection, type SessionContext } from '../src/net/session/SessionHost';import { defineContract } from '../src/net/session/contract';-import { proto, type ProtoMessage } from '../src/net/session/proto';+import { proto, protoAs, type ProtoMessage } from '../src/net/session/proto';import { s } from '../src/net/session/schema';import type { PlatformSocket, PlatformSocketEvents } from '../src/platform/types';@@ -318,3 +318,50 @@ describe('a session choosing its wire', () => {expect(other.fingerprint).not.toBe(base.fingerprint);});});++describe('a message as the wire form of a type the game already has', () => {+ type Kind = 'safe' | 'bold';+ interface Pick { kind: Kind }+ const KINDS: Kind[] = ['safe', 'bold'];+ // a message whose only byte is the kind's index+ const pickMsg: ProtoMessage<{ kind: number }> = {+ shape: 'Pick{1:Kind kind}',+ encode: (v) => Uint8Array.from([v.kind]),+ decode: (b) => ({ kind: b[0]! }),+ toJSON: (v) => ({ kind: v.kind }),+ fromJSON: (j) => ({ kind: (j as { kind: number }).kind }),+ };+ const pick = protoAs<Pick, { kind: number }>(pickMsg, {+ to: (v) => ({ kind: KINDS.indexOf(v.kind) }),+ from: (w) => {+ const kind = KINDS[w.kind];+ if (!kind) throw new Error('unknown kind ' + w.kind);+ return { kind };+ },+ });++ it('keeps the game type on both sides, on either wire', async () => {+ const c = defineContract({ requests: { pick: { req: pick, res: pick } } });+ for (const wire of ['json', 'pb'] as const) {+ const host = new SessionHost<Ctx>({ authenticate: (x) => ({ playerId: String(x), name: 'p' }), wire: 'pb', heartbeat: false });+ c.serve(host, { pick: (v) => ({ kind: v.kind === 'safe' ? 'bold' : 'safe' }) });+ const net = network(host);+ const client = new ClientSession({ connect: net.socket, credentials: () => 'ann', wire, heartbeat: false, retries: 0 });+ await client.start();+ expect(await c.client(client).pick({ kind: 'safe' })).toEqual({ kind: 'bold' });+ client.close();+ }+ });++ it('refuses a message the game cannot read, as an error on that request', async () => {+ const c = defineContract({ requests: { pick: { req: pick, res: pick } } });+ const host = new SessionHost<Ctx>({ authenticate: (x) => ({ playerId: String(x), name: 'p' }), wire: 'pb', heartbeat: false });+ c.serve(host, { pick: (v) => v });+ const client = new ClientSession({ connect: network(host).socket, credentials: () => 'ann', wire: 'pb', heartbeat: false, retries: 0 });+ await client.start();+ const raw = { ...pick, codec: { ...pick.codec, encode: () => Uint8Array.from([9]) } };+ const bad = defineContract({ requests: { pick: { req: raw, res: pick } } });+ await expect(bad.client(client).pick({ kind: 'safe' })).rejects.toThrow(/invalid pick request: unknown kind 9/);+ client.close();+ });+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex a47b0fc98..3262c347b 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -3028,6 +3028,8 @@ export const NOTED = {{"note":"Protobuf as a second optional tool: .proto files become TypeScript types and a binary codec."},'feat(net): a session can speak protobuf, with the JSON wire kept for debugging':{"note":"A session can speak protobuf, with the JSON wire kept for debugging."},+ 'feat(net): a protobuf message can be the wire form of a type the game already has':+ {"internal":"A follow-up inside the session protobuf feature, which has not shipped yet."},'fix(tools): a host that cannot read the engine version says so instead of asking the mirror for v0.0.0':{"internal":"A fix inside the optional tools feature, which has not shipped yet."},"perf(sdk): a blank mini-game package no longer carries terrain and water":