Skip to content

t1k:cocos:playable:input-service

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: gesture, input, InputService, raycasting, touch

/t1k:cocos:playable:input-service

Cocos Component attached to a scene node. Listens to global input events and fires typed signals via SignalBus. See t1k-cocos-playable-signalbus for subscription patterns.

  • InputService — Cocos Component (attach to scene node), registers TOUCH_START/MOVE/END handlers in onLoad
  • InputSignals — Plain TS classes emitted via SignalBus; no constructor needed for FirstInteractionSignal
  • InputServiceConfig — Optional config overrides passed to configure()

Default thresholds: swipeThreshold=50px, swipeVelocityThreshold=300px/s, tapMaxDuration=300ms, tapMaxDistance=10px

SignalPayloadFires when
TouchStartSignalworldPosition, uiPositionfinger touches screen
TouchEndSignalworldPosition, uiPositionfinger lifts
TapSignalworldPosition, uiPositionduration < 300ms AND distance < 10px
SwipeSignal`direction (‘up’‘down’
DragSignalworldPosition, uiPosition, deltaevery TOUCH_MOVE
FirstInteractionSignal—first ever touch (once per session)
RaycastHitSignalhitNode, hitPoint3D ray hits on TOUCH_START
RaycastMoveSignalhitNode, hitPoint3D ray hits on TOUCH_MOVE
RaycastEndSignalhitNode, hitPoint3D ray hits on TOUCH_END
// Runtime configuration (merge over defaults)
inputService.configure({ swipeThreshold: 80, tapMaxDuration: 200 });
// Provide explicit 2D camera for screen→world conversion
inputService.setMainCamera(camera2D);
// Enable 3D raycasting (auto-enables when set)
inputService.set3DCamera(camera3D);
// OR assign via @property in editor: inputService.camera3D = camera;
// Toggle all input processing
inputService.setEnabled(false);
// Raycast mask for filtering physics layers (default = all layers)
inputService.configure({ raycastMask: 1 << 3 }); // layer 3 only

Subscribe to tap anywhere:

SignalBus.instance.subscribe(TapSignal, (s) => {
console.log('tap at UI', s.uiPosition);
});

Detect first touch (BGM unlock):

// PlayableHelper already handles this — autoPlayMusicOnFirstTouch = true
// For custom logic:
SignalBus.instance.subscribe(FirstInteractionSignal, () => {
AudioService.instance.playMusic(Constant.AUDIO_NAME.BGM);
});

4-directional swipe:

SignalBus.instance.subscribe(SwipeSignal, (s) => {
if (s.direction === 'up') movePlayerUp();
});

3D object picking (drag):

// 1. Assign camera3D in editor @property or via set3DCamera()
// 2. Subscribe to raycast signals:
SignalBus.instance.subscribe(RaycastHitSignal, (s) => {
s.hitNode.getComponent(MyObject)?.onSelect();
});
SignalBus.instance.subscribe(RaycastMoveSignal, (s) => {
s.hitNode.setWorldPosition(s.hitPoint);
});

Screen-to-world conversion (internal): Uses camera.screenToWorld() auto-detected from Canvas if mainCamera not explicitly set.

PlayableHelper subscribes FirstInteractionSignal → plays BGM, and optionally subscribes TapSignal for redirect-after-N-clicks. Do not duplicate these subscriptions.

  • Attaching InputService to a node that gets destroyed early — use a persistent scene root node
  • Setting camera3D without enabling the PhysicsSystem in project settings (raycasts silently skip)
  • Forgetting to call setEnabled(false) during loading/cutscenes — tap/swipe signals still fire otherwise
  • Subscribing TapSignal when PlayableHelper.autoPlayMusicOnFirstTouch is true creates duplicate BGM play calls if you also subscribe FirstInteractionSignal
  • Global input.on(TOUCH_START) is served at a LOWER dispatch priority than node/UI listeners, and the chain BREAKS as soon as a node claims the touch (Cocos 3.8.x). The global listener runs via InputEventDispatcher at EventDispatcherPriority.GLOBAL (0); per-node/UI dispatch runs via PointerEventDispatcher at UI (1) (higher = earlier). Input._registerEventDispatcher sorts descending and _emitEvent stops the chain on the first dispatcher that returns false; PointerEventDispatcher.dispatchEventTouch returns false once any node claims the touch. So any first tap that lands on a node which owns a touch listener NEVER reaches the global listener — InputService’s FirstInteractionSignal does not fire when the player’s first tap lands on a button, so PlayableHelper’s first-touch BGM never starts and ClickToStoreHandler/MarketOptionsArbiter under-count taps. Because a playable ad’s screen is normally covered edge-to-edge in tappable buttons, this is the COMMON case, not an edge case — and it surfaces as an “audio bug” (button SFX plays, no BGM) rather than an input bug. Workarounds: (a) add a capture-phase DOM listener on game.canvas as a fallback source for the first-touch signal (also carries the browser’s user-activation gesture for audio unlock), or (b) make the signal source not depend solely on the global listener (UI-priority registration, or a preventSwallow-style opt-out inside @playablelabs/game-foundation’s InputService). Evidence: HotPotPLA, 2026-09-21, headless CDP.
  • Touch events on Cocos Web target document, not Canvas — adding a div over the canvas blocks input silently.
  • Gamepad polling is per-frame, not per-event — debounce in user code if you need event semantics.
  • Multi-touch pinches deliver two unsynchronised TouchMove events per frame — buffer before reacting.
  • EventTouch.getTouches() is UNRELIABLE for the still-active touch set on TOUCH_END (Cocos 3.8.x) — calling it on TOUCH_END to remove the ended touch from a multi-touch map can wipe a finger that is still down, corrupting a pinch or single-drag state machine. Correct pattern: on TOUCH_END remove only the single ended touch via event.touch.getID(); use event.getTouches() only to refresh positions during TOUCH_MOVE; clear the full tracked set on TOUCH_CANCEL. Evidence: TapInOut CameraInputController.ts; mirrors PLAGameFoundation CameraController.ts pattern.
  • Pinch-to-single-drag transition: re-seed drag origin from the SURVIVING touch — when one finger of a pinch lifts, do NOT use event.getLocation() (which is the ended finger’s position) to seed the single-drag start. Instead, read the surviving touch’s last known position from your own tracked map to avoid a spurious drag jump on the first TOUCH_MOVE after the lift.
  • Fix pattern for the swallowed first tap (see the engine-priority gotcha above): use a capture-phase DOM listener on window for pointerdown, with touchstart / mousedown fallbacks — the DOM gesture reaches the page before Cocos’ internal UI dispatcher can claim the touch. Make it idempotent and remove it after the first fire. This is the reliable “first interaction” source (audio unlock, BGM start) whenever the first tap can land on a cc.Button or a full-screen CTA, which is the common case for a playable ad.