Skip to content

Conversation

@vashworth
Copy link
Contributor

@vashworth vashworth commented Oct 3, 2025

When Multi-Scene is enabled, Flutter cannot automatically associate the engine with a scene during the scene connection phase in most cases. However, the scene:willConnectToSession:options: event is critical for some Flutter plugins that rely on scene connection options (the scene-equivalent of application launch options).

To workaround this, this PR adds two things:

  • Adds a way to manually register a FlutterEngine with a FlutterPluginSceneLifeCycleDelegate. Manually registered engines must also be manually unregistered.
    • This use case is for add to app
  • Automatically registers a FlutterEngine if the rootViewController of the scene is a FlutterViewController
    • This use case is for if a Flutter app (not add-to-app) were to enable multi-scene since the rootViewController of the storyboard is a FlutterViewController

This PR also makes a fix for when a FlutterView is removed from the scene:

  • If a FlutterView is removed from a scene, keep the FlutterEngine associated with the scene until it is assigned to a new scene

Pre-launch Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

@github-actions github-actions bot added platform-ios iOS applications specifically tool Affects the "flutter" command-line tool. See also t: labels. engine flutter/engine related. See also e: labels. team-ios Owned by iOS platform team labels Oct 3, 2025
@github-actions github-actions bot removed the tool Affects the "flutter" command-line tool. See also t: labels. label Oct 6, 2025
@vashworth vashworth changed the title Uiscene multi scene add2 app workaround Handle FlutterEngine registration when embedded in Multi-Scene apps Oct 6, 2025
@vashworth vashworth marked this pull request as ready for review October 6, 2025 14:52
@vashworth vashworth requested a review from a team as a code owner October 6, 2025 14:52
* Only manually registered engines can be unregistered. See
* `registerSceneLifeCycleWithFlutterEngine`.
*
* @param engine The `FlutterEngine` to unregister for scene life cycle events.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I'm understanding correctly, the change in willMovetoWindow: made it so that a Flutter managed engine never truly unregisters (it only moves to one scene from another). So why do we still need this method? The registerSceneLifeCycleWithFlutterEngine method seems sufficient for the moving case?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also this method will open up the possibility that flutter tries to manage an engine after the developer manually unregisters it. Do we want to enable that?

*
* Manually registered engines must also be manually deregistered if they
* switch scenes or when they are no longer needed. Use
* `unregisterSceneLifeCycleWithFlutterEngine:`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I think we should tell app developers to do this at their earliest convenience to avoid missing any lifecycle events.

// Connection options may be nil if the notification was received before the
// `scene:willConnectToSession:options:` event. In which case, we can wait for the actual event.
[self addFlutterEngine:engine];
BOOL added = [self addFlutterManagedEngine:engine];
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uber nit: could you also add a comment that says this method is only reachable in a single scene app so there is no manually managed engines (or can we make that assumption? Should we assert in the manual registration method that the app has to support multi-scene to be able to use manual registration?)

}

- (void)updateEnginesInScene:(UIScene*)scene {
- (void)updateFlutterManagedEnginesInScene:(UIScene*)scene {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder why we only have to do this for flutter managed engines? Are we expecting the developer to manually unregister before the engine is deallocated? Or the "allEngines" implementation already does the updating?

* registered with either the `FlutterSceneDelegate` or `FlutterPluginSceneLifeCycleDelegate` during
* `scene:willConnectToSession:options:`.
*
* In all other cases, or once the `FlutterViewController.view` associated with the `FlutterEngine`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: the or case seems a bit misleading as it sounded like Flutter automatically handle registration once view is added to the hierarchy even for manually managed engines?

@vashworth vashworth added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 6, 2025
@auto-submit auto-submit bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 7, 2025
@auto-submit
Copy link
Contributor

auto-submit bot commented Oct 7, 2025

autosubmit label was removed for flutter/flutter/176490, because - The status or check suite Google testing has failed. Please fix the issues identified (or deflake) before re-applying this label.

@vashworth vashworth added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 7, 2025
@auto-submit auto-submit bot added this pull request to the merge queue Oct 7, 2025
Merged via the queue into flutter:master with commit 5c66c53 Oct 7, 2025
190 checks passed
@flutter-dashboard flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 7, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 7, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 7, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 7, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 7, 2025
mboetger pushed a commit to mboetger/flutter that referenced this pull request Oct 7, 2025
…lutter#176490)

When Multi-Scene is enabled, Flutter cannot automatically associate the
engine with a scene during the scene connection phase in most cases.
However, the `scene:willConnectToSession:options:` event is critical for
some Flutter plugins that rely on scene connection options (the
scene-equivalent of application launch options).

To workaround this, this PR adds two things:
* Adds a way to manually register a `FlutterEngine` with a
`FlutterPluginSceneLifeCycleDelegate`. Manually registered engines must
also be manually unregistered.
  * This use case is for add to app
* Automatically registers a `FlutterEngine` if the `rootViewController`
of the scene is a `FlutterViewController`
* This use case is for if a Flutter app (not add-to-app) were to enable
multi-scene since the `rootViewController` of the storyboard is a
`FlutterViewController`
  
This PR also makes a fix for when a `FlutterView` is removed from the
scene:
* If a `FlutterView` is removed from a scene, keep the `FlutterEngine`
associated with the scene until it is assigned to a new scene

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
okorohelijah pushed a commit to okorohelijah/flutter that referenced this pull request Oct 7, 2025
…lutter#176490)

When Multi-Scene is enabled, Flutter cannot automatically associate the
engine with a scene during the scene connection phase in most cases.
However, the `scene:willConnectToSession:options:` event is critical for
some Flutter plugins that rely on scene connection options (the
scene-equivalent of application launch options).

To workaround this, this PR adds two things:
* Adds a way to manually register a `FlutterEngine` with a
`FlutterPluginSceneLifeCycleDelegate`. Manually registered engines must
also be manually unregistered.
  * This use case is for add to app
* Automatically registers a `FlutterEngine` if the `rootViewController`
of the scene is a `FlutterViewController`
* This use case is for if a Flutter app (not add-to-app) were to enable
multi-scene since the `rootViewController` of the storyboard is a
`FlutterViewController`
  
This PR also makes a fix for when a `FlutterView` is removed from the
scene:
* If a `FlutterView` is removed from a scene, keep the `FlutterEngine`
associated with the scene until it is assigned to a new scene

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025
auto-submit bot pushed a commit to flutter/packages that referenced this pull request Oct 8, 2025
Roll Flutter from 908012d58baa to e11e2c11288b (39 revisions)

flutter/flutter@908012d...e11e2c1

2025-10-08 [email protected] Configure FfiNative resolver on dart:io (flutter/flutter#176621)
2025-10-08 [email protected] Marks Linux_pixel_7pro service_extensions_test to be unflaky (flutter/flutter#176700)
2025-10-08 [email protected] Keyboard Animation Fix (flutter/flutter#176418)
2025-10-08 [email protected] Feat: Add carousel view builder (flutter/flutter#172837)
2025-10-08 [email protected] Roll Skia from d10a0d877ff4 to ea7cdbc6b986 (15 revisions) (flutter/flutter#176686)
2025-10-08 [email protected] Roll Fuchsia Linux SDK from jJr3my9C6TwYWPygi... to xrIAL91ngrd-wNr9S... (flutter/flutter#176682)
2025-10-08 [email protected] Fix InputDecoration helper/error padding is not compliant (flutter/flutter#176353)
2025-10-08 [email protected] Fix PopupMenu does not update when PopupMenuTheme in Theme changes. (flutter/flutter#175513)
2025-10-07 [email protected] Roll Dart SDK to 3.10.0-290.1.beta (flutter/flutter#176629)
2025-10-07 [email protected] [ Tool ] Output `app.dtd` and `app.devTools` in machine mode (flutter/flutter#176655)
2025-10-07 [email protected] Rename UIScene integration test projects and fix Xcode compatibility (flutter/flutter#176635)
2025-10-07 [email protected] Selecting an implementation widget with the on-device inspector opens the code location for the nearest project widget (flutter/flutter#176530)
2025-10-07 [email protected] Migrate to `WidgetStateInputBorder` (flutter/flutter#176386)
2025-10-07 [email protected] Make it clear that you need to install clangd in VSCode intellisense c++ config (flutter/flutter#176609)
2025-10-07 [email protected] Bump the customer tests to pick up an update to Zulip's tests. (flutter/flutter#176463)
2025-10-07 [email protected] Roll Packages from d3ef88b to 8ca6416 (2 revisions) (flutter/flutter#176633)
2025-10-07 [email protected] Add fallback for 'scene:willConnectToSession:options' (flutter/flutter#176580)
2025-10-07 [email protected] Roll Skia from d09786dfb854 to d10a0d877ff4 (11 revisions) (flutter/flutter#176616)
2025-10-07 [email protected] [ Widget Preview ] Rework UI and theming (flutter/flutter#176581)
2025-10-07 [email protected] Handle FlutterEngine registration when embedded in Multi-Scene apps (flutter/flutter#176490)
2025-10-07 [email protected] Fix code style in Linux embedder template (flutter/flutter#176256)
2025-10-07 [email protected] Add tooling to migrate to UIScene (flutter/flutter#176427)
2025-10-06 [email protected] Bump customer tests.version to 986c4326b4e4bb4e37bc963c2cc2aaa10b943859 (flutter/flutter#176594)
2025-10-06 [email protected] Fix typo in pages.dart (flutter/flutter#176438)
2025-10-06 [email protected] Fix: Update anchorRect for overlayBuilder when anchor moves (flutter/flutter#169814)
2025-10-06 [email protected] Roll Fuchsia Linux SDK from Zm6K_3gP3VCaMy9rH... to jJr3my9C6TwYWPygi... (flutter/flutter#176591)
2025-10-06 [email protected] Fix deprecated configureStatusBarForFullscreenFlutterExperience for Android 15+ (flutter/flutter#175501)
2025-10-06 [email protected] updates docs for flutter engine footprint (flutter/flutter#176217)
2025-10-06 [email protected] [ Widget Preview ] Fix `WidgetInspectorService` override (flutter/flutter#176550)
2025-10-06 [email protected] Fix NavigatorBar lacks visual feedback (flutter/flutter#175182)
2025-10-06 [email protected] Roll Packages from e401aeb to d3ef88b (4 revisions) (flutter/flutter#176582)
2025-10-06 [email protected] Roll Dart SDK from 898380a41c90 to 6b0193498f09 (2 revisions) (flutter/flutter#176576)
2025-10-06 [email protected] Roll Skia from bc7cf194f4ee to d09786dfb854 (1 revision) (flutter/flutter#176577)
2025-10-06 [email protected] Roll vulkan-deps to a9e2ca3b (flutter/flutter#176322)
2025-10-06 [email protected] Add an AppDelegate callback for implicit FlutterEngines (flutter/flutter#176240)
2025-10-06 [email protected] Roll Skia from 45191c22b15c to bc7cf194f4ee (2 revisions) (flutter/flutter#176572)
2025-10-06 [email protected] [ Widget Preview ] Fix type error when retrieving flags from persistent preferences (flutter/flutter#176546)
2025-10-06 [email protected] Roll Skia from 1fd0ca1f2120 to 45191c22b15c (3 revisions) (flutter/flutter#176556)
2025-10-05 [email protected] Roll Dart SDK from 016a8c0045fd to 898380a41c90 (1 revision) (flutter/flutter#176549)

If this roll has caused a breakage, revert this CL and stop the roller
using the controls here:
https://autoroll.skia.org/r/flutter-packages
Please CC [email protected],[email protected] on the revert to ensure that a human
is aware of the problem.

...
engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Nov 12, 2025
reidbaker pushed a commit to AbdeMohlbi/flutter that referenced this pull request Dec 10, 2025
…lutter#176490)

When Multi-Scene is enabled, Flutter cannot automatically associate the
engine with a scene during the scene connection phase in most cases.
However, the `scene:willConnectToSession:options:` event is critical for
some Flutter plugins that rely on scene connection options (the
scene-equivalent of application launch options).

To workaround this, this PR adds two things:
* Adds a way to manually register a `FlutterEngine` with a
`FlutterPluginSceneLifeCycleDelegate`. Manually registered engines must
also be manually unregistered.
  * This use case is for add to app
* Automatically registers a `FlutterEngine` if the `rootViewController`
of the scene is a `FlutterViewController`
* This use case is for if a Flutter app (not add-to-app) were to enable
multi-scene since the `rootViewController` of the storyboard is a
`FlutterViewController`
  
This PR also makes a fix for when a `FlutterView` is removed from the
scene:
* If a `FlutterView` is removed from a scene, keep the `FlutterEngine`
associated with the scene until it is assigned to a new scene

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

**Note**: The Flutter team is currently trialing the use of [Gemini Code
Assist for
GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code).
Comments from the `gemini-code-assist` bot should not be taken as
authoritative feedback from the Flutter team. If you find its comments
useful you can update your code accordingly, but if you are unsure or
disagree with the feedback, please feel free to wait for a Flutter team
member's review for guidance on which automated comments should be
addressed.

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

engine flutter/engine related. See also e: labels. platform-ios iOS applications specifically team-ios Owned by iOS platform team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants