A cloud-synced directory for game-save data.
To get an instance of the directory,
call ``openDirectory(containerIdentifier:)``,
which returns the directory for the iCloud container associated with the specified identifier.
Calling this method starts syncing the directory in the background on the specified container.
When the game needs to access the contents of the directory,
show a UI while the directory fully syncs
using the <doc://com.apple.documentation/documentation/swiftui/view/gamesavesyncingalert(directory:finishedloading:)>
view extension if your app uses SwiftUI,
the ``finishSyncing(statusDisplay:)-(UIWindow)`` method if your app uses UIKit,
or the ``finishSyncing(statusDisplay:)-(NSWindow)`` method if your app uses AppKit.
If you're showing your own UI,
call the ``finishSyncing()`` method to wait for the directory to finish syncing.
After the directory is ready to use,
syncing pauses until you close the directory object or the object is deallocated.
To resume syncing during the game,
close and re-open the directory by calling ``close()`` and then ``openDirectory(containerIdentifier:)``.
class func openDirectory(containerIdentifier: String? = nil) -> GameSaveSyncedDirectory
Requests an instance of the game-save directory.
- Parameter containerIdentifier: The identifier of the directory to request.
If you pass `nil`, this method uses the first container identifier
listed in the `com.apple.developer.icloud-container-identifiers` entitlements array.
This method returns immediately, and starts syncing the directory in the background.
To wait for syncing to complete, call the ``finishSyncing()`` method.
Waits for the directory sync to complete, showing the sync's progress in a modal alert.
- Parameter window: The window where the system shows progress and alerts.
If the sync results in a conflict, the framework displays a conflict resolution UI
for the user to chose a version that will be used.
If the user isn't signed in to iCloud or iCloud drive,
the framework informs the user and then switches to local saving.
method · iOS 26.0+
finishSyncing
TypeScript
finishSyncing(): Promise<void>
Swift declaration
func finishSyncing() async
Waits for the directory sync to complete, without showing any user interface.
Use this method to wait if your app displays its own syncing UI.
Indicates that you resolved a conflict.
- Parameter version: The version to use.
If you're implementing your own conflict resolution,
read all of the conflicting versions,
and modify one of them to incorporate the state and changes from the others.
Then call this method, passing that version.
Call this method only when the directory is in the ``State/conflicted(versions:)`` state.
method · iOS 26.0+
triggerPendingUpload
TypeScript
triggerPendingUpload(): Promise<boolean>
Swift declaration
func triggerPendingUpload() async -> Bool
Triggers an upload of the directory for any changes that were pending.
- Returns: `true` if there were pending uploads; otherwise `false`.
get · iOS 26.0+
id
TypeScript
get id(): string
Swift declaration
var id: String { get }
The stable identity of the entity associated with this instance.
method · iOS 26.0+
close
TypeScript
close(): void
Swift declaration
func close()
Closes the directory, and resumes syncing the directory to the cloud.
