NSUbiquitousKeyValueStore¶

Shares small preferences between a user’s Apple devices through iCloud.

Description¶

Uses Apple’s shared default key-value store. Keep this wrapper while you need its signals. Connect did_change_externally before you call synchronize() at launch. Each wrapper registers a native

observer and removes it when released. Keep a local copy of preferences so the app works without iCloud. The

exported app needs the com.apple.developer.ubiquity-kvstore-identifier entitlement. Use the same store

identifier on all app targets that must share values.

Values can be bool, int, float, String, PackedByteArray, Array, or Dictionary. Dictionary keys must be

strings. Nested containers can have at most 64 levels. Null entries and other Godot types are rejected.

Setters return false for invalid input. A true result only confirms that the binding passed the write to

Apple. It does not confirm cloud delivery or quota acceptance.

Apple permits 1,024 keys and 1 MB of values in total. A single value can be at most 1 MB. Each key can have

at most 128 UTF-16 code units. Use this store for preferences that change infrequently. Keep sensitive data

in Keychain. Windows and Linux stubs do not store or synchronize values.

Tutorials¶

Properties¶

Dictionary

dictionary_representation

Methods¶

Array	array_for_key(key: String)
bool	bool_for_key(key: String)
PackedByteArray	data_for_key(key: String)
NSUbiquitousKeyValueStore	default_store() static
Dictionary	dictionary_for_key(key: String)
float	double_for_key(key: String)
int	long_long_for_key(key: String)
Variant	object_for_key(key: String)
void	remove_object_for_key(key: String)
bool	set_array(value: Array, key: String)
bool	set_bool(value: bool, key: String)
bool	set_data(value: PackedByteArray, key: String)
bool	set_dictionary(value: Dictionary, key: String)
bool	set_double(value: float, key: String)
bool	set_long_long(value: int, key: String)
bool	set_object(value: Variant, key: String)
bool	set_string(value: String, key: String)
String	string_for_key(key: String)
bool	synchronize()

Signals¶

did_change_externally(reason: ChangeReason, changed_keys: PackedStringArray) 🔗

Reports Apple’s external change notification on the main thread when this signal has a connection. The

reason is a ChangeReason value. Read the changed keys from the store to get their current values;

keys can have been removed. The key list is empty when Apple omits it. Handle account and quota reasons

even when the list is empty. Local writes do not emit this signal.

Enumerations¶

enum ChangeReason: 🔗

ChangeReason SERVER_CHANGE = 0

Values changed in iCloud. Read the changed keys and update local preferences.

ChangeReason INITIAL_SYNC_CHANGE = 1

Values were downloaded during initial synchronization. Read them before you upload defaults.

ChangeReason QUOTA_VIOLATION_CHANGE = 2

The store exceeded its quota. Reduce stored data and keep local preferences available.

ChangeReason ACCOUNT_CHANGE = 3

The user changed the Apple account. Apply the app’s account policy. Do not upload the previous account’s

preferences automatically.

Property Descriptions¶

Dictionary dictionary_representation 🔗

Dictionary get_dictionary_representation()

A snapshot of all stored keys and values. Data becomes PackedByteArray. Native Date values become float

Unix seconds.

Method Descriptions¶

Array array_for_key(key: String) 🔗

Returns the Array value for the key. Returns an empty array if the key is absent. Use object_for_key() to check whether a key exists.

bool bool_for_key(key: String) 🔗

Returns the bool value for the key. Returns false if the key is absent. Use object_for_key() to

check whether a key exists.

PackedByteArray data_for_key(key: String) 🔗

Returns the PackedByteArray value for the key. Returns an empty byte array if the key is absent. Use

object_for_key() to check whether a key exists.

NSUbiquitousKeyValueStore default_store() static 🔗

Returns a new Godot wrapper for Apple’s shared default store. Construction with new() uses the same native

store. Keep one wrapper to receive its signal. On Windows and Linux, the stub returns null.

Dictionary dictionary_for_key(key: String) 🔗

Returns the Dictionary value for the key. Returns an empty dictionary if the key is absent. Use object_for_key() to check whether a key exists.

float double_for_key(key: String) 🔗

Returns the float value for the key. Returns 0.0 if the key is absent. Use object_for_key() to

check whether a key exists.

int long_long_for_key(key: String) 🔗

Returns the int value for the key. Returns 0 if the key is absent. Use object_for_key() to check

whether a key exists.

Variant object_for_key(key: String) 🔗

Returns the value, or null if the key is absent. Data becomes PackedByteArray. Nested arrays and

dictionaries are converted recursively. Native Date values become float Unix seconds.

void remove_object_for_key(key: String) 🔗

Removes the key and its value. Local removal does not emit did_change_externally.

bool set_array(value: Array, key: String) 🔗

Sets the value for the key. Returns false for invalid input. A true result confirms that the binding

passed the write to Apple. It does not confirm quota acceptance or cloud delivery. Local writes do not

emit did_change_externally. All dictionary keys must be String. Containers can contain only

supported property list values.

bool set_bool(value: bool, key: String) 🔗

Sets the value for the key. Returns false for invalid input. A true result confirms that the binding

passed the write to Apple. It does not confirm quota acceptance or cloud delivery. Local writes do not

emit did_change_externally.

bool set_data(value: PackedByteArray, key: String) 🔗

Sets the value for the key. Returns false for invalid input. A true result confirms that the binding

passed the write to Apple. It does not confirm quota acceptance or cloud delivery. Local writes do not

emit did_change_externally.

bool set_dictionary(value: Dictionary, key: String) 🔗

Sets the value for the key. Returns false for invalid input. A true result confirms that the binding

passed the write to Apple. It does not confirm quota acceptance or cloud delivery. Local writes do not

emit did_change_externally. All dictionary keys must be String. Containers can contain only

supported property list values.

bool set_double(value: float, key: String) 🔗

Sets the value for the key. Returns false for invalid input. A true result confirms that the binding

passed the write to Apple. It does not confirm quota acceptance or cloud delivery. Local writes do not

emit did_change_externally.

bool set_long_long(value: int, key: String) 🔗

Sets the value for the key. Returns false for invalid input. A true result confirms that the binding

passed the write to Apple. It does not confirm quota acceptance or cloud delivery. Local writes do not

emit did_change_externally.

bool set_object(value: Variant, key: String) 🔗

Sets a supported property list value. A top-level null removes the key. Unsupported types, null entries in

containers, non-string dictionary keys, and containers deeper than 64 levels cause the entire write to

fail. Returns false for invalid input. A true result does not confirm quota acceptance or cloud delivery.

bool set_string(value: String, key: String) 🔗

Sets the value for the key. Returns false for invalid input. A true result confirms that the binding

passed the write to Apple. It does not confirm quota acceptance or cloud delivery. Local writes do not

emit did_change_externally.

String string_for_key(key: String) 🔗

Returns the String value for the key. Returns an empty string if the key is absent. Use object_for_key() to check whether a key exists.

bool synchronize() 🔗

Returns Apple’s synchronization result. Connect did_change_externally first. Call this at launch

or when the app returns to the foreground. This does not force an immediate upload or confirm delivery to

other devices. A false result can indicate missing app entitlements.