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.

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.mjs
index 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.ts
index 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 declared
diff --git a/desktop/tests/export-game.test.ts b/desktop/tests/export-game.test.ts
index 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.ts
index 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.hpp
index 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.cpp
index 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.cpp
index 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.md
index 7aa3a1c6e..083b0b1e4 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5152,6 +5152,7 @@ removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
+setWindowSize: ((width: number, height: number) => void) | undefined
share: ((options: PlatformShareOptions) => void) | undefined
steamAchievements: ((appId: number) => AchievementProvider | null) | undefined
steamIdentity: (() => { id: string; name: string; } | null) | undefined
@@ -6088,6 +6089,7 @@ physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
scenes: { name: string; data?: SceneData; path?: string; }[]
+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefined
source: RuntimeAssetSource
spineManager: SpineManager | null | undefined
spineModule: 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 — function
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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) => () => void
removeStorageItem: (key: string) => void
setStorageItem: (key: string, value: string) => void
+setWindowSize: ((width: number, height: number) => void) | undefined
steam: NativeSteamBridge | undefined
storageKeys: () => string[]
textEditor: NativeTextEditorBridge | undefined
@@ -4601,6 +4602,7 @@ es_readCacheFile: ((key: string) => ArrayBuffer | null) | undefined
es_readDataFile: ((key: string) => ArrayBuffer | null) | undefined
es_removeStorageItem: ((key: string) => void) | undefined
es_setStorageItem: ((key: string, value: string) => void) | undefined
+es_setWindowSize: ((width: number, height: number) => void) | undefined
es_steam_available: (() => boolean) | undefined
es_steam_getStat: ((name: string) => number) | undefined
es_steam_identity: (() => { id: string; name: string; }) | undefined
@@ -4670,6 +4672,7 @@ readFile: (path: string) => Promise<ArrayBuffer>
readTextFile: (path: string) => Promise<string>
removeStorageItem: (key: string) => void
setStorageItem: (key: string, value: string) => void
+setWindowSize: (width: number, height: number) => void
steamAchievements: (appId: number) => AchievementProvider | null
steamIdentity: () => { id: string; name: string; } | null
unbindInputEvents: () => void
@@ -5332,6 +5335,7 @@ removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
+setWindowSize: ((width: number, height: number) => void) | undefined
share: ((options: PlatformShareOptions) => void) | undefined
steamAchievements: ((appId: number) => AchievementProvider | null) | undefined
steamIdentity: (() => { id: string; name: string; } | null) | undefined
@@ -6278,6 +6282,7 @@ physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
scenes: { name: string; data?: SceneData; path?: string; }[]
+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefined
source: RuntimeAssetSource
spineManager: SpineManager | null | undefined
spineModule: 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 — function
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 672b69326..d3c53ef20 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5147,6 +5147,7 @@ removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
+setWindowSize: ((width: number, height: number) => void) | undefined
share: ((options: PlatformShareOptions) => void) | undefined
steamAchievements: ((appId: number) => AchievementProvider | null) | undefined
steamIdentity: (() => { id: string; name: string; } | null) | undefined
@@ -6083,6 +6084,7 @@ physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
scenes: { name: string; data?: SceneData; path?: string; }[]
+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefined
source: RuntimeAssetSource
spineManager: SpineManager | null | undefined
spineModule: 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 — function
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 42e25e40b..8feb348cb 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5392,6 +5392,7 @@ removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
+setWindowSize: ((width: number, height: number) => void) | undefined
share: ((options: PlatformShareOptions) => void) | undefined
steamAchievements: ((appId: number) => AchievementProvider | null) | undefined
steamIdentity: (() => { id: string; name: string; } | null) | undefined
@@ -6328,6 +6329,7 @@ physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
scenes: { name: string; data?: SceneData; path?: string; }[]
+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefined
source: RuntimeAssetSource
spineManager: SpineManager | null | undefined
spineModule: 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 — function
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index f5df7bebc..c00f4a4f3 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5154,6 +5154,7 @@ removeStorageItem: (key: string) => void
requestPayment: ((request: PlatformPaymentRequest) => Promise<void>) | undefined
setCloudKeyValues: ((entries: Readonly<Record<string, string>>) => boolean) | undefined
setStorageItem: (key: string, value: string) => void
+setWindowSize: ((width: number, height: number) => void) | undefined
share: ((options: PlatformShareOptions) => void) | undefined
steamAchievements: ((appId: number) => AchievementProvider | null) | undefined
steamIdentity: (() => { id: string; name: string; } | null) | undefined
@@ -6090,6 +6091,7 @@ physicsEnabled: boolean | undefined
physicsModule: PhysicsWasmModule | null | undefined
remoteRoot: string | undefined
scenes: { name: string; data?: SceneData; path?: string; }[]
+screenFit: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number; } | undefined
source: RuntimeAssetSource
spineManager: SpineManager | null | undefined
spineModule: 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 — function
diff --git a/sdk/src/platform/native/adapter.ts b/sdk/src/platform/native/adapter.ts
index 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.ts
index 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.ts
index 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 the
diff --git a/sdk/src/platform/types.ts b/sdk/src/platform/types.ts
index 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.ts
index 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.ts
index 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);