Contextual Onboarding & First Arrival

“Use your phone.”

Shortly after Broken Compass opened publicly, seemingly different questions kept reaching the same answer. Where is a business? How do I find a service? How do I get there? Use your phone.

Players also needed help with vehicle purchasing, contextual controls, and Third Eye, the interaction used to act on objects in the world. Some older documentation described interactions that had changed.

The underlying problem was the interaction grammar of the environment. Players didn't know that the Phone Directory was the primary wayfinding layer, or which action made sense where. More documentation would still require them to know what they didn't know before searching for it.

Leave with something real.

After connecting and creating a character, the player purchases or finances a real, persistent vehicle. Third Eye becomes useful at the dealership. Customs introduces vehicle customization. The Phone Directory gives them a reason to learn the phone: find Kathi's Cafe and set a GPS route.

Vehicle and seatbelt controls arrive while driving. At the cafe, the normal shop interaction lets them buy actual food. They return to the car, drive home, and store it in the real garage. Pedestrian breadcrumbs then lead toward the apartment and the existing city-orientation experience.

The player finishes with a vehicle, food, and experience using the systems they'll need next. Progression observes successful actions rather than advancing because someone clicked Next.

The instruction gets lighter.

Finding the cafe introduces the phone, directory, and GPS as one useful workflow. Once the route is set, the next instruction is shorter: follow it. Seatbelt and vehicle controls appear here because the player is driving.

Being in a vehicle wasn't a reason to teach everything a vehicle could do. I deliberately left the custom radio out of First Arrival. Its instruction belongs later, when the player installs it and has a reason to learn it.

Early copy assumed default keyboard mappings such as LEFT ALT. Investigation showed that effective labels could be resolved at presentation time. Relevant controls are surfaced dynamically where possible, so the instruction respects the player's customized controls instead of blindly teaching defaults.

The boundary was in the wrong place.

Hypothesis: Put the new player into a private tutorial instance immediately. FiveM calls these routing buckets. They separate players and entities from the shared world.

Evidence: A dealership vehicle could be created inside that private instance, then fail Qbox's post-spawn ownership and property validation and be deleted. Vehicle spawning depended on client and network ownership behavior that did not survive the purchase lifecycle correctly inside the private bucket.

Decision: Let the dealership purchase and validated vehicle spawn finish in the normal shared world, bucket 0. Only after a valid owned vehicle exists and the player is seated in it do the player and vehicle move together into the private tutorial bucket.

I moved the onboarding boundary to fit the production lifecycle. Rewriting that lifecycle to preserve my original assumption would have made the wrong thing more complicated.

Moving a person didn't close the property.

First Arrival exposed a separate property lifecycle defect. Character creation could physically move a player away from an apartment without properly closing their qbx_properties state. Returning to the area later exposed that stale state and a concurrency weakness in exitProperty().

The first question was why invalid state existed. I repaired the upstream lifecycle through a supported server-side integration point so the property state closed correctly.

Then I hardened the downstream exit function: snapshot the property ID before yielding, use a per-player exit lock, and avoid repeatedly reading mutable state. Repeated or concurrent exit attempts could then be handled safely.

A nil check alone would have hidden the symptom. The repair had to address both the lifecycle that created the stale state and the function that could encounter it.