ui_popup_generic_runtime

Instruction file imported from madhackademie/RaymanInifiteRunner (.cursor/rules/ui_popup_generic_runtime.mdc). Copyright stays with the author.

UI popup runtime rules (Unity 6):

• Use the generic popup pipeline for runtime popups:
  • PopupId for popup identifiers,
  • ScreenPopupBinding for screenId -> popupId -> prefab,
  • ScreenPopupHost for lazy instantiate/show/hide.
• Treat popup bindings as the single source of truth.
• Keep popup wiring explicit in UIManager.runtimePopupBindings.
• For new popup features, add a dedicated popup id instead of hardcoded strings.
• If a popup binding is missing, fail closed with a clear warning (no hidden fallback path).

Architecture guidance:

• Keep popup views/prefabs reusable and screen-agnostic when possible.
• Keep gameplay/business logic in controllers/services, not in popup view classes.
• Prefer one runtime popup path per use case to avoid duplicate behavior.

Anti-patterns to avoid:

• Direct popup instantiation in feature screens as a long-term runtime path.
• Hidden legacy fallback flows that bypass the generic popup host.
• Multiple concurrent popup sources for the same use case.

Migration checklist (required for each new popup):

1. Add a new constant in PopupId (no magic string in feature code).
2. Add or validate one explicit ScreenPopupBinding entry:
   • screenId target,
   • popupId,
   • popupPrefab.
3. Resolve/open the popup through ScreenPopupHost only.
4. Remove or reject direct/fallback popup paths for the same use case.
5. Verify runtime behavior:
   • one user action => one popup instance shown,
   • no duplicate popup from a second source,
   • clear warning if binding is missing.
6. Update UI documentation (Notes/Ui/popup_generique.md) and log the change in PROJECT_LOG.md.