using System.Linq; using System.Runtime.InteropServices; using UnityEngine; using UnityEngine.InputSystem; using UnityEngine.InputSystem.Controls; using UnityEngine.InputSystem.Layouts; using UnityEngine.InputSystem.LowLevel; using UnityEngine.InputSystem.Utilities; #if UNITY_EDITOR using UnityEditor; #endif // The input system stores a chunk of memory for each device. What that // memory looks like we can determine ourselves. The easiest way is to just describe // it as a struct. // // Each chunk of memory is tagged with a "format" identifier in the form // of a "FourCC" (a 32-bit code comprised of four characters). Using // IInputStateTypeInfo we allow the system to get to the FourCC specific // to our struct. public struct CustomDeviceState : IInputStateTypeInfo { // We use "CUST" here as our custom format code. It can be anything really. // Should be sufficiently unique to identify our memory format, though. public FourCC format => new FourCC('C', 'U', 'S', 'T'); // Next we just define fields that store the state for our input device. // The only thing really interesting here is the [InputControl] attributes. // These automatically attach InputControls to the various memory bits that // we define. // // To get started, let's say that our device has a bitfield of buttons. Each // bit indicates whether a certain button is pressed or not. For the sake of // demonstration, let's say our device has 16 possible buttons. So, we define // a ushort field that contains the state of each possible button on the // device. // // On top of that, we need to tell the input system about each button. Both // what to call it and where to find it. The "name" property tells the input system // what to call the control; the "layout" property tells it what type of control // to create ("Button" in our case); and the "bit" property tells it which bit // in the bitfield corresponds to the button. // // We also tell the input system about "display names" here. These are names // that get displayed in the UI and such. [InputControl(name = "firstButton", layout = "Button", bit = 0, displayName = "First Button")] [InputControl(name = "secondButton", layout = "Button", bit = 1, displayName = "Second Button")] [InputControl(name = "thirdButton", layout = "Button", bit = 2, displayName = "Third Button")] public ushort buttons; // Let's say our device also has a stick. However, the stick isn't stored // simply as two floats but as two unsigned bytes with the midpoint of each // axis located at value 127. We can simply define two consecutive byte // fields to represent the stick and annotate them like so. // // First, let's introduce stick control itself. This one is simple. We don't // yet worry about X and Y individually as the stick as whole will itself read the // component values from those controls. // // We need to set "format" here too as InputControlLayout will otherwise try to // infer the memory format from the field. As we put this attribute on "X", that // would come out as "BYTE" -- which we don't want. So we set it to "VC2B" (a Vector2 // of bytes). [InputControl(name = "stick", format = "VC2B", layout = "Stick", displayName = "Main Stick")] // So that's what we need next. By default, both X and Y on "Stick" are floating-point // controls so here we need to individually configure them the way they work for our // stick. // // NOTE: We don't mention things as "layout" and such here. The reason is that we are // modifying a control already defined by "Stick". This means that we only need // to set the values that are different from what "Stick" stick itself already // configures. And since "Stick" configures both "X" and "Y" to be "Axis" controls, // we don't need to worry about that here. // // Using "format", we tell the controls how their data is stored. As bytes in our case // so we use "BYTE" (check the documentation for InputStateBlock for details on that). // // NOTE: We don't use "SBYT" (signed byte) here. Our values are not signed. They are // unsigned. It's just that our "resting" (i.e. mid) point is at 127 and not at 0. // // Also, we use "defaultState" to tell the system that in our case, setting the // memory to all zeroes will *NOT* result in a default value. Instead, if both x and y // are set to zero, the result will be Vector2(-1,-1). // // And then, using the various "normalize" parameters, we tell the input system how to // deal with the fact that our midpoint is located smack in the middle of our value range. // Using "normalize" (which is equivalent to "normalize=true") we instruct the control // to normalize values. Using "normalizeZero=0.5", we tell it that our midpoint is located // at 0.5 (AxisControl will convert the BYTE value to a [0..1] floating-point value with // 0=0 and 255=1) and that our lower limit is "normalizeMin=0" and our upper limit is // "normalizeMax=1". Put another way, it will map [0..1] to [-1..1]. // // Finally, we also set "offset" here as this is already set by StickControl.X and // StickControl.Y -- which we inherit. Note that because we're looking at child controls // of the stick, the offset is relative to the stick, not relative to the beginning // of the state struct. [InputControl(name = "stick/x", defaultState = 127, format = "BYTE", offset = 0, parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5")] public byte x; [InputControl(name = "stick/y", defaultState = 127, format = "BYTE", offset = 1, parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5")] // The stick up/down/left/right buttons automatically use the state set up for X // and Y but they have their own parameters. Thus we need to also sync them to // the parameter settings we need for our BYTE setup. // NOTE: This is a shortcoming in the current layout system that cannot yet correctly // merge parameters. Will be fixed in a future version. [InputControl(name = "stick/up", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp=2,clampMin=0,clampMax=1")] [InputControl(name = "stick/down", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp=2,clampMin=-1,clampMax=0,invert")] [InputControl(name = "stick/left", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp=2,clampMin=-1,clampMax=0,invert")] [InputControl(name = "stick/right", parameters = "normalize,normalizeMin=0,normalizeMax=1,normalizeZero=0.5,clamp=2,clampMin=0,clampMax=1")] public byte y; } // Now that we have the state struct all sorted out, we have a way to lay out the memory // for our device and we have a way to map InputControls to pieces of that memory. What // we're still missing, however, is a way to represent our device as a whole within the // input system. // // For that, we start with a class derived from InputDevice. We could also base this // on something like Mouse or Gamepad in case our device is an instance of one of those // specific types but for this demonstration, let's assume our device is nothing like // those devices (if we base our devices on those layouts, we have to correctly map the // controls we inherit from those devices). // // Other than deriving from InputDevice, there are two other noteworthy things here. // // For one, we want to ensure that the call to InputSystem.RegisterLayout happens as // part of startup. Doing so ensures that the layout is known to the input system and // thus appears in the control picker. So we use [InitializeOnLoad] and [RuntimeInitializeOnLoadMethod] // here to ensure initialization in both the editor and the player. // // Also, we use the [InputControlLayout] attribute here. This attribute is optional on // types that are used as layouts in the input system. In our case, we have to use it // to tell the input system about the state struct we are using to define the memory // layout we are using and the controls tied to it. #if UNITY_EDITOR [InitializeOnLoad] // Call static class constructor in editor. #endif [InputControlLayout(stateType = typeof(CustomDeviceState))] public class CustomDevice : InputDevice, IInputUpdateCallbackReceiver { // [InitializeOnLoad] will ensure this gets called on every domain (re)load // in the editor. #if UNITY_EDITOR static CustomDevice() { // Trigger our RegisterLayout code in the editor. Initialize(); } #endif // In the player, [RuntimeInitializeOnLoadMethod] will make sure our // initialization code gets called during startup. [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)] private static void Initialize() { // Register our device with the input system. We also register // a "device matcher" here. These are used when a device is discovered // by the input system. Each device is described by an InputDeviceDescription // and an InputDeviceMatcher can be used to match specific properties of such // a description. See the documentation of InputDeviceMatcher for more // details. // // NOTE: In case your device is more dynamic in nature and cannot have a single // static layout, there is also the possibility to build layouts on the fly. // Check out the API documentation for InputSystem.onFindLayoutForDevice and // for InputSystem.RegisterLayoutBuilder. InputSystem.RegisterLayout( matches: new InputDeviceMatcher() .WithInterface("Custom")); } // While our device is fully functional at this point, we can refine the API // for it a little bit. One thing we can do is expose the controls for our // device directly. While anyone can look up our controls using strings, exposing // the controls as properties makes it simpler to work with the device in script. public ButtonControl firstButton { get; protected set; } public ButtonControl secondButton { get; protected set; } public ButtonControl thirdButton { get; protected set; } public StickControl stick { get; protected set; } // FinishSetup is where our device setup is finalized. Here we can look up // the controls that have been created. protected override void FinishSetup() { base.FinishSetup(); firstButton = GetChildControl("firstButton"); secondButton = GetChildControl("secondButton"); thirdButton = GetChildControl("thirdButton"); stick = GetChildControl("stick"); } // We can also expose a '.current' getter equivalent to 'Gamepad.current'. // Whenever our device receives input, MakeCurrent() is called. So we can // simply update a '.current' getter based on that. public static CustomDevice current { get; private set; } public override void MakeCurrent() { base.MakeCurrent(); current = this; } // When one of our custom devices is removed, we want to make sure that if // it is the '.current' device, we null out '.current'. protected override void OnRemoved() { base.OnRemoved(); if (current == this) current = null; } // So, this is all great and nice. But we have one problem. No one is actually // creating an instance of our device yet. Which means that while we can bind // to controls on the device from actions all we want, at runtime we will never // actually receive input from our custom device. For that to happen, we need // to make sure that an instance of the device is created at some point. // // This one's a bit tricky. Because it really depends on how the device is // actually discovered in practice. In most real-world scenarios, there will be // some external API that notifies us when a device under its domain is added or // removed. In response, we would report a device being added (using // InputSystem.AddDevice(new InputDeviceDescription { ... }) or removed // (using DeviceRemoveEvent). // // In this demonstration, we don't have an external API to query. And we don't // really have another criteria by which to determine when a device of our custom // type should be added. // // So, let's fake it here. First, to create the device, we simply add a menu entry // in the editor. Means that in the player, this device will never be functional // but this serves as a demonstration only anyway. // // NOTE: Nothing of the following is necessary if you have a device that is // detected and sent input for by the Unity runtime itself, i.e. that is // picked up from the underlying platform APIs by Unity itself. In this // case, when your device is connected, Unity will automatically report an // InputDeviceDescription and all you have to do is make sure that the // InputDeviceMatcher you supply to RegisterLayout matches that description. // // Also, IInputUpdateCallbackReceiver and any other manual queuing of input // is unnecessary in that case as Unity will queue input for the device. #if UNITY_EDITOR [MenuItem("Tools/Custom Device Sample/Create Device")] private static void CreateDevice() { // This is the code that you would normally run at the point where // you discover devices of your custom type. InputSystem.AddDevice(new InputDeviceDescription { interfaceName = "Custom", product = "Sample Product" }); } // For completeness sake, let's also add code to remove one instance of our // custom device. Note that you can also manually remove the device from // the input debugger by right-clicking in and selecting "Remove Device". [MenuItem("Tools/Custom Device Sample/Remove Device")] private static void RemoveDevice() { var customDevice = InputSystem.devices.FirstOrDefault(x => x is CustomDevice); if (customDevice != null) InputSystem.RemoveDevice(customDevice); } #endif // So the other part we need is to actually feed input for the device. Notice // that we already have the IInputUpdateCallbackReceiver interface on our class. // What this does is to add an OnUpdate method that will automatically be called // by the input system whenever it updates (actually, it will be called *before* // it updates, i.e. from the same point that InputSystem.onBeforeUpdate triggers). // // Here, we can feed input to our devices. // // NOTE: We don't have to do this here. InputSystem.QueueEvent can be called from // anywhere, including from threads. So if, for example, you have a background // thread polling input from your device, that's where you can also queue // its input events. // // Again, we don't have actual input to read here. So we just make up some stuff // here for the sake of demonstration. We just poll the keyboard // // NOTE: We poll the keyboard here as part of our OnUpdate. Remember, however, // that we run our OnUpdate from onBeforeUpdate, i.e. from where keyboard // input has not yet been processed. This means that our input will always // be one frame late. Plus, because we are polling the keyboard state here // on a frame-to-frame basis, we may miss inputs on the keyboard. // // NOTE: One thing we could instead is to actually use OnScreenControls that // represent the controls of our device and then use that to generate // input from actual human interaction. public void OnUpdate() { var keyboard = Keyboard.current; if (keyboard == null) return; var state = new CustomDeviceState(); state.x = 127; state.y = 127; // WARNING: It may be tempting to simply store some state related to updates // directly on the device. For example, let's say we want scale the // vector from WASD to a certain length which can be adjusted with // the scroll wheel of the mouse. It seems natural to just store the // current strength as a private field on CustomDevice. // // This will *NOT* work correctly. *All* input state must be stored // under the domain of the input system. InputDevices themselves // cannot private store their own separate state. // // What you *can* do however, is simply add fields your state struct // (CustomDeviceState in our case) that contain the state you want // to keep. It is not necessary to expose these as InputControls if // you don't want to. // Map WASD to stick. var wPressed = keyboard.wKey.isPressed; var aPressed = keyboard.aKey.isPressed; var sPressed = keyboard.sKey.isPressed; var dPressed = keyboard.dKey.isPressed; if (aPressed) state.x -= 127; if (dPressed) state.x += 127; if (wPressed) state.y += 127; if (sPressed) state.y -= 127; // Map buttons to 1, 2, and 3. if (keyboard.digit1Key.isPressed) state.buttons |= 1 << 0; if (keyboard.digit2Key.isPressed) state.buttons |= 1 << 1; if (keyboard.digit3Key.isPressed) state.buttons |= 1 << 2; // Finally, queue the event. // NOTE: We are replacing the current device state wholesale here. An alternative // would be to use QueueDeltaStateEvent to replace only select memory contents. InputSystem.QueueStateEvent(this, state); } }