135 lines
6.2 KiB
Markdown
135 lines
6.2 KiB
Markdown
# Connected iOS Device Access
|
|
|
|
## Summary
|
|
|
|
World Manager can browse Minecraft Bedrock content from a trusted iPhone or iPad on macOS using Apple's private `MobileDevice.framework` and the House Arrest service.
|
|
|
|
Connected-device sources are modeled as normal `MinecraftSource` values, but they are not scanned through a live filesystem mirror. The current implementation asks the device for library item summaries, metadata, icons, sizes, and directory listings through `AppleMobileDeviceSourceAccess`. Only explicit materialization operations, such as reveal/export/share, mirror an item subtree into a temporary local directory.
|
|
|
|
## Current Flow
|
|
|
|
1. `SourceLibrary` owns a `ConnectedDeviceRuntime` refresh loop when a connected-device access method is configured.
|
|
2. `AppleMobileDeviceSourceAccess.listConnectedDevices()` enumerates devices through `AppleMobileDeviceAccess.connectedDevices()`.
|
|
3. `AppleMobileDeviceSourceAccess.listAccessibleContainers(for:)` lists app containers and prioritizes `com.mojang.minecraftpe`.
|
|
4. `ConnectedDeviceSourcePickerView` lets the user add a device-backed Minecraft source.
|
|
5. `ConnectedDeviceSourceFactory` creates a stable synthetic source identifier:
|
|
|
|
```text
|
|
wmminecraft-device://<device-udid>/<bundle-id>?mode=documents
|
|
```
|
|
|
|
6. `SourceScanExecutor` scans the source through the generic `SourceAccessMethod` protocol.
|
|
7. `AppleMobileDeviceSourceAccess.discoverItems` calls `minecraftLibrarySnapshot` for item summaries and `minecraftMetadataBatch` for metadata.
|
|
8. Preview icons, size metrics, directory contents, and full item materialization are loaded lazily through the same source-access method.
|
|
|
|
This keeps UI, indexing, export, and persistence mostly source-agnostic while allowing connected devices to avoid a full upfront mirror.
|
|
|
|
## Minecraft Container
|
|
|
|
The tested Minecraft bundle identifier is:
|
|
|
|
```text
|
|
com.mojang.minecraftpe
|
|
```
|
|
|
|
Minecraft exposes a vendable Documents surface. The working Minecraft content root for House Arrest `VendDocuments` is:
|
|
|
|
```text
|
|
Documents/games/com.mojang
|
|
```
|
|
|
|
The app treats that value as a vend-relative path stored on `DeviceAppContainer.minecraftFolderRelativePath`.
|
|
|
|
Expected subfolders under that root:
|
|
|
|
- `minecraftWorlds`
|
|
- `resource_packs`
|
|
- `behavior_packs`
|
|
- `skin_packs`
|
|
- `world_templates`
|
|
|
|
## House Arrest Details
|
|
|
|
The implementation uses the explicit House Arrest flow in the Objective-C bridge:
|
|
|
|
1. Start `com.apple.mobile.house_arrest`.
|
|
2. Send `VendDocuments`.
|
|
3. Receive the vend response.
|
|
4. Use AFC against the returned service connection.
|
|
|
|
The direct `AMDeviceCreateHouseArrestService` helper returned `InstallationLookupFailed` / `e80000b7` on the tested device, so it is not the primary path.
|
|
|
|
The AFC root for this vend should not be treated as a normal `/` filesystem root. Paths are relative to the vend surface, and Minecraft content is reached through `Documents/games/com.mojang`.
|
|
|
|
## Runtime Behavior
|
|
|
|
Connected-device sources use a staged refresh strategy:
|
|
|
|
- Availability is derived from current device presence and trust state.
|
|
- Trusted devices are available.
|
|
- Locked or untrusted devices are limited.
|
|
- Missing or inaccessible devices are disconnected.
|
|
- When a source becomes available, `SourceSyncRuntime` can queue a reconcile scan instead of a full scan if cached content exists.
|
|
|
|
Scan execution uses fewer workers for connected-device sources than local folders to avoid overloading AFC/MobileDevice calls.
|
|
|
|
During scan:
|
|
|
|
- `minecraftLibrarySnapshot` returns candidate content items.
|
|
- `minecraftMetadataBatch` returns display names, UUIDs, versions, minimum engine versions, and world pack references.
|
|
- Icons are loaded with `minecraftIconBatch` or individual file reads and cached through `ImageCacheStore`.
|
|
- Size information is loaded through `pathMetricsBatch`.
|
|
- Directory previews call `listDirectory`.
|
|
|
|
During materialization:
|
|
|
|
- `materializeItem` mirrors one remote item subtree into `NSTemporaryDirectory()/WMMConnectedDeviceReveal/...`.
|
|
- `ContentPackageExporter` mirrors the selected item into archive staging when exporting connected-device content.
|
|
- Temporary materialized folders are treated as disposable.
|
|
|
|
## Persistence
|
|
|
|
Connected-device sources are persisted in the SQLite source cache with:
|
|
|
|
- source identifier
|
|
- source origin and device/container metadata
|
|
- access descriptor
|
|
- availability
|
|
- raw item cache
|
|
- source snapshot
|
|
- last scan date
|
|
|
|
On app launch, cached sources and items are restored before availability refreshes complete, so offline device-backed sources can still show cached results.
|
|
|
|
## Relevant Files
|
|
|
|
- `World Manager for Minecraft/SourceAccess/ConnectedDevice/AppleMobileDevice/AppleMobileDeviceBridge.m`
|
|
- `World Manager for Minecraft/SourceAccess/ConnectedDevice/AppleMobileDevice/AppleMobileDeviceBridge.h`
|
|
- `World Manager for Minecraft/SourceAccess/ConnectedDevice/AppleMobileDevice/AppleMobileDeviceAccess.swift`
|
|
- `World Manager for Minecraft/SourceAccess/ConnectedDevice/AppleMobileDevice/AppleMobileDeviceSourceAccess.swift`
|
|
- `World Manager for Minecraft/SourceAccess/ConnectedDevice/ConnectedDeviceSourceFactory.swift`
|
|
- `World Manager for Minecraft/SourceAccess/ConnectedDevice/ConnectedDeviceSourcePickerView.swift`
|
|
- `World Manager for Minecraft/Services/Sources/ConnectedDevice/SourceConnectedDeviceRuntime.swift`
|
|
- `World Manager for Minecraft/Services/Sources/Scanning/SourceScanExecution.swift`
|
|
|
|
## Developer Probe
|
|
|
|
The local probe harness is useful for debugging MobileDevice behavior outside the app:
|
|
|
|
```sh
|
|
Scripts/run_mobile_device_probe.sh summary
|
|
Scripts/run_mobile_device_probe.sh apps
|
|
Scripts/run_mobile_device_probe.sh details com.mojang.minecraftpe
|
|
Scripts/run_mobile_device_probe.sh probe-paths com.mojang.minecraftpe
|
|
Scripts/run_mobile_device_probe.sh mirror com.mojang.minecraftpe 'Documents/games/com.mojang' /tmp/wmm-minecraft-device-mirror
|
|
```
|
|
|
|
These commands require a trusted connected device and generally need to run outside restricted automation sandboxes.
|
|
|
|
## Caveats
|
|
|
|
- `MobileDevice.framework`, House Arrest, and AFC are private Apple interfaces.
|
|
- Behavior can change across macOS, iOS, iPadOS, and Minecraft releases.
|
|
- Device access requires trust, unlock state, and a vendable app container.
|
|
- Connected-device export/reveal operations may be slower than local folder operations because they materialize remote content on demand.
|