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(native): a desktop window opens at the project's design resolution
esengine6d0df1d2f1de
diff --git a/desktop/scripts/export-project.mjs b/desktop/scripts/export-project.mjsindex 94785aff3..62b334f08 100644--- a/desktop/scripts/export-project.mjs+++ b/desktop/scripts/export-project.mjs@@ -112,7 +112,15 @@ async function loadProjectFormat() {const dir = mkdtempSync(path.join(DESKTOP, '.format-'));const outfile = path.join(dir, 'format.mjs');await esbuild.build({- entryPoints: [path.join(DESKTOP, 'src', 'project', 'format.ts')],+ // runtimeConfig re-exports nothing of format's, so both entries are bundled+ // into one module: a headless export that derived the project's settings by+ // hand would be a second answer to what a project MEANS.+ stdin: {+ contents: "export * from './src/project/format';\nexport * from './src/project/runtimeConfig';\n",+ resolveDir: DESKTOP,+ sourcefile: 'projectFormat.ts',+ loader: 'ts',+ },outfile, bundle: true, format: 'esm', platform: 'node', target: 'node20',external: ['esbuild', 'electron', 'sharp'], logLevel: 'error',});@@ -190,7 +198,7 @@ const wasmDir = platform === 'wechat']) ?? path.join(DESKTOP, 'public', 'wasm'): path.join(DESKTOP, 'public', 'wasm');-const { resolveOrientation, parseManifest } = await loadProjectFormat();+const { resolveOrientation, parseManifest, runtimeConfigOf } = await loadProjectFormat();// PARSED, not read by hand: the parser normalizes legacy platform ids and drops// values that could not be judged against, and a budget read straight off the JSON// here would be the orientation bug again with a different field.@@ -210,6 +218,10 @@ try {platform,title: opts.title ?? project.name ?? path.basename(opts.projectDir),orientation: resolveOrientation(project),+ // The project's OWN settings, through the editor's own derivation: without+ // it a headless package ships every setting at its default while claiming+ // to be the package the dialog makes.+ runtime: runtimeConfigOf(manifest),androidTemplate: platform === 'android' ? templateDir : null,desktopTemplates,desktopChannel: opts['steam-appid'] ? 'steam' : undefined,diff --git a/desktop/src/project/runtimeConfig.ts b/desktop/src/project/runtimeConfig.tsindex 668a96c24..5d7327bc8 100644--- a/desktop/src/project/runtimeConfig.ts+++ b/desktop/src/project/runtimeConfig.ts@@ -164,7 +164,10 @@ export function packagedRuntimeFields(rc: RuntimeProjectConfig): PackagedRuntime...(rc.ySortLayers ? { ySortLayers: rc.ySortLayers } : {}),...(rc.depthLayers ? { depthLayers: rc.depthLayers } : {}),...(rc.colorSpace === 'linear' ? { colorSpace: rc.colorSpace } : {}),- ...(rc.screenFit.scaleMode >= 0 ? { screenFit: rc.screenFit } : {}),+ // ALWAYS, even with the fit off (`scaleMode < 0`): it carries the design+ // resolution, which is what a desktop window opens at. One representation, or+ // the window grows a second one that drifts.+ screenFit: rc.screenFit,...(rc.uiTheme === 'light' ? { uiTheme: rc.uiTheme } : {}),...(Object.keys(rc.uiThemeColors).length > 0 ? { uiThemeColors: rc.uiThemeColors } : {}),// Physics and the mixer ride along only when the project actually declareddiff --git a/desktop/tests/export-game.test.ts b/desktop/tests/export-game.test.tsindex 5c4de9e38..20a768958 100644--- a/desktop/tests/export-game.test.ts+++ b/desktop/tests/export-game.test.ts@@ -160,7 +160,7 @@ describe('exportGame', () => {}}, 60_000);- it('writes the project camera fit into game.config.json (only when opted in)', async () => {+ it('writes the design resolution always, and the camera fit when opted in', async () => {const fitOut = path.join(root, 'dist-game-fit');const res = await exportGame({root, entryScene: 'scenes/main.esscene', gameHostEntry: GAME_HOST, scriptsEntry: 'src/main.ts',@@ -174,14 +174,16 @@ describe('exportGame', () => {const cfg = JSON.parse(readFileSync(path.join(fitOut, 'game.config.json'), 'utf8'));expect(cfg.screenFit).toEqual({ designWidth: 1080, designHeight: 1920, scaleMode: 2, matchWidthOrHeight: 0.5 });- // Off (scaleMode -1) ⇒ no screenFit key, so an unconfigured game's config is unchanged.+ // With the fit OFF the design resolution still ships — a desktop window opens+ // at it — and `scaleMode: -1` is what tells the camera not to scale.const offOut = path.join(root, 'dist-game-fitoff');await exportGame({root, entryScene: 'scenes/main.esscene', gameHostEntry: GAME_HOST, scriptsEntry: 'src/main.ts',sdkDistDir: path.join(root, '_sdk'), wasmDir: path.join(root, '_wasm'), outDir: offOut,runtime: runtimeConfigOf({ designResolution: { width: 1920, height: 1080 } }),});- expect(JSON.parse(readFileSync(path.join(offOut, 'game.config.json'), 'utf8')).screenFit).toBeUndefined();+ expect(JSON.parse(readFileSync(path.join(offOut, 'game.config.json'), 'utf8')).screenFit)+ .toEqual({ designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5 });}, 60_000);it('content-addresses + KTX2-compresses cooked assets when opted in', async () => {diff --git a/desktop/tests/runtime-config.test.ts b/desktop/tests/runtime-config.test.tsindex d62eafea0..ed18babdf 100644--- a/desktop/tests/runtime-config.test.ts+++ b/desktop/tests/runtime-config.test.ts@@ -65,10 +65,15 @@ describe('runtimeConfigOf', () => {});describe('packagedRuntimeFields', () => {- // Absence IS the default in game.config.json, so an untouched project has to- // produce an empty object — otherwise every existing build's config changes.- it('is empty for a project that declared nothing', () => {- expect(packagedRuntimeFields(runtimeConfigOf({}))).toEqual({});+ // Absence IS the default in game.config.json, so an untouched project carries+ // nothing it did not declare.+ it('carries only the design resolution for a project that declared nothing', () => {+ // Not a setting a project opts into: every project HAS a design resolution,+ // and a desktop window opens at it. Everything else stays absent so a build+ // with default settings keeps the config it has always had.+ expect(packagedRuntimeFields(runtimeConfigOf({}))).toEqual({+ screenFit: { designWidth: 1920, designHeight: 1080, scaleMode: -1, matchWidthOrHeight: 0.5 },+ });});it('carries the 2.5D depth mask — the field that used to reach Play and no build', () => {@@ -94,6 +99,18 @@ describe('packagedRuntimeFields', () => {});});+ // The design resolution is what a desktop window opens at, and a window has a+ // size whether or not the camera scales to it — so it ships even with the fit+ // off, which is the case every project starts in.+ it('carries the design resolution even when the camera fit is off', () => {+ const fields = packagedRuntimeFields(runtimeConfigOf({+ designResolution: { width: 1080, height: 1920 },+ }));+ expect(fields.screenFit).toEqual({+ designWidth: 1080, designHeight: 1920, scaleMode: -1, matchWidthOrHeight: 0.5,+ });+ });+// Physics and the mixer used to reach Play and no shipped build at all, so a// game verified in Play could ship with different gravity and a silent mixer.it('carries physics and the mixer, which used to reach Play and no build', () => {diff --git a/native/host/Host.hpp b/native/host/Host.hppindex 87e4ca12e..55eaa8eb6 100644--- a/native/host/Host.hpp+++ b/native/host/Host.hpp@@ -150,6 +150,15 @@ struct Platform {*/virtual std::string executableDir() { return {}; }+ /**+ * Open a window this big, in design pixels.+ *+ * A window exists before any JS does and the host parses no JSON, so the+ * project's design resolution arrives from the SDK once. Ignored where the app+ * is given a screen rather than owning a window.+ */+ virtual void setWindowSize(int /*width*/, int /*height*/) {}+/*** Directories a PLAYER can browse to, best first — where a crash record is* copied so it can be sent.diff --git a/native/host/bindings/RenderBindings.cpp b/native/host/bindings/RenderBindings.cppindex d722c3031..067998359 100644--- a/native/host/bindings/RenderBindings.cpp+++ b/native/host/bindings/RenderBindings.cpp@@ -134,6 +134,18 @@ JSValue js_renderer_surfaceSize(JSContext* ctx, JSValueConst, int, JSValueConst*return o;}+// es_setWindowSize(w, h): the project's design resolution, which only the SDK can+// read (the window exists before any JS, and the host parses no JSON). A platform+// that is GIVEN its screen ignores it.+JSValue js_setWindowSize(JSContext* ctx, JSValueConst, int argc, JSValueConst* argv) {+ int32_t w = 0, h = 0;+ if (argc < 2 || JS_ToInt32(ctx, &w, argv[0]) < 0 || JS_ToInt32(ctx, &h, argv[1]) < 0) {+ return JS_UNDEFINED;+ }+ if (host().platform) host().platform->setWindowSize(w, h);+ return JS_UNDEFINED;+}+// es_registry_getCameraEntities() -> [entity]. Active cameras with a Transform,// as the web binding reports them (its sibling returns an emscripten::val array).JSValue js_registry_getCameraEntities(JSContext* ctx, JSValueConst, int, JSValueConst*) {@@ -156,6 +168,7 @@ void registerRenderBindings(HostState& h, JSValue global) {bindGlobal(h, global, "es_getTextureDimensions", js_getTextureDimensions, 1);bindGlobal(h, global, "es_rasterizeGlyph", js_rasterizeGlyph, 1);bindGlobal(h, global, "es_renderer_surfaceSize", js_renderer_surfaceSize, 0);+ bindGlobal(h, global, "es_setWindowSize", js_setWindowSize, 2);bindGlobal(h, global, "es_registry_getCameraEntities", js_registry_getCameraEntities, 0);}diff --git a/native/host/platform/desktop.cpp b/native/host/platform/desktop.cppindex c193b3960..672e524db 100644--- a/native/host/platform/desktop.cpp+++ b/native/host/platform/desktop.cpp@@ -131,6 +131,32 @@ struct DesktopPlatform final : eshost::Platform {std::string executableDir() override { return exeDir; }+ /**+ * Open at the project's design resolution, once, before anyone has seen it.+ *+ * Clamped to the display: a 2160-tall design on a 1080 laptop must not open a+ * window taller than the screen. Only the first ask counts.+ */+ void setWindowSize(int width, int height) override {+ if (!window || sized || width <= 0 || height <= 0) return;+ sized = true;+ const SDL_DisplayMode* mode = SDL_GetCurrentDisplayMode(SDL_GetDisplayForWindow(window));+ if (mode && mode->w > 0 && mode->h > 0) {+ // 90%, not 100%: a window exactly the size of the display has its title+ // bar under the menu bar and its bottom under the taskbar.+ const float fit = std::min(1.0f, std::min(mode->w * 0.9f / static_cast<float>(width),+ mode->h * 0.9f / static_cast<float>(height)));+ width = static_cast<int>(static_cast<float>(width) * fit);+ height = static_cast<int>(static_cast<float>(height) * fit);+ }+ SDL_SetWindowSize(window, width, height);+ SDL_SetWindowPosition(window, SDL_WINDOWPOS_CENTERED, SDL_WINDOWPOS_CENTERED);+ }++ /** Whether the game has been given its size; a second ask is the game's own+ * business and not a boot decision. */+ bool sized = false;+// The editing surface, which on desktop is US: a phone hands its keyboard the// value and gets edits back, and SDL supplies only committed text and an IME// preedit. The model in media/text_edit.hpp is the rest.@@ -433,7 +459,10 @@ int main(int argc, char** argv) {// SDL_WINDOW_METAL only where Metal is the backend: elsewhere it is a request// for a surface the platform does not have, and window creation fails.- SDL_WindowFlags flags = SDL_WINDOW_RESIZABLE | SDL_WINDOW_HIGH_PIXEL_DENSITY;+ // HIDDEN until the first frame is on it: the window exists before Dawn and+ // before any JS, and showing it then is half a second of an empty white rect+ // with the game's name on it.+ SDL_WindowFlags flags = SDL_WINDOW_RESIZABLE | SDL_WINDOW_HIGH_PIXEL_DENSITY | SDL_WINDOW_HIDDEN;#if defined(__APPLE__)flags |= SDL_WINDOW_METAL;#endif@@ -475,6 +504,7 @@ int main(int argc, char** argv) {}bool running = true;+ bool shown = false;// SDL reports mouse positions in window coordinates; the host contract is// surface pixels, as it is for touch.auto pixelScale = [&] { return SDL_GetWindowPixelDensity(window); };@@ -565,7 +595,16 @@ int main(int argc, char** argv) {// blocks for an event rather than spinning at the display's refresh rate.if (!eshost::surfaceBound() && SDL_WaitEvent(&e)) handleEvent(e);while (SDL_PollEvent(&e)) handleEvent(e);- if (running && eshost::surfaceBound()) eshost::frame();+ if (running && eshost::surfaceBound()) {+ eshost::frame();+ // Shown once something has been drawn on it: sizing happens during+ // boot, and a window shown before that is a default-sized empty+ // rectangle that then jumps.+ if (!shown) {+ shown = true;+ SDL_ShowWindow(window);+ }+ }if (eshost::quitRequested()) running = false;}diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 7aa3a1c6e..083b0b1e4 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -5152,6 +5152,7 @@ removeStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => void+setWindowSize: ((width: number, height: number) => void) | undefinedshare: ((options: PlatformShareOptions) => void) | undefinedsteamAchievements: ((appId: number) => AchievementProvider | null) | undefinedsteamIdentity: (() => { id: string; name: string; } | null) | undefined@@ -6088,6 +6089,7 @@ physicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefinedremoteRoot: string | undefinedscenes: { name: string; data?: SceneData; path?: string; }[]+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefinedsource: RuntimeAssetSourcespineManager: SpineManager | null | undefinedspineModule: SpineWasmModule | null | undefined@@ -10286,7 +10288,7 @@ NavPlugin## packagedRuntimeInit — function```-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; }+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }```## paramDefaultValue — functiondiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 54afc1a50..4970fbb81 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -4538,6 +4538,7 @@ readFile: (path: string) => Promise<ArrayBuffer>registerInput: (listener: NativeInputListener) => () => voidremoveStorageItem: (key: string) => voidsetStorageItem: (key: string, value: string) => void+setWindowSize: ((width: number, height: number) => void) | undefinedsteam: NativeSteamBridge | undefinedstorageKeys: () => string[]textEditor: NativeTextEditorBridge | undefined@@ -4601,6 +4602,7 @@ es_readCacheFile: ((key: string) => ArrayBuffer | null) | undefinedes_readDataFile: ((key: string) => ArrayBuffer | null) | undefinedes_removeStorageItem: ((key: string) => void) | undefinedes_setStorageItem: ((key: string, value: string) => void) | undefined+es_setWindowSize: ((width: number, height: number) => void) | undefinedes_steam_available: (() => boolean) | undefinedes_steam_getStat: ((name: string) => number) | undefinedes_steam_identity: (() => { id: string; name: string; }) | undefined@@ -4670,6 +4672,7 @@ readFile: (path: string) => Promise<ArrayBuffer>readTextFile: (path: string) => Promise<string>removeStorageItem: (key: string) => voidsetStorageItem: (key: string, value: string) => void+setWindowSize: (width: number, height: number) => voidsteamAchievements: (appId: number) => AchievementProvider | nullsteamIdentity: () => { id: string; name: string; } | nullunbindInputEvents: () => void@@ -5332,6 +5335,7 @@ removeStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => void+setWindowSize: ((width: number, height: number) => void) | undefinedshare: ((options: PlatformShareOptions) => void) | undefinedsteamAchievements: ((appId: number) => AchievementProvider | null) | undefinedsteamIdentity: (() => { id: string; name: string; } | null) | undefined@@ -6278,6 +6282,7 @@ physicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefinedremoteRoot: string | undefinedscenes: { name: string; data?: SceneData; path?: string; }[]+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefinedsource: RuntimeAssetSourcespineManager: SpineManager | null | undefinedspineModule: SpineWasmModule | null | undefined@@ -10526,7 +10531,7 @@ NavPlugin## packagedRuntimeInit — function```-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; }+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }```## paramDefaultValue — functiondiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 672b69326..d3c53ef20 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -5147,6 +5147,7 @@ removeStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => void+setWindowSize: ((width: number, height: number) => void) | undefinedshare: ((options: PlatformShareOptions) => void) | undefinedsteamAchievements: ((appId: number) => AchievementProvider | null) | undefinedsteamIdentity: (() => { id: string; name: string; } | null) | undefined@@ -6083,6 +6084,7 @@ physicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefinedremoteRoot: string | undefinedscenes: { name: string; data?: SceneData; path?: string; }[]+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefinedsource: RuntimeAssetSourcespineManager: SpineManager | null | undefinedspineModule: SpineWasmModule | null | undefined@@ -10291,7 +10293,7 @@ NodePlatformAdapter## packagedRuntimeInit — function```-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; }+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }```## paramDefaultValue — functiondiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 42e25e40b..8feb348cb 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -5392,6 +5392,7 @@ removeStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => void+setWindowSize: ((width: number, height: number) => void) | undefinedshare: ((options: PlatformShareOptions) => void) | undefinedsteamAchievements: ((appId: number) => AchievementProvider | null) | undefinedsteamIdentity: (() => { id: string; name: string; } | null) | undefined@@ -6328,6 +6329,7 @@ physicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefinedremoteRoot: string | undefinedscenes: { name: string; data?: SceneData; path?: string; }[]+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefinedsource: RuntimeAssetSourcespineManager: SpineManager | null | undefinedspineModule: SpineWasmModule | null | undefined@@ -10541,7 +10543,7 @@ NavPlugin## packagedRuntimeInit — function```-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; }+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }```## paramDefaultValue — functiondiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex f5df7bebc..c00f4a4f3 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -5154,6 +5154,7 @@ removeStorageItem: (key: string) => voidrequestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefinedsetCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefinedsetStorageItem: (key: string, value: string) => void+setWindowSize: ((width: number, height: number) => void) | undefinedshare: ((options: PlatformShareOptions) => void) | undefinedsteamAchievements: ((appId: number) => AchievementProvider | null) | undefinedsteamIdentity: (() => { id: string; name: string; } | null) | undefined@@ -6090,6 +6091,7 @@ physicsEnabled: boolean | undefinedphysicsModule: PhysicsWasmModule | null | undefinedremoteRoot: string | undefinedscenes: { name: string; data?: SceneData; path?: string; }[]+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefinedsource: RuntimeAssetSourcespineManager: SpineManager | null | undefinedspineModule: SpineWasmModule | null | undefined@@ -10313,7 +10315,7 @@ NavPlugin## packagedRuntimeInit — function```-(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; }+(config: Pick<PackagedGameConfig, "physicsEnabled" | "physicsConfig" | "audioConfig" | "uiTheme" | "uiThemeColors" | "achievements" | "steamAppId" | "screenFit">): { physicsEnabled?: boolean; physicsConfig?: PhysicsPluginConfig; audioConfig?: AudioProjectConfig; uiTheme?: "light"; uiThemeOverrides?: ThemeOverrides; achievements?: string[]; steamAppId?: number; screenFit?: PackagedGameConfig["screenFit"]; }```## paramDefaultValue — functiondiff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.tsindex 3f5230382..2b43f295f 100644--- a/sdk/src/platform/native/adapter.ts+++ b/sdk/src/platform/native/adapter.ts@@ -260,6 +260,12 @@ export class NativePlatformAdapter implements PlatformAdapter {return steam?.available() ? steam.identity() : null;}+ /** Open the window at the project's design resolution. A no-op on a host that+ * has no window of its own. */+ setWindowSize(width: number, height: number): void {+ this.bridge_.setWindowSize?.(width, height);+ }+/** The store overlay covering the game, and uncovering it. */onStoreOverlay(listener: (covered: boolean) => void): () => void {const steam = this.bridge_.steam;diff --git a/sdk/src/platform/native/bridge.ts b/sdk/src/platform/native/bridge.tsindex e491eaf91..cb6982891 100644--- a/sdk/src/platform/native/bridge.ts+++ b/sdk/src/platform/native/bridge.ts@@ -208,6 +208,10 @@ export interface NativeBridge {* a shell with no pads to report (a phone). */pollGamepads?(): GamepadSnapshot[];+ /** Size the host's own window, in design pixels. Absent where the app is given+ * a screen instead of owning a window (a phone). */+ setWindowSize?(width: number, height: number): void;+/** The Steam client, on a shell that can have one (desktop). Absent everywhere* else, and present-but-unavailable when no client is running. */steam?: NativeSteamBridge;diff --git a/sdk/src/platform/native/hostBridge.ts b/sdk/src/platform/native/hostBridge.tsindex e1b0a8c14..4314a9fc6 100644--- a/sdk/src/platform/native/hostBridge.ts+++ b/sdk/src/platform/native/hostBridge.ts@@ -78,6 +78,10 @@ export interface NativeHostBindings {es_steam_store?(): boolean;es_steam_reset?(): boolean;+ /** Ask the host's window to open at this size. Absent on a host that is given+ * its screen rather than owning a window. */+ es_setWindowSize?(width: number, height: number): void;+/** Perform an HTTP request off the main thread (native TLS stack), calling* back with the reply. Optional — a host without it stays offline (remote* asset groups and hot-update do not resolve). */@@ -230,6 +234,9 @@ export function createHostBridge(},}: {}),+ ...(bindings.es_setWindowSize+ ? { setWindowSize: (w: number, h: number) => bindings.es_setWindowSize!(w, h) }+ : {}),...(bindings.es_pollGamepads// 'standard' is asserted HERE rather than by the host: the layout is// this bridge's contract with the SDK, and a host that filled thediff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.tsindex 3d5ba97d5..39272b181 100644--- a/sdk/src/platform/types.ts+++ b/sdk/src/platform/types.ts@@ -449,6 +449,15 @@ export interface PlatformAdapter {* account id do not survive a double. */steamIdentity?(): { id: string; name: string } | null;+ /**+ * Ask for a window this big, in design pixels.+ *+ * Only a platform that OWNS a window has one to size — a phone is given a+ * screen and a browser a canvas. Best-effort: the host clamps it to the+ * display, and only the first ask counts.+ */+ setWindowSize?(width: number, height: number): void;+/*** Tell me when the store's overlay covers the game, and when it stops.*diff --git a/sdk/src/runtime/packagedRuntime.ts b/sdk/src/runtime/packagedRuntime.tsindex d68569866..f00656d0e 100644--- a/sdk/src/runtime/packagedRuntime.ts+++ b/sdk/src/runtime/packagedRuntime.ts@@ -160,7 +160,7 @@ export function packagedAppOptions(export function packagedRuntimeInit(config: Pick<PackagedGameConfig,'physicsEnabled' | 'physicsConfig' | 'audioConfig' | 'uiTheme' | 'uiThemeColors'- | 'achievements' | 'steamAppId'>,+ | 'achievements' | 'steamAppId' | 'screenFit'>,): {physicsEnabled?: boolean;physicsConfig?: PhysicsPluginConfig;@@ -169,6 +169,7 @@ export function packagedRuntimeInit(uiThemeOverrides?: ThemeOverrides;achievements?: string[];steamAppId?: number;+ screenFit?: PackagedGameConfig['screenFit'];} {return {physicsEnabled: config.physicsEnabled,@@ -178,6 +179,9 @@ export function packagedRuntimeInit(uiThemeOverrides: parseThemeOverrides(config.uiThemeColors),achievements: config.achievements,steamAppId: config.steamAppId,+ // Also here, not only in packagedAppOptions: the camera fit is baked into+ // the app's construction, but the WINDOW is sized on a live one.+ screenFit: config.screenFit,};}diff --git a/sdk/src/runtime/runtimeLoader.ts b/sdk/src/runtime/runtimeLoader.tsindex 89a360f3d..b1687ad0b 100644--- a/sdk/src/runtime/runtimeLoader.ts+++ b/sdk/src/runtime/runtimeLoader.ts@@ -515,6 +515,9 @@ export interface RuntimeInitConfig {uiTheme?: 'dark' | 'light';/** Project-declared theme token overrides; see {@link LoadRuntimeSceneOptions.uiThemeOverrides}. */uiThemeOverrides?: ThemeOverrides;+ /** The design resolution and camera fit. A desktop window opens at the design+ * size; the fit itself is applied by createWebApp/createNativeApp. */+ screenFit?: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number };/** The achievement ids the project declares — the set an unlock is checked* against, since a store would take an unknown one and do nothing. */achievements?: string[];@@ -547,6 +550,13 @@ export async function initRuntime(config: RuntimeInitConfig): Promise<void> {applyAudioProjectConfig(app.getResource(Audio), config.audioConfig);}+ // A desktop window opens at the project's design resolution. The host cannot+ // read it for itself — the window exists before any JS does, and the host has+ // no JSON parser — so this is where the two meet.+ if (config.screenFit) {+ getPlatform().setWindowSize?.(config.screenFit.designWidth, config.screenFit.designHeight);+ }+// The declared achievement ids, so an unlock outside the set is refused here// rather than accepted by a store and silently dropped.app.getResource(Achievements)?.setKnown(config.achievements ?? null);