Skip to content

README.md

Latest commit

 

History

History
61 lines (48 loc) · 3.33 KB

README.md

File metadata and controls

61 lines (48 loc) · 3.33 KB

VirtualTouchscreenZone

Create per-UI-zone virtual touch devices that mirror the real Touchscreen in the same frame. Each zone owns one VirtualTouchscreen (VTS) so you can pair different PlayerInputs to different screen regions. Works for one-device local multiplayer.

Why

Unity’s PlayerInputManager joins players when a device produces input. A single physical Touchscreen can’t be split by default. This component fabricates one VTS per zone and feeds it only the touches that began inside that zone. Control schemes can then target VirtualTouchscreen explicitly.

Features

  • VirtualTouchscreen layout identical to Touchscreen.
  • Zone hit-test on Began. Claimed finger is routed to that zone until End/Cancel.
  • Mirrors with source timestamps to keep order within the frame.
  • Optional auto-join via PlayerInputManager.JoinPlayer on first touch.
  • Throttle per frame and move epsilon to avoid queue overflow.
  • Verbose logging with origin tags (primary, /Touchscreen/touch0, etc.).

Setup

  1. Project: Edit → Project Settings → Player → Active Input Handling = Input System (New).
  2. Canvas: Add a RectTransform for each control zone.
  3. Add Component: VirtualTouchscreenZone to each zone object.
  4. Player prefab(s):
    • Use PlayerInput component.
    • In your Input Actions, add a control scheme that requires VirtualTouchscreen (not Touchscreen) if you want to force VTS.
  5. PlayerInputManager:
    • Place one in the scene.
    • Leave Join Behavior as you prefer. This script can auto-join on first Began.

Inspector fields

  • behaviorEnabled: Master on/off.
  • mirroringEnabled: Keep device but pause mirroring.
  • forceUsePrimaryTouch: Many simulators only update primaryTouch. Set true for reliability.
  • maxQueuedPerFrame: Per-zone event cap. Protects maxQueuedEventsPerUpdate.
  • moveEpsilonPixels: Suppress tiny Moved.
  • zoneRect: Zone bounds. Defaults to this RectTransform.
  • vtsLayoutName / deviceName: Layout stays VirtualTouchscreen. Name defaults to VirtualTouchscreen-<InstanceID>.
  • removeDeviceOnDisable: Clean up VTS on disable.
  • autoJoinOnPress: Join player on first Began inside this zone.
  • joinControlScheme: Optional scheme name to enforce.
  • joinOnlyIfUnpaired / joinOncePerZone: Join guards.
  • Logging toggles: Enable by instance or flip VirtualTouchscreenZone.GlobalLoggingEnabled = true.

Input Actions example

  • Aim (Value/Vector2, Pass Through): bind to <Pointer>/position processed by your composite (e.g., pointer drag diff).
  • Launch (Button): <Pointer>/press with Press(ReleaseOnly) so release triggers fire while you can still read last Aim.
  • Control scheme device requirement: VirtualTouchscreen.

Common pitfalls

  • Double sources: Turn off Mouse → Touch simulation and avoid EnhancedTouch while mirroring.
  • Queue overflow: If you see
    Maximum number of queued events exceeded… Current limit is '1000' then lower event noise or raise InputSystem.settings.maxQueuedEventsPerUpdate early: 
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]
static void RaiseQueueLimit() =>
    InputSystem.settings.maxQueuedEventsPerUpdate =
        Mathf.Max(InputSystem.settings.maxQueuedEventsPerUpdate, 10000);