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.

fix(ios): the host adopts the scene lifecycle, so a game built with Xcode 27 opens on iOS 27

yhh6bfb9217e2ed
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a97a3f4c8..22bf6a309 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ published separately; it ships inside the editor.
### Fixed
+- **An iOS game opens on iOS 27.** Built with Xcode 27, every game closed 0.3 s after launch on an iOS 27 device: the host opened its window the way UIKit no longer allows, without a window scene. The host now adopts the scene lifecycle (one window scene; the game pauses and resumes with it). Its log also reaches the device console as text, where it read `<private>`. The simulator in CI runs an older iOS and could not see it; it was found on an iPhone.
- **A Spine atlas of any size loads.** The atlas text went to the Spine module through its 64 KB stack, so an atlas past about 60 KB wrote over the module's memory: a crash or a corrupted skeleton, whatever the skeleton's format. Its length was also counted in UTF-16 units rather than bytes, so an atlas with non-ASCII page or region names was cut short. The atlas now goes through the heap as UTF-8 with its byte length, as the skeleton data and DragonBones' atlas already did; a 150 KB atlas named in Chinese loads on Spine 3.8 and 4.2.
- **A material parameter named like an engine uniform is refused on every platform.** A `#pragma param u_ambient` in a `Lit` shader compiled on WebGPU and failed only on WebGL, a WeChat mini-game among them, with `redefinition of an interface block member name`. The names a parameter may not take are no longer a hand-kept list of three: they are read from what the engine actually declares for the shader's domain, so every member of the light block is refused at load, a name only the light block uses stays free in an `Unlit` shader, and the error says which block owns it.
- **World text under a perspective camera no longer eats the memory.** A `Text` left on `renderMode: Auto` in world space, seen through a perspective camera, was rasterized as if the camera were orthographic: a 32 px label asked for glyphs tens of thousands of pixels high. On a phone the native heap swung between 2.4 and 4.2 GB and the game drew about one frame in two seconds. Auto now draws world text under a perspective camera as SDF, since no single bitmap size lands 1:1 at every depth; the same eight floating labels hold the heap at about 45 MB and 60 fps. A bitmap glyph is also never rasterized larger than half an atlas page (512 px), which also covers an orthographic camera zoomed far in and a forced `Bitmap`; past that it is drawn from 512 px and the log says so once.
diff --git a/native/host/platform/ios.mm b/native/host/platform/ios.mm
index db2ddc523..ef4389d9f 100644
--- a/native/host/platform/ios.mm
+++ b/native/host/platform/ios.mm
@@ -20,6 +20,7 @@
* @copyright Copyright (c) 2026 ESEngine Team
* Licensed under the Apache License, Version 2.0.
*/
+#import <os/log.h>
#import <UIKit/UIKit.h>
#import <QuartzCore/CAMetalLayer.h>
@@ -155,7 +156,8 @@ struct IOSPlatform final : eshost::Platform {
}
void log(bool error, const char* message) override {
- NSLog(@"[Estella]%s %s", error ? " ERROR:" : "", message);
+ os_log_with_type(OS_LOG_DEFAULT, error ? OS_LOG_TYPE_ERROR : OS_LOG_TYPE_DEFAULT,
+ "[Estella]%{public}s %{public}s", error ? " ERROR:" : "", message);
}
eshost::FontMatch matchFont(const std::string& family, u32 codepoint, int style) override {
@@ -202,7 +204,7 @@ IOSPlatform g_platform;
}
- (void)loadView {
- self.view = [[EstellaMetalView alloc] initWithFrame:UIScreen.mainScreen.bounds];
+ self.view = [[EstellaMetalView alloc] initWithFrame:CGRectZero];
self.view.multipleTouchEnabled = YES; // one id per finger — see touch_stream.hpp
}
@@ -216,9 +218,9 @@ IOSPlatform g_platform;
NSNotificationCenter* nc = NSNotificationCenter.defaultCenter;
[nc addObserver:self selector:@selector(appBackgrounded)
- name:UIApplicationDidEnterBackgroundNotification object:nil];
+ name:UISceneDidEnterBackgroundNotification object:nil];
[nc addObserver:self selector:@selector(appForegrounded)
- name:UIApplicationWillEnterForegroundNotification object:nil];
+ name:UISceneWillEnterForegroundNotification object:nil];
}
// The layer's drawable size is in pixels; the engine's viewport and the touch
@@ -395,17 +397,30 @@ IOSPlatform g_platform;
@end
-@interface EstellaAppDelegate : UIResponder <UIApplicationDelegate>
+@interface EstellaSceneDelegate : UIResponder <UIWindowSceneDelegate>
@property(nonatomic, strong) UIWindow* window;
@end
-@implementation EstellaAppDelegate
-- (BOOL)application:(UIApplication*)application
- didFinishLaunchingWithOptions:(NSDictionary*)options {
- self.window = [[UIWindow alloc] initWithFrame:UIScreen.mainScreen.bounds];
+@implementation EstellaSceneDelegate
+- (void)scene:(UIScene*)scene willConnectToSession:(UISceneSession*)session
+ options:(UISceneConnectionOptions*)options {
+ if (![scene isKindOfClass:UIWindowScene.class]) return;
+ self.window = [[UIWindow alloc] initWithWindowScene:(UIWindowScene*)scene];
self.window.rootViewController = [[EstellaViewController alloc] init];
[self.window makeKeyAndVisible];
- return YES;
+}
+@end
+
+@interface EstellaAppDelegate : UIResponder <UIApplicationDelegate>
+@end
+
+@implementation EstellaAppDelegate
+- (UISceneConfiguration*)application:(UIApplication*)application
+ configurationForConnectingSceneSession:(UISceneSession*)session
+ options:(UISceneConnectionOptions*)options {
+ UISceneConfiguration* config = [[UISceneConfiguration alloc] initWithName:@"Default" sessionRole:session.role];
+ config.delegateClass = EstellaSceneDelegate.class;
+ return config;
}
- (void)applicationDidReceiveMemoryWarning:(UIApplication*)application {
diff --git a/native/ios/App/Info.plist.in b/native/ios/App/Info.plist.in
index f12055bf8..cd37680bd 100644
--- a/native/ios/App/Info.plist.in
+++ b/native/ios/App/Info.plist.in
@@ -31,6 +31,11 @@
<string>@VERSION_CODE@</string>
<key>LSRequiresIPhoneOS</key>
<true/>
+ <key>UIApplicationSceneManifest</key>
+ <dict>
+ <key>UIApplicationSupportsMultipleScenes</key>
+ <false/>
+ </dict>
<key>UILaunchScreen</key>
<dict/>
<key>UIRequiredDeviceCapabilities</key>
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 286624409..a928045bd 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -4128,4 +4128,6 @@ export const NOTED = {
{"note": "A material parameter named like an engine uniform is refused on every platform."},
"fix(spine): the atlas reaches the module through the heap as UTF-8 bytes, so an atlas past 60 KB or with non-ASCII names loads":
{"note": "A Spine atlas of any size loads."},
+ "fix(ios): the host adopts the scene lifecycle, so a game built with Xcode 27 opens on iOS 27":
+ {"note": "An iOS game opens on iOS 27."},
};