Gatillos adaptativos DualSense

Para qué sirve este sistema

Los gatillos adaptativos del mando DualSense son uno de los canales de feedback más expresivos disponibles para los desarrolladores de Unity, y también uno de los más tediosos de implementar. Leer la documentación del SDK de PS5, gestionar reports de salida HID sin formato y hacer seguimiento del estado por dispositivo para que las actualizaciones del gatillo nunca corrompan la vibración — nada de eso tiene cabida en el código del juego.

El sistema Feedback de Serenity incluye un canal de gatillo adaptativo dedicado que gestiona la capa HID en escritorio y estructura el camino hacia el SDK de PS5 en consola. El efecto se define una sola vez como dato, se llama a IFeedbackService.Play y el framework lo entrega al pad correcto.

El problema en Unity

Los gatillos adaptativos DualSense requieren escribir directamente en el report de salida HID USB del mando. En escritorio eso implica gestionar un búfer de salida compartido que también transporta los motores de vibración y los datos LED — actualizar el campo del gatillo sin cuidado borra el estado de vibración del fotograma anterior. En hardware PS5 la API es completamente diferente: scePadSetTriggerEffect con ScePadTriggerEffectParam, cabeceras SDK bajo licencia que no pueden viajar con el repositorio y un devkit para probar. Gestionar ambas rutas en el código del juego es una carga de mantenimiento.

Más allá de la capa de transporte, el modelo de efecto necesita ser accesible para los diseñadores. Posición de inicio, posición de fin, fuerza, lado del gatillo, modo y duración necesitan campos de inspector, validación de rango y una forma de combinarse con otras modalidades de feedback en el mismo asset. Construir todo eso desde cero en cada proyecto es duplicación que acaba siendo costosa.

Cómo lo aborda Serenity

Serenity modela el efecto como AdaptiveTriggerEffect con seis campos: AdaptiveTriggerSide (Left, Right o Both), AdaptiveTriggerMode (Off, Resistance o Weapon), StartPosition01, EndPosition01, Strength01, DurationSeconds y HaveExitTime. Todos los valores normalizados van de 0 a 1. El efecto se define en el inspector como AdaptiveTriggerEffectAuthoring dentro de un ScriptableObject FeedbackDefinition y se convierte al efecto puro en tiempo de ejecución.

En tiempo de ejecución, AdaptiveTriggerChannel recibe el efecto y lo delega a IAdaptiveTriggerBackend. En escritorio, la implementación registrada es PcHidAdaptiveTriggerBackend, que traduce el efecto y lo envía a través del DualSenseOutputWriter compartido — el mismo writer que gestiona el estado de vibración y LED, de modo que los tres canales nunca se sobreescriben entre sí. El backend por defecto es NullAdaptiveTriggerBackend (un no-op) hasta que se registra un backend real, lo que significa que las plataformas no compatibles simplemente no hacen nada sin necesidad de branches en el código del juego.

Cómo encaja en Serenity

La funcionalidad de gatillo adaptativo forma parte del sistema Feedback más amplio de Serenity. AdaptiveTriggerEffect y sus enums viven en el namespace Serenity.Feedback.Application.Effects — C# puro sin dependencias de Unity. AdaptiveTriggerChannel implementa IFeedbackChannel y reside en la capa de infraestructura junto a los canales de vibración, LED, screen shake y hit stop. La seam del backend IAdaptiveTriggerBackend separa el canal del transporte: PcHidAdaptiveTriggerBackend para USB HID en escritorio, Ps5SdkAdaptiveTriggerBackend como scaffold para builds UNITY_PS5 y NullAdaptiveTriggerBackend como no-op por defecto.

PcHidAdaptiveTriggerBackend mapea cada AdaptiveTriggerMode al efecto de gatillo DualSense correspondiente: Resistance aplica una fuerza continua desde la posición de inicio, Weapon añade un punto de ruptura entre las posiciones de inicio y fin, y Off limpia el efecto. Todas las escrituras pasan por DualSenseOutputWriter.TrySetTrigger, que mantiene la salida por dispositivo sincronizada para que el estado de vibración y LED nunca se corrompa. Cuando HaveExitTime es true, el canal programa una corrutina que resetea el gatillo tras DurationSeconds (en tiempo real); cuando HaveExitTime es false, el efecto persiste hasta que otro efecto — normalmente uno en modo Off — lo sobreescribe.

Flujo de trabajo práctico

1. Crea un ScriptableObject FeedbackDefinition y añade una entrada AdaptiveTriggerEffectAuthoring a su lista de efectos.
2. Configura Side (Left, Right o Both), Mode (Resistance o Weapon), StartPosition, EndPosition, Strength, DurationSeconds y si el efecto debe auto-resetearse mediante HaveExitTime.
3. Registra el FeedbackDefinition en el servicio de feedback a través de la pipeline de inicialización.
4. Reproduce el efecto en tiempo de ejecución llamando a IFeedbackService.Play("tu-id") o enviando una PlayFeedbackSignal desde cualquier sistema o elemento de UI.
5. Para dirigirse al pad de un jugador específico, pasa un FeedbackTarget con alcance al índice de ese jugador o al acting pad — el canal resuelve el dispositivo DualSense correcto automáticamente.
6. Para detener un efecto persistente activo antes de su salida natural, llama a IFeedbackService.Stop("tu-id") o reproduce un efecto en modo Off en el mismo lado.

Qué incluye

• AdaptiveTriggerEffect con AdaptiveTriggerSide (Left/Right/Both) y AdaptiveTriggerMode (Off/Resistance/Weapon)
• Campos normalizados 0–1 para StartPosition01, EndPosition01 y Strength01, escalados por la intensidad global de feedback
• Auto-reset temporizado mediante HaveExitTime y DurationSeconds, o modo persistente hasta ser sobreescrito
• PcHidAdaptiveTriggerBackend gestiona DualSense sobre USB HID en escritorio y en el editor de Unity
• El DualSenseOutputWriter compartido garantiza que las actualizaciones de gatillo nunca corrompan el estado de vibración o LED en el mismo report de salida
• NullAdaptiveTriggerBackend por defecto mantiene en silencio las plataformas no compatibles sin ningún branch en el código del juego
• Scaffold Ps5SdkAdaptiveTriggerBackend para builds UNITY_PS5, listo para completar en devkit
• AdaptiveTriggerEffectAuthoring para la definición en el inspector dentro de ScriptableObjects FeedbackDefinition

Cuándo usarlo

• Juegos dirigidos a PS5 o DualSense en PC que quieran resistencia de disparo, tensión de arco o fricción de superficie a través de los gatillos adaptativos.
• Proyectos que ya usan el sistema Feedback de Serenity para vibración, LED o screen shake y quieren añadir gatillos adaptativos sin una integración HID separada.
• Equipos que quieren que los diseñadores definan los efectos de gatillo como datos en lugar de programar reports de salida de mando a mano.
• Bases de código que necesitan que la misma llamada de feedback funcione en DualSense, DualShock 4 y otros mandos — el backend null gestiona los dispositivos no DualSense en silencio.

Sistemas relacionados

• Rumble de Gamepad e Iluminación de Mando Un único servicio de feedback que controla el rumble de doble motor, el color del lightbar LED y la vibración HD del Switch Pro en PS5, PS4, Nintendo Switch Pro y mandos genéricos.
• Screen Shake, Hit Stop y Screen Flash Screen shake, camera shake, UI shake, hit stop y flash de pantalla completa — todo creado en un FeedbackDefinition y disparado con una única llamada al servicio.
• Integración del Input System Un gateway de player input que encamina las acciones del Input System de Unity a menús, gameplay y navegación de UI a través de servicios limpios.
• Sistema de Game Mode Transiciones de estado de juego tipadas con señales, estrategias de pausa y una puerta de disponibilidad a la que otros sistemas pueden suscribirse.