A Guide to JigSpace-Style Anchors in RealityKit

Creating a Ghost Material

A simple way to create a ghost material is to use an UnlitMaterial with a translucent color. This avoids complex lighting calculations and looks clean.

// Create a semi-transparent material for our ghost
let ghostMaterial = UnlitMaterial(color: .white.withAlphaComponent(0.5))

// Clone your model and apply the ghost material
// We'll assume 'originalCarEntity' is already loaded
ghostCarEntity = originalCarEntity.clone(recursive: true)
ghostCarEntity.model?.materials = [ghostMaterial]

// We'll also need a static anchor to hold the ghost in our scene
let ghostAnchor = AnchorEntity()
ghostAnchor.addChild(ghostCarEntity)
arView.scene.addAnchor(ghostAnchor)

ghostCarEntity.isEnabled = false // Start with it hidden

Continuous Raycasting

To make the ghost follow surfaces, we need to perform a raycast from the center of the screen on every frame. The ARView's session delegate is the perfect place for this. Make sure your view controller conforms to ARSessionDelegate.

func session(_ session: ARSession, didUpdate frame: ARFrame) {
    // Use the center of the view for the raycast
    let screenCenter = arView.center

    // Perform a raycast to find a horizontal plane
    guard let query = arView.makeRaycastQuery(from: screenCenter, 
                                              allowing: .estimatedPlane, 
                                              alignment: .horizontal),
          let result = arView.session.raycast(query).first else {
        // If no surface is found, hide the ghost
        ghostCarEntity.isEnabled = false
        return
    }

    // If we found a surface, show and position the ghost
    ghostCarEntity.isEnabled = true
    
    // Update the ghost's position to the raycast result's world transform
    ghostCarEntity.transform.matrix = result.worldTransform
}

With this code, you'll now see a ghostly car gliding across any horizontal surfaces your camera sees. It's a bit jittery, but we'll fix that later. First, let's handle the placement.

Step 2: The "Sticky" Placement

Now for the satisfying part: tapping to place the object permanently. We'll add a tap gesture recognizer to our ARView.

override func viewDidLoad() {
    super.viewDidLoad()
    // ... other setup ...

    let tapGesture = UITapGestureRecognizer(target: self, action: #selector(handleTap))
    arView.addGestureRecognizer(tapGesture)
}

@objc func handleTap(_ sender: UITapGestureRecognizer) {
    // Get the tap location
    let tapLocation = sender.location(in: arView)

    // Perform a raycast from the tap location
    guard let query = arView.makeRaycastQuery(from: tapLocation, 
                                              allowing: .estimatedPlane, 
                                              alignment: .horizontal),
          let result = arView.session.raycast(query).first else {
        // User tapped on a non-viable surface
        return
    }

    // Create a NEW anchor at the exact world position
    // This is the key! We use AnchorEntity(world:) instead of AnchorEntity(plane:)
    let finalAnchor = AnchorEntity(world: result.worldTransform)

    // Add your REAL model to this new, static anchor
    // Assuming 'realCarEntity' is your fully-textured model
    finalAnchor.addChild(realCarEntity.clone(recursive: true))

    // Add the new anchor to the scene
    arView.scene.addAnchor(finalAnchor)

    // Optional: Hide the ghost after placing an object
    ghostCarEntity.isEnabled = false
}

And that's the core logic! By creating an AnchorEntity with a specific world transform, we're telling RealityKit, "Put this here and leave it alone." It's no longer tethered to the ever-changing ARPlaneAnchor, resulting in a perfectly stable placement.

Refining the Experience

The basic functionality is there, but a few refinements can elevate the experience from functional to fantastic.

Smoothing the Ghost's Movement

The ghost's movement can be jarring as it snaps to new positions every frame. We can smooth this out with a simple linear interpolation (LERP). Instead of instantly setting the ghost's transform, we'll move it a fraction of the way towards the target transform each frame.

Update your session(_:didUpdate:) method:

func session(_ session: ARSession, didUpdate frame: ARFrame) {
    // ... raycast logic as before ...
    guard let result = arView.session.raycast(query).first else {
        // ...
        return
    }

    ghostCarEntity.isEnabled = true
    
    // The new target transform
    let targetTransform = Transform(matrix: result.worldTransform)

    // Smoothly move the ghost towards the target
    // The 'deltaTime' is the time since the last frame update
    // The '0.1' factor controls the speed of the smoothing
    let smoothingFactor: Float = 0.1 
    ghostCarEntity.transform = Transform.lerp(from: ghostCarEntity.transform, to: targetTransform, t: smoothingFactor)
}

// You might need to add a LERP function to Transform if it's not available
// extension Transform {
//     static func lerp(from start: Transform, to end: Transform, t: Float) -> Transform {
//         let newTranslation = simd_mix(start.translation, end.translation, t)
//         let newRotation = simd_slerp(start.rotation, end.rotation, t)
//         let newScale = simd_mix(start.scale, end.scale, t)
//         return Transform(scale: newScale, rotation: newRotation, translation: newTranslation)
//     }
// }

This small change makes the ghost feel like it's gliding gracefully over surfaces, which is much more visually appealing.

Guiding the User

Don't forget to help your user! The ARCoachingOverlayView is essential for telling users to move their phone around to find a surface. If no surface is found, the ghost won't appear, and the user might not know why. The coaching overlay solves this problem elegantly.

Conclusion: It's All About Control

The "JigSpace-style" anchor isn't a secret API; it's a design pattern centered on taking control back from the system. By separating the real-time preview from the final, committed placement, you provide an experience that feels both responsive and incredibly stable.

To recap the key points:

• Use continuous raycasting to power a "ghost" preview object.
• Smooth the ghost's movement with LERP for a polished feel.
• On user tap, perform a final raycast to get a precise location.
• Create a static AnchorEntity(world:) at that exact transform for a rock-solid placement.

Give this technique a try in your next RealityKit project. Your users will notice the difference, even if they can't quite put their finger on why it just feels so... right.