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.

23.6 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    main_ios.mm
 * @brief   The iOS glue for the JS host: a CAMetalLayer-backed view, the app
 *          bundle's assets, Metal-backed Dawn, touch, and a CADisplayLink loop.
 * @details The Android sibling of this file is main_android.cpp; everything they
 *          share — Dawn bring-up, the es_* bindings, the SDK bundle and the frame —
 *          is in host_core.cpp. Obj-C++ so UIKit and the C++ host meet directly,
 *          with no bridging layer.
 *
 *          The app target is a thin shell: its main() calls EstellaRunApp(), and
 *          the delegate + view controller below (compiled into the static host
 *          library) own the window. Link the app with -ObjC so these classes
 *          survive dead-stripping.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @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>

#include "Host.hpp"
#include "platform/apple_common.hpp"   // Core Text + NSURLSession, shared with macOS
#include "platform/touch_stream.hpp"
#include "platform/ios_device.hpp"
#include "../../ios/App/EstellaNativeChannel.h"   // the app-facing half of the channel

using esengine::u32;
using esengine::u8;
using esengine::WebGPUDevice;

@class EstellaViewController;

/** What the platform needs of whoever owns the keyboard's responder. A role, not
 *  a class, so the C++ side names no view controller. */
@protocol EstellaTextEditorHost <NSObject>
- (void)textEditorFocus:(NSString*)value selectionStart:(NSInteger)selectionStart
           selectionEnd:(NSInteger)selectionEnd multiline:(BOOL)multiline
              maxLength:(NSInteger)maxLength password:(BOOL)password;
- (void)textEditorBlur;
- (void)textEditorWrite:(NSString*)value selectionStart:(NSInteger)selectionStart
           selectionEnd:(NSInteger)selectionEnd;
@end

/** The host's own side of the channel: what the platform asks of the registry. */
@interface EstellaNativeChannel ()
+ (BOOL)answers:(NSString*)method;
+ (BOOL)call:(int)callId method:(NSString*)method args:(NSString*)args;
@end

namespace {

struct IOSPlatform final : eshost::Platform {
    eshost::IOSDevice device;
    int deviceCapabilities() const override { return device.capabilities(); }
    bool startMotion(bool a, bool g, int interval) override { return device.start(a, g, interval); }
    void stopMotion() override { device.stop(); }
    bool pollMotion(eshost::MotionState& out) override { return device.poll(out); }
    bool vibrate(int duration, int intensity) override { return device.vibrate(duration, intensity); }
    bool keepScreenOn(bool enabled) override { return device.keepScreenOn(enabled); }
    SafeInsets contentInsets;
    SafeInsets safeAreaInsets() const override { return contentInsets; }
    CAMetalLayer* layer = nil;
    // Whoever owns the responder the keyboard talks to (the view controller); set
    // once it has loaded, which is also what makes hasTextEditor() true.
    //
    // `__unsafe_unretained` rather than `__weak`: this file compiles under manual
    // reference counting (where a zeroing weak reference does not exist), and the
    // reference must not own the controller that owns the surface. The app has one
    // root controller for the life of the process, so there is nothing for a
    // zeroing reference to zero.
    __unsafe_unretained id<EstellaTextEditorHost> editorHost = nil;

    bool hasTextEditor() const override { return editorHost != nil; }

    void textEditorFocus(const std::string& value, int selectionStart, int selectionEnd,
                         bool multiline, int maxLength, bool password) override {
        NSString* text = [NSString stringWithUTF8String:value.c_str()] ?: @"";
        [editorHost textEditorFocus:text selectionStart:selectionStart selectionEnd:selectionEnd
                          multiline:multiline maxLength:maxLength password:password];
    }

    void textEditorBlur() override { [editorHost textEditorBlur]; }

    void textEditorWrite(const std::string& value, int selectionStart, int selectionEnd) override {
        NSString* text = [NSString stringWithUTF8String:value.c_str()] ?: @"";
        [editorHost textEditorWrite:text selectionStart:selectionStart selectionEnd:selectionEnd];
    }

    // A file shipped inside the .app bundle — the packaged-asset analog of the
    // APK's assets/. Paths are project-relative ("game.config.json", "logo.png"),
    // so a game reads the same paths on both platforms. An exported project lives
    // under Content/ (a folder reference, which keeps its subdirectories); the
    // bundle root is the fallback, where the built-in demo's files sit.
    std::vector<u8> readAsset(const char* path) override {
        NSString* rel = [NSString stringWithUTF8String:path];
        NSString* root = [[NSBundle mainBundle] resourcePath];
        for (NSString* base : @[[root stringByAppendingPathComponent:@"Content"], root]) {
            NSData* data = [NSData dataWithContentsOfFile:[base stringByAppendingPathComponent:rel]];
            if (!data) continue;
            std::vector<u8> out(data.length);
            memcpy(out.data(), data.bytes, data.length);
            return out;
        }
        return {};
    }

    std::string cacheDir() override {
        NSArray* dirs = NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES);
        if (dirs.count == 0) return {};
        return std::string([dirs[0] UTF8String]);
    }

    /** Application Support, not Caches: iOS empties Caches whenever it wants the
     *  space back, which is correct for content that refetches and wrong for a
     *  save. Unlike the other two this directory does not exist until an app
     *  makes it, so create it — and only report it once it is really there,
     *  since an empty answer degrades storage to the session rather than
     *  handing out a path that every write will fail against. */
    std::string dataDir() override {
        NSArray* dirs = NSSearchPathForDirectoriesInDomains(NSApplicationSupportDirectory, NSUserDomainMask, YES);
        if (dirs.count == 0) return {};
        NSString* path = dirs[0];
        NSError* err = nil;
        if (![[NSFileManager defaultManager] createDirectoryAtPath:path
                                       withIntermediateDirectories:YES
                                                        attributes:nil
                                                             error:&err]) {
            return {};
        }
        return std::string([path UTF8String]);
    }

    /** Documents, not Caches: the record exists to be sent, and Documents is the
     *  directory the Files app shows (with UIFileSharingEnabled) and iTunes/Finder
     *  can copy off a device that has none. */
    std::string logDir() override {
        NSArray* dirs = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
        if (dirs.count == 0) return {};
        return std::string([dirs[0] UTF8String]);
    }

    std::string describe() override {
        UIDevice* d = [UIDevice currentDevice];
        return std::string([[d model] UTF8String]) + ", iOS "
             + std::string([[d systemVersion] UTF8String]) + ", arm64";
    }

    /** The first language the app can actually be shown in ('zh-Hans-CN'):
     *  preferredLanguages is the player's ordered list, per-app setting included. */
    std::string language() override {
        NSString* tag = [NSLocale preferredLanguages].firstObject;
        return tag ? std::string([tag UTF8String]) : std::string();
    }

    WGPUBackendType backend() const override { return WGPUBackendType_Metal; }

    WebGPUDevice::NativeSurface surface() override {
        return {WebGPUDevice::NativeWindowKind::MetalLayer, (__bridge void*)layer};
    }

    void surfaceSize(u32& width, u32& height) override {
        width = layer ? (u32)layer.drawableSize.width : 0;
        height = layer ? (u32)layer.drawableSize.height : 0;
    }

    void log(bool error, const char* message) override {
        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 {
        return eshost::appleMatchFont(family, codepoint, style);
    }

    // Core Text draws what stb_truetype cannot read — see Platform::drawGlyph.
    bool drawGlyph(const std::string& family, u32 codepoint, int style, esengine::f32 pixelSize,
                   int supersample, int padding, GlyphCoverage& out) override {
        return eshost::appleDrawGlyph(family, codepoint, style, pixelSize, supersample, padding, out);
    }

    // The app's own Objective-C or Swift, by name: see EstellaNativeChannel below.
    bool nativeHas(const std::string& method) override {
        return [EstellaNativeChannel answers:[NSString stringWithUTF8String:method.c_str()] ?: @""];
    }
    bool nativeCall(int id, const std::string& method, const std::string& args) override {
        return [EstellaNativeChannel call:id
                                   method:[NSString stringWithUTF8String:method.c_str()] ?: @""
                                     args:[NSString stringWithUTF8String:args.c_str()] ?: @"null"];
    }

    void startFetch(const eshost::FetchRequest& req) override {
        eshost::appleStartFetch(req);
    }
};

IOSPlatform g_platform;

}  // namespace

// -- The app's own native code, by name ----------------------------------------
//
// The registry an app's Objective-C or Swift fills (EstellaNativeChannel.h) and
// the frame loop asks. A handler runs on the main thread, where an SDK that
// presents anything has to be called, and answers from wherever that SDK calls
// back; the answer is queued and the script hears it on the next frame.

@implementation EstellaNativeChannel

/** The handlers, created on first use: an app registers from +load, which runs
 *  before anything of the host's has. Guarded by the dictionary itself. */
+ (NSMutableDictionary<NSString*, EstellaNativeHandler>*)handlers {
    static NSMutableDictionary<NSString*, EstellaNativeHandler>* handlers;
    static dispatch_once_t once;
    dispatch_once(&once, ^{
        handlers = [NSMutableDictionary dictionary];
        // What the app is, which a script cannot otherwise read: its id and version.
        handlers[@"app.info"] = [^(NSString* args, EstellaNativeReply reply) {
            NSBundle* bundle = NSBundle.mainBundle;
            NSDictionary* info = @{
                @"os": @"ios",
                @"osVersion": UIDevice.currentDevice.systemVersion ?: @"",
                @"device": UIDevice.currentDevice.model ?: @"",
                @"id": bundle.bundleIdentifier ?: @"",
                @"version": [bundle objectForInfoDictionaryKey:@"CFBundleShortVersionString"] ?: @"",
                @"build": [bundle objectForInfoDictionaryKey:@"CFBundleVersion"] ?: @"",
            };
            NSData* json = [NSJSONSerialization dataWithJSONObject:info options:0 error:nil];
            if (json) reply([[NSString alloc] initWithData:json encoding:NSUTF8StringEncoding], nil);
            else reply(nil, @"app.info could not be written as JSON");
        } copy];
    });
    return handlers;
}

+ (void)registerMethod:(NSString*)method handler:(EstellaNativeHandler)handler {
    if (!method || !handler) return;
    NSMutableDictionary* handlers = [self handlers];
    @synchronized (handlers) { handlers[method] = [handler copy]; }
}

+ (void)unregisterMethod:(NSString*)method {
    if (!method) return;
    NSMutableDictionary* handlers = [self handlers];
    @synchronized (handlers) { [handlers removeObjectForKey:method]; }
}

+ (void)emitEvent:(NSString*)event json:(NSString*)json {
    if (!event) return;
    eshost::deliverNativeEvent(event.UTF8String ?: "", json.UTF8String ?: "null");
}

+ (BOOL)answers:(NSString*)method {
    NSMutableDictionary* handlers = [self handlers];
    @synchronized (handlers) { return handlers[method] != nil; }
}

+ (BOOL)call:(int)callId method:(NSString*)method args:(NSString*)args {
    EstellaNativeHandler handler = nil;
    NSMutableDictionary* handlers = [self handlers];
    @synchronized (handlers) { handler = handlers[method]; }
    if (!handler) return NO;
    // One answer reaches the script, however many times the handler gives one.
    NSObject* once = [NSObject new];
    __block BOOL answered = NO;
    EstellaNativeReply reply = ^(NSString* json, NSString* error) {
        @synchronized (once) {
            if (answered) return;
            answered = YES;
        }
        if (error) eshost::deliverNativeReply(callId, false, error.UTF8String ?: "");
        else eshost::deliverNativeReply(callId, true, json.UTF8String ?: "null");
    };
    dispatch_async(dispatch_get_main_queue(), ^{
        @try {
            handler(args, reply);
        } @catch (NSException* exception) {
            reply(nil, exception.reason ?: exception.name);
        }
    });
    return YES;
}

@end

/// A view whose backing layer is the CAMetalLayer Dawn renders into.
@interface EstellaMetalView : UIView
@end

@implementation EstellaMetalView
+ (Class)layerClass { return [CAMetalLayer class]; }
@end

// The app's editing surface: a real UITextView, invisible, that the keyboard and
// its IME talk to. Core Text draws the field itself, but composition (pinyin,
// kana, prediction) is delivered only to a UIKit responder — so the responder is
// what this holds, and nothing else about the field lives here.
@interface EstellaViewController : UIViewController <UITextViewDelegate, EstellaTextEditorHost>
@end

@implementation EstellaViewController {
    CADisplayLink* _displayLink;
    eshost::input::TouchIdTable _touchIds;
    BOOL _booted;
    UITextView* _editor;
    BOOL _multiline;
    BOOL _writing;      // set while adopting a value the app decided, so it is not echoed back
}

- (void)loadView {
    self.view = [[EstellaMetalView alloc] initWithFrame:CGRectZero];
    self.view.multipleTouchEnabled = YES;  // one id per finger — see touch_stream.hpp
}

- (void)viewDidLoad {
    [super viewDidLoad];
    // Before boot: whether there is an editing surface decides whether the
    // es_textEditor_* entry points are bound at all.
    g_platform.editorHost = self;
    _displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(step:)];
    [_displayLink addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes];

    NSNotificationCenter* nc = NSNotificationCenter.defaultCenter;
    [nc addObserver:self selector:@selector(appBackgrounded)
               name:UISceneDidEnterBackgroundNotification object:nil];
    [nc addObserver:self selector:@selector(appForegrounded)
               name:UISceneWillEnterForegroundNotification object:nil];
}

// The layer's drawable size is in pixels; the engine's viewport and the touch
// coordinates it receives are in those same pixels.
- (void)viewDidLayoutSubviews {
    [super viewDidLayoutSubviews];
    CAMetalLayer* layer = (CAMetalLayer*)self.view.layer;
    UIScreen* screen = self.view.window.screen ?: UIScreen.mainScreen;
    const CGFloat scale = screen.scale;
    layer.contentsScale = scale;
    const CGSize size = CGSizeMake(self.view.bounds.size.width * scale,
                                   self.view.bounds.size.height * scale);
    if (size.width <= 0 || size.height <= 0) return;

    const BOOL resized = !CGSizeEqualToSize(layer.drawableSize, size);
    layer.drawableSize = size;
    g_platform.layer = layer;
    const UIEdgeInsets insets = self.view.safeAreaInsets;
    g_platform.contentInsets = { (float)(insets.top * scale), (float)(insets.bottom * scale),
                                (float)(insets.left * scale), (float)(insets.right * scale) };

    // Boot on the first laid-out frame: Dawn needs a layer with a real size to
    // configure a surface against. Later layouts (rotation) just rebind.
    if (!_booted) {
        _booted = eshost::boot(g_platform);
    } else if (resized) {
        eshost::bindSurface();
    }
}

// The display link is the clock here; the pacer only holds the game's cap (FramePacer.hpp), skipping the vsyncs it falls
// between, as every host does.
- (void)step:(CADisplayLink*)link {
    if (eshost::untilFrameDue(/*floor=*/false) > std::chrono::steady_clock::duration::zero()) return;
    eshost::frame();
}

- (void)viewSafeAreaInsetsDidChange {
    [super viewSafeAreaInsetsDidChange];
    const CGFloat scale = (self.view.window.screen ?: UIScreen.mainScreen).scale;
    const UIEdgeInsets insets = self.view.safeAreaInsets;
    g_platform.contentInsets = { (float)(insets.top * scale), (float)(insets.bottom * scale),
                                (float)(insets.left * scale), (float)(insets.right * scale) };
}

- (void)appBackgrounded {
    _displayLink.paused = YES;
    eshost::surfaceLost();
    eshost::setVisible(false);   // suspend audio + auto-pause the game
}

- (void)appForegrounded {
    eshost::setVisible(true);    // resume audio even if the surface rebind lags
    if (_booted && eshost::bindSurface()) _displayLink.paused = NO;
}

// UIKit touches are in points, top-left origin; the host contract is surface
// pixels with the same origin (as on the web), so scale them here. Every touch
// in the set is dispatched under its OWN id: UIKit identifies a finger by the
// UITouch object, which the table turns into the small stable id the engine
// tracks a finger by.
- (void)dispatchTouches:(NSSet<UITouch*>*)touches phase:(eshost::input::Phase)phase {
    const CGFloat scale = self.view.contentScaleFactor;
    const bool ending = phase == eshost::input::kTouchEnd || phase == eshost::input::kTouchCancel;
    for (UITouch* t in touches) {
        const void* key = (__bridge const void*)t;
        const int touchId = ending ? _touchIds.release(key) : _touchIds.acquire(key);
        if (touchId < 0) continue;   // an end for a finger we never started, or past kMaxTouches
        const CGPoint p = [t locationInView:self.view];
        eshost::touch(phase, touchId, (float)(p.x * scale), (float)(p.y * scale));
    }
}

- (void)touchesBegan:(NSSet<UITouch*>*)touches withEvent:(UIEvent*)event {
    [self dispatchTouches:touches phase:eshost::input::kTouchStart];
}
- (void)touchesMoved:(NSSet<UITouch*>*)touches withEvent:(UIEvent*)event {
    [self dispatchTouches:touches phase:eshost::input::kTouchMove];
}
- (void)touchesEnded:(NSSet<UITouch*>*)touches withEvent:(UIEvent*)event {
    [self dispatchTouches:touches phase:eshost::input::kTouchEnd];
}
- (void)touchesCancelled:(NSSet<UITouch*>*)touches withEvent:(UIEvent*)event {
    [self dispatchTouches:touches phase:eshost::input::kTouchCancel];
}

- (BOOL)prefersStatusBarHidden { return YES; }

// -- The editing surface ------------------------------------------------------

/** The responder, created on first use. Off-screen and clear: it must be a real,
 *  attached view for the keyboard to attach to, but the game draws the field. */
- (UITextView*)ensureEditor {
    if (_editor) return _editor;
    _editor = [[UITextView alloc] initWithFrame:CGRectMake(-100, -100, 1, 1)];
    _editor.delegate = self;
    _editor.backgroundColor = UIColor.clearColor;
    _editor.textColor = UIColor.clearColor;
    _editor.tintColor = UIColor.clearColor;   // no system caret; the game draws its own
    _editor.autocorrectionType = UITextAutocorrectionTypeNo;
    _editor.autocapitalizationType = UITextAutocapitalizationTypeNone;
    [self.view addSubview:_editor];
    return _editor;
}

- (void)textEditorFocus:(NSString*)value selectionStart:(NSInteger)selectionStart
           selectionEnd:(NSInteger)selectionEnd multiline:(BOOL)multiline
              maxLength:(NSInteger)maxLength password:(BOOL)password {
    UITextView* editor = [self ensureEditor];
    _multiline = multiline;
    _writing = YES;
    editor.text = value;
    editor.returnKeyType = multiline ? UIReturnKeyDefault : UIReturnKeyDone;
    // The field renders its own bullets; this is for the keyboard's benefit — no
    // suggestion strip or autocorrect over a password.
    editor.textContentType = password ? UITextContentTypePassword : nil;
    editor.secureTextEntry = password;
    [self setEditorSelectionStart:selectionStart end:selectionEnd];
    _writing = NO;
    [editor becomeFirstResponder];
}

- (void)textEditorBlur {
    [_editor resignFirstResponder];
}

- (void)textEditorWrite:(NSString*)value selectionStart:(NSInteger)selectionStart
           selectionEnd:(NSInteger)selectionEnd {
    if (!_editor) return;
    _writing = YES;
    if (![_editor.text isEqualToString:value]) _editor.text = value;
    [self setEditorSelectionStart:selectionStart end:selectionEnd];
    _writing = NO;
}

- (void)setEditorSelectionStart:(NSInteger)start end:(NSInteger)end {
    const NSInteger length = (NSInteger)_editor.text.length;
    const NSInteger lo = MAX(0, MIN(start, length));
    const NSInteger hi = MAX(lo, MIN(end, length));
    _editor.selectedRange = NSMakeRange((NSUInteger)lo, (NSUInteger)(hi - lo));
}

/** Hand the responder's whole state to the engine. A marked range IS the IME
 *  preedit, so that is what `composing` asks about. */
- (void)reportEditorState {
    if (_writing || !_editor) return;
    const NSRange selection = _editor.selectedRange;
    const BOOL composing = _editor.markedTextRange != nil;
    eshost::deliverTextEditorState(_editor.text.UTF8String ?: "",
                                   (int)selection.location,
                                   (int)(selection.location + selection.length), composing);
}

- (void)textViewDidChange:(UITextView*)textView { [self reportEditorState]; }

- (void)textViewDidChangeSelection:(UITextView*)textView { [self reportEditorState]; }

- (BOOL)textView:(UITextView*)textView shouldChangeTextInRange:(NSRange)range
                                           replacementText:(NSString*)text {
    // Return on a single-line field submits instead of inserting a newline —
    // the same rule the web's Enter follows.
    if (!_multiline && [text isEqualToString:@"\n"]) {
        eshost::deliverTextEditorSubmit();
        return NO;
    }
    return YES;
}

- (void)textViewDidEndEditing:(UITextView*)textView {
    // The keyboard went away (done, or another responder took over): for a UI
    // field that is losing focus, which is what Escape does on the web.
    eshost::deliverTextEditorCancel();
}

@end

@interface EstellaSceneDelegate : UIResponder <UIWindowSceneDelegate>
@property(nonatomic, strong) UIWindow* window;
@end

@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];
}
@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 {
    eshost::memoryWarning();   // SDK residency caches trim (the audio buffer cache)
}
@end

extern "C" int EstellaRunApp(int argc, char** argv) {
    @autoreleasepool {
        return UIApplicationMain(argc, argv, nil, NSStringFromClass([EstellaAppDelegate class]));
    }
}