Version: 1.0

GDScript API

The plugin provides a GDScript wrapper named HealthKit, which is automatically registered as an Autoload singleton when the plugin is enabled. It handles platform checks and provides mock data for non-iOS platforms.

Singleton: HealthKit

func _ready() -> void:
    # Connect to signals
    HealthKit.permission_result.connect(_on_permission_result)
    HealthKit.steps_updated.connect(_on_steps_updated)

    # Request permission
    HealthKit.request_permission()

    # Check permission and availability
    var is_available: bool = HealthKit.is_health_data_available()
    var status: int = HealthKit.get_permission_status()

    # Start real-time observer and background delivery
    HealthKit.start_step_observer()

    # Async snapshot queries (call first, then read result after ~1s)
    HealthKit.run_today_steps_query()
    HealthKit.run_total_steps_query()
    HealthKit.run_period_steps_query(7)  # last 7 days

    # Read cached results
    var today: int = HealthKit.get_today_steps()
    var total: int = HealthKit.get_total_steps()
    var period: Dictionary = HealthKit.get_period_steps_dict()  # {"2026-03-15": 5432, ...}

Signals

Signal	Description
`permission_result(granted: bool)`	Emitted after `request_permission()` completes.
`steps_updated(steps: int)`	Emitted when `HKObserverQuery` detects a change in today's step count.
`today_steps_ready(steps: int)`	Emitted when `run_today_steps_query()` completes.
`total_steps_ready(steps: int)`	Emitted when `run_total_steps_query()` completes.
`period_steps_ready(steps_dict: Dictionary)`	Emitted when `run_period_steps_query()` completes.
`pedometer_steps_updated(steps: int)`	Emitted when the real-time pedometer detects new steps since it was started.
`pedometer_error(reason: String)`	Emitted if the pedometer encounters an error.

Methods

Method	Returns	Description
`request_permission()`	`void`	Requests permission to read HealthKit data.
`get_permission_status()`	`int`	Returns the `AuthorizationStatus`.
`get_permission_status_string(status: int)`	`String`	Returns a human-readable string for the given `AuthorizationStatus`.
`is_health_data_available()`	`bool`	Checks if HealthKit is available on the device.
`start_step_observer()`	`void`	Starts background observation for step count changes.
`stop_step_observer()`	`void`	Stops background step observation.
`is_pedometer_available()`	`bool`	Checks if the device supports CMPedometer.
`get_pedometer_permission_status()`	`int`	Returns the `MotionAuthorizationStatus`.
`start_pedometer_observer()`	`void`	Starts real-time pedometer tracking.
`stop_pedometer_observer()`	`void`	Stops real-time pedometer tracking.
`get_live_pedometer_steps()`	`int`	Returns the number of steps tracked since the pedometer was started.
`run_today_steps_query()`	`void`	Requests the total step count for today. Emits `today_steps_ready` when done.
`get_today_steps()`	`int`	Returns the cached step count for today (after query finishes).
`run_total_steps_query()`	`void`	Requests the all-time total step count. Emits `total_steps_ready` when done.
`get_total_steps()`	`int`	Returns the cached all-time step count (after query finishes).
`run_period_steps_query(days: int)`	`void`	Requests daily step counts for the past `days`. Emits `period_steps_ready`.
`get_period_steps_dict()`	`Dictionary`	Returns the cached dictionary of period steps.
`open_settings()`	`void`	Opens the app settings.

GDScript API

Singleton: HealthKit

Signals

Methods

Enums

AuthorizationStatus (HealthKit)

MotionAuthorizationStatus (CoreMotion)

Singleton: HealthKit​

Signals​

Methods​

Enums​

AuthorizationStatus (HealthKit)​

MotionAuthorizationStatus (CoreMotion)​

Singleton: HealthKit

Signals

Methods

Enums

AuthorizationStatus (HealthKit)

MotionAuthorizationStatus (CoreMotion)