feat: ui renderer default virtual screen (#1444)

Author: pravusjif

packages/@dcl/react-ecs/src/platform.ts

@@ -0,0 +1,28 @@
+/**
+ * Platform detection hook for the UI scale system.
+ *
+ * react-ecs stays independent of the scene runtime (`~system/*` modules), so
+ * it cannot ask the explorer which platform it runs on. Instead, the host SDK
+ * injects the check at module-load time (see `@dcl/sdk/react-ecs`). Until a
+ * provider is injected — or when none ever is — the platform is assumed to be
+ * non-mobile.
+ */
+let isMobileProvider: () => boolean = () => false
+
+/**
+ * Injects the function used to detect whether the scene runs on a mobile
+ * platform. Called by `@dcl/sdk` with its `isMobile()` platform helper.
+ */
+export function setIsMobileProvider(provider: () => boolean): void {
+  isMobileProvider = provider
+}
+
+/**
+ * Whether the scene is running on a mobile platform, according to the
+ * injected provider. Platform detection is asynchronous on the SDK side, so
+ * this may return false during the first ticks and flip to true once the
+ * explorer information arrives.
+ */
+export function isMobile(): boolean {
+  return isMobileProvider()
+}

packages/@dcl/react-ecs/src/system.ts

@@ -12,6 +12,11 @@ import {
   setScreenInsetArea,
   setUiScaleFactor
 } from './components/utils'
+import { isMobile } from './platform'
+
+// react-ecs compiles with `types: []` (no runtime typings), so the console
+// global provided by the scene runtime is declared here.
+declare const console: { log(message: string): void }
 
 /**
  * @public
@@ -26,6 +31,26 @@ export type UiRendererOptions = {
   virtualHeight: number
 }
 
+/**
+ * Default virtual screen size used on mobile platforms, and the size 16:9
+ * virtual screens are overridden to on mobile (phone screens are much wider
+ * than 16:9, so a 16:9 virtual canvas would letterbox the UI).
+ */
+const DEFAULT_MOBILE_VIRTUAL_SIZE: UiRendererOptions = { virtualWidth: 1600, virtualHeight: 720 }
+
+/**
+ * Default virtual screen size used on non-mobile platforms.
+ */
+const DEFAULT_VIRTUAL_SIZE: UiRendererOptions = { virtualWidth: 1920, virtualHeight: 1080 }
+
+function isValidVirtualSize(options: UiRendererOptions | undefined): options is UiRendererOptions {
+  return !!options && options.virtualWidth > 0 && options.virtualHeight > 0
+}
+
+function is16by9(options: UiRendererOptions): boolean {
+  return options.virtualWidth * 9 === options.virtualHeight * 16
+}
+
 /**
  * @public
  */
@@ -36,6 +61,11 @@ export interface ReactBasedUiSystem {
   destroy(): void
   /**
    * Set the main UI renderer. Optional virtual size defines the global UI scale factor.
+   *
+   * When no virtual size is provided, a platform default is used: 1600x720 on
+   * mobile, 1920x1080 otherwise. Providing an invalid size (values \<= 0)
+   * disables the virtual screen (no UI scaling). On mobile, a provided 16:9
+   * virtual size is overridden to 1600x720 to fit phone screens.
    */
   setUiRenderer(ui: UiComponent, options?: UiRendererOptions): void
   /**
@@ -50,7 +80,8 @@ export interface ReactBasedUiSystem {
    * @param entity - The entity to associate with this UI renderer. When the entity is removed,
    *                 the UI renderer is automatically cleaned up.
    * @param ui - The UI component to render
-   * @param options - Optional virtual size used for UI scale factor when main UI has none
+   * @param options - Optional virtual size used for UI scale factor when main UI has none.
+   *                  Defaults and the mobile 16:9 override behave as in {@link ReactBasedUiSystem.setUiRenderer}.
    */
   addUiRenderer(entity: Entity, ui: UiComponent, options?: UiRendererOptions): void
   /**
@@ -78,6 +109,12 @@ export function createReactBasedUiSystem(engine: IEngine, pointerSystem: Pointer
   // Unique owner for the interactable area module variable.
   const interactableAreaOwner = Symbol('react-ecs-interactable-area')
 
+  // Last 16:9 size we already logged the mobile override for, so the log
+  // fires once per provided size instead of every tick. Tracked as raw numbers
+  // to avoid allocating a comparison string every tick.
+  let loggedMobileOverrideW = 0
+  let loggedMobileOverrideH = 0
+
   function getActiveVirtualSize(): UiRendererOptions | undefined {
     // Main renderer options win; otherwise use the first additional renderer option.
     if (virtualSize) return virtualSize
@@ -87,6 +124,40 @@ export function createReactBasedUiSystem(engine: IEngine, pointerSystem: Pointer
     return undefined
   }
 
+  /**
+   * Resolves the virtual screen to scale the UI against, or `undefined` when
+   * the virtual screen is disabled.
+   */
+  function resolveVirtualSize(): UiRendererOptions | undefined {
+    const provided = getActiveVirtualSize()
+    const mobile = isMobile()
+
+    // No creator-provided size: fall back to the platform default.
+    if (!provided) {
+      return mobile ? DEFAULT_MOBILE_VIRTUAL_SIZE : DEFAULT_VIRTUAL_SIZE
+    }
+
+    // An explicitly provided but invalid size (values <= 0) disables the
+    // virtual screen — no UI scaling at all.
+    if (!isValidVirtualSize(provided)) {
+      return undefined
+    }
+
+    // On mobile, 16:9 virtual screens don't fit phone aspect ratios — override them.
+    if (mobile && is16by9(provided)) {
+      if (loggedMobileOverrideW !== provided.virtualWidth || loggedMobileOverrideH !== provided.virtualHeight) {
+        loggedMobileOverrideW = provided.virtualWidth
+        loggedMobileOverrideH = provided.virtualHeight
+        console.log(
+          `Mobile platform detected: overriding 16:9 virtual screen size ${provided.virtualWidth}x${provided.virtualHeight} with ${DEFAULT_MOBILE_VIRTUAL_SIZE.virtualWidth}x${DEFAULT_MOBILE_VIRTUAL_SIZE.virtualHeight}`
+        )
+      }
+      return DEFAULT_MOBILE_VIRTUAL_SIZE
+    }
+
+    return provided
+  }
+
   function ReactBasedUiSystem() {
     const components: React.ReactNode[] = []
 
@@ -133,18 +204,25 @@ export function createReactBasedUiSystem(engine: IEngine, pointerSystem: Pointer
       setInteractableArea(canvasInfo.interactableArea, interactableAreaOwner)
     }
 
-    const activeVirtualSize = getActiveVirtualSize()
-    if (!activeVirtualSize) {
+    // The virtual screen (provided or defaulted) only applies while some
+    // renderer is registered; with no UI at all the scale factor is released.
+    if (uiComponent === undefined && additionalRenderers.size === 0) {
       // Reset only if this system owns the scale factor.
       resetUiScaleFactor(uiScaleFactorOwner)
       return
     }
 
+    const activeVirtualSize = resolveVirtualSize()
+    if (!activeVirtualSize) {
+      // Virtual screen explicitly disabled by an invalid provided size.
+      resetUiScaleFactor(uiScaleFactorOwner)
+      return
+    }
+
     if (!canvasInfo) return
 
     const { width, height, devicePixelRatio } = canvasInfo
     const { virtualWidth, virtualHeight } = activeVirtualSize
-    if (!virtualWidth || !virtualHeight) return
 
     // Normalize by devicePixelRatio so virtual px map to logical px (matching the
     // vw/vh path); without it the scale was inflated on high-dpr mobile screens.

packages/@dcl/sdk/src/react-ecs.ts

@@ -18,5 +18,12 @@
  */
 
 import ReactEcs from '@dcl/react-ecs'
+import { setIsMobileProvider } from '@dcl/react-ecs/dist/platform'
+import { isMobile } from './platform'
+
+// react-ecs cannot reach ~system/Runtime itself, so the platform check used
+// for virtual screen size defaults is injected here.
+setIsMobileProvider(isMobile)
+
 export * from '@dcl/react-ecs'
 export default ReactEcs