Skip to content
T1KTheOneKit

t1k:cocos:playable:layout

FieldValue
Moduleplayable
Version0.5.6
Efforthigh
Tools—

Keywords: ads, aspect ratio, cocos, layout, playable, responsive, safe area, UI

How to invoke

Section titled “How to invoke”
/t1k:cocos:playable:layout

ResponsiveLayoutService

Section titled “ResponsiveLayoutService”

Cocos Component singleton that detects device aspect ratio on load and on every canvas resize, categorizes it into NARROW/STANDARD/WIDE, fires ScreenResizedSignal via SignalBus, and provides helpers for adaptive node positioning and scaling. Attach to a persistent node in the scene (e.g. Canvas root). See also: t1k-cocos-playable-signalbus.

Import paths:

  • db://assets/PLAGameFoundation/layout/ResponsiveLayoutService

Details

Section titled “Details”

Integration Points

Section titled “Integration Points”
  • ScreenResizedSignal fires once on onLoad immediately after detection — subscribe before onLoad completes if you need the initial value, or read service.category directly in start().
  • Plays well with the parameter system: subscribe to ScreenResizedSignal in ParameterController to re-apply layout-sensitive parameter values when the device rotates or the browser is resized.
  • getSafeArea() returns zeros on web — safe to call unconditionally.
  • Only one ResponsiveLayoutService instance is allowed; a second onLoad call destroys the newer component.

Common Mistakes

Section titled “Common Mistakes”
  • Reading ResponsiveLayoutService.instance before the component’s onLoad has run — returns null. Always guard with a null check or access in start() / after a frame delay.
  • Calling adjustForAspectRatio without subscribing to ScreenResizedSignal — positions only set once and will not update if browser is resized.
  • Using scaleToFit on a node whose UITransform.contentSize is zero — method early-returns silently. Set contentSize explicitly.
  • ES2017 target: do not use optional chaining (?.) or nullish coalescing (??) in game code.

Gotchas

Section titled “Gotchas”
  • Cocos Widget aligns relative to parent at layout time — animating the parent breaks the widget unless alignFlags are reapplied per frame (or Widget.target is locked).
  • Safe-area inset on iOS in-app webview is not always reported — provide a manual fallback inset of 24px top, 12px bottom.