⬡ Dev Tools/2026-07-18Advanced

Your AR Furniture Is Gone by Morning — Persisting Placements with ARWorldMap

AR apps generated by Rork Max lose every placed object on relaunch. Here is the design that fixes it: when to save an ARWorldMap, how to encode custom anchors, how to handle the relocalization wait, and what to do when relocalization simply never lands.

Rork Max²²⁹ ARKit² ARWorldMap Swift⁴⁸ indie development³¹

✦ Premium Article

Ask Rork Max for an AR app that places furniture on the floor, and it hands you something that works on the first run. Session setup, plane detection, tap-to-place — all of it, without writing a line of Swift yourself.

The trouble showed up the next morning.

I closed the app after placing a few pieces, reopened it the following day, and every single object was gone. Not a bug. An ARKit session remembers nothing unless you tell it to. After years of shipping wallpaper apps as an indie developer, I thought I had a decent nose for missing persistence — but AR moved the goalposts. Saving coordinates is not enough.

What follows is the design that fills that gap.

Why saving coordinates does not bring anything back

The instinctive fix is to serialize each tap's simd_float4x4 to JSON. It does not work, because the coordinate system itself is rebuilt from scratch every session.

ARKit places the world origin wherever the device happened to be when tracking started. Launch near the doorway yesterday and beside the sofa today, and identical numbers now point meters apart. Coordinates only mean something alongside the map that interprets them.

That map is ARWorldMap, and it holds three kinds of things:

Element	What it is	Saved?
Feature points	The point cloud the camera has recognized (rawFeaturePoints)	Yes
Anchors	Your ARAnchor list — transforms and identifiers	Yes
3D models	The meshes and materials you are rendering	No

That third row costs people a night. ARWorldMap remembers where. It never remembers what. Restore it naively and your anchors come back to an empty screen.

Giving anchors something to say

The fix is to subclass ARAnchor and carry your own payload. World map archiving encodes anchors too, so a correct NSSecureCoding implementation ships your model identifiers along with the map.

final class FurnitureAnchor: ARAnchor {
    // The key that decides which model to rebuild on restore
    let catalogID: String
    let placedAt: Date
 
    init(catalogID: String, transform: simd_float4x4) {
        self.catalogID = catalogID
        self.placedAt = Date()
        super.init(name: "furniture", transform: transform)
    }
 
    // ARKit calls this whenever it copies an anchor inside a session.
    // Skip it and your payload is gone before it ever reaches disk.
    required init(anchor: ARAnchor) {
        let other = anchor as! FurnitureAnchor
        self.catalogID = other.catalogID
        self.placedAt = other.placedAt
        super.init(anchor: other)
    }
 
    override class var supportsSecureCoding: Bool { true }
 
    required init?(coder: NSCoder) {
        guard let id = coder.decodeObject(of: NSString.self, forKey: "catalogID") as String? else {
            return nil  // Older maps: refuse rather than restore garbage
        }
        self.catalogID = id
        self.placedAt = coder.decodeObject(of: NSDate.self, forKey: "placedAt") as Date? ?? Date()
        super.init(coder: coder)
    }
 
    override func encode(with coder: NSCoder) {
        super.encode(with: coder)
        coder.encode(catalogID as NSString, forKey: "catalogID")
        coder.encode(placedAt as NSDate, forKey: "placedAt")
    }
}

When I layer this onto generated code, init(anchor:) is the first thing I check. Leave it out and everything looks fine during the session — only the saved map comes back hollow. You cannot catch that without closing the app on a real device, which makes it the single easiest thing to miss in a code review.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Find out why AR placements vanish on relaunch, and add ARWorldMap save/restore in roughly 60 lines of Swift

✦Sidestep the two traps that silently destroy saved data: mappingStatus timing and NSSecureCoding on custom anchors

✦Ship an escape hatch for the 30-second relocalization failures that otherwise read as a frozen app

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Save only once mappingStatus reaches .mapped

You can call getCurrentWorldMap at any time. That does not mean you should. ARKit publishes how mature the map is through mappingStatus.

The four states, and why waiting matters

.notAvailable — no map yet; the call fails.
.limited — too few feature points; restore almost never lands.
.extending — usable, but the surroundings are half-recorded.
.mapped — the area around you is well covered.

In my one-bedroom apartment, walking three or four slow steps near the center reached .mapped in roughly 12–20 seconds. Holding the camera still on one spot left me stuck at .extending past 90 seconds. Feature points come from parallax, so the requirement is movement, not patience.

func saveWorldMap(session: ARSession, to url: URL) async throws {
    // Saving below .mapped roughly halved my restore success rate
    guard let frame = session.currentFrame,
          frame.worldMappingStatus == .mapped else {
        throw MapError.notReadyYet
    }
 
    let map = try await withCheckedThrowingContinuation { cont in
        session.getCurrentWorldMap { map, error in
            if let map { cont.resume(returning: map) }
            else { cont.resume(throwing: error ?? MapError.unknown) }
        }
    }
 
    let data = try NSKeyedArchiver.archivedData(
        withRootObject: map, requiringSecureCoding: true)
    // The point cloud dominates: 4–11 MB for a whole apartment
    try data.write(to: url, options: [.atomic, .completeFileProtection])
}

.completeFileProtection is deliberate. A world map is the shape of someone's room. It is less legible than a photo, but it is still a record of where they live, and it belongs somewhere that cannot be read while the device is locked.

Restoring, and the wait nobody designs for

Restoring means handing the map to initialWorldMap. Placements do not snap back at that moment. ARKit compares what the camera sees now against the stored point cloud, and only reconnects the coordinate system once it finds a match. Throughout that comparison the session sits in .limited(.relocalizing).

func restore(from url: URL, into session: ARSession) throws {
    let data = try Data(contentsOf: url)
    guard let map = try NSKeyedUnarchiver.unarchivedObject(
        ofClass: ARWorldMap.self, from: data) else {
        throw MapError.decodeFailed
    }
 
    let config = ARWorldTrackingConfiguration()
    config.planeDetection = [.horizontal]
    config.initialWorldMap = map
    // Never pair this with resetTracking — anchors would double up
    session.run(config, options: [.removeExistingAnchors])
}
 
func session(_ session: ARSession, cameraDidChangeTrackingState camera: ARCamera) {
    switch camera.trackingState {
    case .limited(.relocalizing):
        statusText = "Looking for last time's spot — point the camera where you placed things"
    case .normal:
        statusText = nil          // Placements only reappear here
        relocalizeDeadline?.cancel()
    default:
        break
    }
}

Drop .removeExistingAnchors and the restored anchors stack on top of the previous run, so every chair arrives twice. Generated code tends to ship resetTracking by default, which quietly cancels the point of passing a map at all. I check that line every time.

Model rebuilding then happens in the anchor-added callback:

func renderer(_ renderer: SCNSceneRenderer, didAdd node: SCNNode, for anchor: ARAnchor) {
    guard let furniture = anchor as? FurnitureAnchor else { return }
    // The map has no models. Rebuild from catalogID yourself.
    node.addChildNode(FurnitureLibrary.makeNode(id: furniture.catalogID))
}

Plan the escape hatch before you need it

This is the part the documentation is quietest about: relocalization is not guaranteed to succeed.

Three conditions produced most of my failures on device:

The lighting changed (a map saved at noon, restored under a ceiling light at night)
The user entered from a different direction (those feature points were never seen from that side)
Furniture had been moved substantially, so the room no longer matches itself

To the user, all three look identical: the app froze. Waiting in silence is how you lose them. I give the wait a deadline.

// Cut it off at 30 seconds. Successful relocalizations landed in 5–15.
relocalizeDeadline = Task {
    try? await Task.sleep(for: .seconds(30))
    guard !Task.isCancelled else { return }
    await MainActor.run { self.offerManualRecovery() }
}
 
@MainActor
func offerManualRecovery() {
    // Offer choices instead of an endless spinner:
    // 1. Try again (with a nudge to return to the original spot)
    // 2. Re-place the whole arrangement relative to where you stand now
    // 3. Start over
    presentRecoverySheet()
}

Option two earns its keep. Relative positions between anchors survive without a map, so you can preserve the table-and-chairs relationship and drop the whole arrangement onto today's floor. Not a true restore — but far cheaper than placing everything again.

Size, and the decisions to make before you save

Maps are not small. A desk area alone measured 1.8 MB for me; walking a full apartment pushed past 11 MB. Save per room and you are stacking tens of megabytes on someone's phone.

Three decisions worth making up front:

Granularity — one file per room. A single giant map means rewriting everything on every update.
Cap and eviction — I keep the five most recent rooms and evict by last-used date.
Your App Store disclosure — a map is spatial data. Say plainly, in your camera usage description, that a record of the space stays on device and why. Ship it vague and review will ask.

iCloud sync is tempting. I keep maps device-local by default, because a map leaving the device means the shape of someone's home leaves with it. If sharing is genuinely the product, unlock it behind explicit consent — in that order.

The smallest version worth building first

Building all of this at once makes failure impossible to localize. The order I recommend:

Place one anchor and put mappingStatus on screen. Feel how movement drives it.
Save once you hit .mapped and log the file size. A few MB means it worked.
Fully quit, relaunch, restore. Time the gap between .limited(.relocalizing) and .normal.
Add the custom anchor and model rebuilding. Now what comes back too.
Add the deadline and the escape hatch.

Measuring step 3 early is what keeps you from guessing at the deadline later.

For where native generation stops and hand work resumes, see where Rork Max still falls short. For the measuring side of spatial apps, building a room-measuring app with RoomPlan covers adjacent ground, and ten refactoring patterns for generated SwiftUI covers polishing the output itself.

Start with step 1 in today's Rork Max session. The moment mappingStatus appears on screen, what AR sees and what it forgets clicks faster than any explanation can manage. It took me several days of detours to put that one line there. I hope you can skip them.

Thank You for Reading

Rork Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.