How it works
WorldTrackingLimitation describes the conditions that are currently degrading the system's ability to track the device in physical space — situations such as rapid camera movement or a visually featureless environment. It's modeled as an option set, so a single value can carry zero, one, or several limitations at once, letting you reason about tracking health as a set of flags rather than a single status code. Reach for it when your spatial experience needs to react to a loss of tracking quality — for example, to surface guidance to the person or to pause behavior that depends on a stable world anchor.
Hold the limitations in state
Because WorldTrackingLimitation conforms to OptionSet, an empty value means tracking is unimpaired and a populated value enumerates what's currently wrong. The example stores one in
@State private var limitation: WorldTrackingLimitation = [], using the empty array literal to express the nominal, no-limitations case.Test for the nominal case with isEmpty
An OptionSet is empty when none of its flags are set, so
isEmptyis the direct way to ask whether tracking is healthy. The example branches onlimitation.isEmptyto choose between a "nominal" message and a description of the active limitations.Inspect individual flags with contains(_:)
Each distinct condition is exposed as a static member you can probe with
contains(_:). The example checkslimitation.contains(.excessiveMotion)andlimitation.contains(.insufficientFeatures)to build a human-readable list, naming the two limitations that the option set can report.Add a limitation with insert(_:)
Since the type is an OptionSet, you compose values with set operations rather than reassigning the whole status. The example calls
limitation.insert(.excessiveMotion)to turn that single flag on while leaving any other active limitations untouched.Clear all limitations by resetting to empty
Assigning the empty option set removes every flag in one step, returning tracking to its nominal state. The "Reset tracking" button does exactly this with
limitation = [], which drivesisEmptyback to true.
limitation.insert(.excessiveMotion) to limitation.insert(.insufficientFeatures) to watch the status text and warning icon report a different limitation.Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct WorldTrackingLimitationDemo: View {
@State private var limitation: WorldTrackingLimitation = []
private var statusText: String {
if limitation.isEmpty {
return "World tracking: nominal"
}
var parts: [String] = []
if limitation.contains(.excessiveMotion) { parts.append("Excessive motion") }
if limitation.contains(.insufficientFeatures) { parts.append("Insufficient features") }
return parts.joined(separator: ", ")
}
var body: some View {
VStack(alignment: .leading, spacing: 12) {
Label(statusText, systemImage: limitation.isEmpty ? "checkmark.circle" : "exclamationmark.triangle")
.font(.headline)
.foregroundStyle(limitation.isEmpty ? .green : .orange)
Button("Simulate excessive motion") {
limitation.insert(.excessiveMotion)
}
Button("Reset tracking") {
limitation = []
}
}
.padding()
}
}