Events API | let an event reference a named spawn point of its scene

[popuz]

Events API: let an event reference a named spawn point of its scene

Type: feature / cross-team (Events API + Events web app + Explorer client)
Area: decentraland/events (events.decentraland.org), Explorer EventsApi + RealmNavigation
Explorer client size: trivial — one DTO field plus one argument at the single Jump In call site; the teleport pipeline already supports named spawn points end to end

Problem

An event only carries x, y (plus server/world). That names a parcel, but a parcel is not a
landing spot, so the Explorer has always had to guess where inside it to put the player — and every
guess so far has been wrong for someone:

• Landing on the scene's spawn point ignored the event's coordinates entirely: an event at the
  Theatre (0,5) inside Genesis Plaza dropped players at the plaza entrance (~0,-1).
• PR unity-explorer#8942 fixed that by
  landing at the geometric centre of the event's parcel — which is exactly where a small scene
  tends to stand its centrepiece asset. Players spawned on top of (or inside) the asset the event
  was about (unity-explorer#9546).
• PR unity-explorer#9567 fixed that
  with a client-side heuristic: if the scene declares a named spawn point whose area covers the
  event's parcel, land on it; otherwise keep the parcel centre.

The heuristic resolves every live event correctly today, but it is still the client guessing the
organizer's intent from geometry. It cannot cover:

• an event parcel that holds no spawn point — the player still gets the invented parcel-centre
  landing, "settled" by a physics floor probe (SnapToSceneFloor, 15 m step-up tolerance) that can
  place them on top of whatever stands there;
• a parcel covered by several spawn points — the client picks one by declaration order, the
  organizer has no say;
• an organizer who wants players to land at a spawn point outside the event parcel (e.g. a
  queue/lobby area for a stage event).

The missing piece was already named in #8942's own description:

A cleaner long-term option (out of scope here) is author-defined named spawn points in
scene.json that an event/place can reference.

Both halves of that option now exist — scene.json spawn points have an optional name, and since
PR unity-explorer#9369 the Explorer
teleport pipeline accepts a spawnPointName and resolves it with correct anchoring, cameraTarget
look-at, and graceful fallback when the name doesn't match. The only link still missing is the
Events API carrying the name from the organizer to the client.

Proposal

Add an optional spawn point name to the event model, flowing organizer → API → client:

1. API (decentraland/events): a new optional field on the event entity — suggested
   spawn_point_name: string | null (snake_case like the rest of the wire format) — accepted on
   event create/edit and returned by GET /api/events. Absent/null means "no preference", which
   must keep today's behaviour exactly.
2. Events web app (submit/edit form): a field to pick the spawn point. Ideally a dropdown
   populated from the deployed scene's metadata for the entered coordinates (the Catalyst
   POST /content/entities/active response carries metadata.spawnPoints[].name), with free-text
   as the minimum viable version — an unknown name degrades gracefully on the client (falls back to
   the default spawn selection, see FallBackToDefaultSelectionWhenNameNotMatched in
   TeleportUtilsShould).
3. Explorer client: deserialize the field in EventDTO and pass it at the single Jump In call
   site (EventCardActionsController) into the existing
   IRealmNavigator.TeleportToParcelAsync(parcel, ct, isLocal, landOnParcel, spawnPointName)
   overload. No pipeline changes.

Precedence on the client, most explicit wins:

Event data	Landing
spawn_point_name set	that spawn point, via the existing named-spawn-point path
not set, a named spawn point covers the event parcel	that spawn point (the #9567 heuristic, unchanged)
not set, no spawn point in the parcel	parcel centre + floor probe (the #8942 behaviour, unchanged)

This also gives organizers the "flexible behaviour without redeploying the scene" property the
parcel coordinates were informally used for: one scene, different events, different landings — now
deterministic instead of guessed.

Non-goals

• No change to scene.json — spawn point names already exist there.
• No validation hard-failure when the name doesn't match the deployed scene (scenes redeploy
  independently of events; the client fallback handles drift).
• The landOnParcel plumbing refactor is tracked separately in
  unity-explorer#9583; this ticket
  neither depends on it nor blocks it.

Acceptance criteria

• GET /api/events returns spawn_point_name (null when unset) and create/edit accept it
• Events web form lets an organizer set/clear the spawn point for a Genesis City event
• Explorer Jump In on an event with spawn_point_name lands on that spawn point, honouring its
  cameraTarget
• Explorer Jump In on an event without the field behaves exactly as today (heuristic, then
  parcel centre)
• An event whose spawn_point_name no longer matches the deployed scene falls back to the
  scene's default spawn selection instead of erroring

History

When	What	Where
—	scene.json spawnPoints[] support optional name; teleport docs	scene metadata docs
2026-06-15	Events Jump In lands on the event parcel (centre) via landOnParcel; the "named spawn point an event can reference" option called out as the cleaner long-term fix	unity-explorer#8942
2026-06	spawnPointName threaded through the whole teleport pipeline (deeplink overrides): name matching, base-parcel anchoring, cameraTarget, fallback on unknown name	unity-explorer#9369
2026-07	Bug report: Events Jump In lands players inside the scene's centrepiece asset	unity-explorer#9546
2026-08-03	Client-side heuristic: land on the named spawn point covering the event's parcel, if any	unity-explorer#9567
2026-08-04	Tech-debt ticket: replace the landOnParcel flag with an explicit teleport destination	unity-explorer#9583

Links

• Events API: https://events.decentraland.org/api/events — decentraland/events
• Explorer DTO: Explorer/Assets/DCL/EventsApi/EventDTO.cs
• Explorer Jump In call site: Explorer/Assets/DCL/Events/EventCardActionsController.cs (the only landOnParcel: true caller)
• Named spawn point resolution: Explorer/Assets/DCL/Infrastructure/SceneLifeCycle/TeleportUtils.cs (PickTargetWithOffset)

[github-actions]

Automated Triage

Issue type	enhancement
Affected area	Events (Genesis Plaza)
Feature category	Primary
Priority	2-medium

Reasoning: This is a well-scoped enhancement to the Events system, which is a Primary category feature. The feature adds optional spawn_point_name to the Events API, allowing event organizers explicit control over where players land (instead of the current client-side heuristic). Explorer client changes are trivial (one DTO field + single call site). Precedence clearly defined with graceful fallback when name doesn't match deployed scene.

Labels applied: feature, enhancement, 2-medium, shape-up

---

Auto-triaged. If labels are incorrect, update issue triage categories or severity policy and re-run triage.

[popuz]

verify how it works in the multi-scene worlds and Genesis Plaza!