Custom Mappings

Sample Projects

Exploring any one of the sample projects is a good way to understand how custom mappings work.

Why Custom Mappings?

Custom mappings provide the ability to map one control onto another, so they both fire at the same time. Mutal mapping is supported so that mapping works in both directions, making the controls have the same game impact.

Defining Your Custom Mappings

Custom mappings are defined in a class that descends from CustomMappingsSuperclass. The recommended file name is VgcCustomMappings.swift and the recommended class name is CustomMappings.

Here is the custom mappings file from the sample projects - explanations contained in in-line comments:

import Foundation
import VirtualGameController

public class CustomMappings: CustomMappingsSuperclass {
    
    public override init() {
        
        super.init()
        
        ///
        /// CUSTOMIZE HERE
        ///
        /// Use this data structure to map one control element onto another, which means that
        /// both will fire at the same time.
        
        /// Mapping can be performed on either the peripheral side or the central side.
        /// Obviously, central-side mapping is more performant from a network utilization
        /// perspective.  Peripheral-side mapping is more efficient in terms of how it is
        /// performed, but has the  disadvantage of not supporting hardware control mapping,
        /// which central-side mapping does.


        self.mappings = [
            ElementType.RightThumbstickXAxis.rawValue:  ElementType.DpadXAxis.rawValue,
            ElementType.RightThumbstickYAxis.rawValue:  ElementType.DpadYAxis.rawValue,
        ]

    }

By-directional Mapping

Elements can be setup to map mutally, so that if either element fires, they both fire:

self.mappings = [
    ElementType.RightThumbstickXAxis.rawValue:  ElementType.DpadXAxis.rawValue,
    ElementType.DpadXAxis.rawValue:  ElementType.RightThumbstickXAxis.rawValue,
]

Initializing Your Custom Mappings

Your custom mappings class must be passed into the startAs used to initialize VirtualGameController functionality in your app, and it must be done for each of the app roles (Peripheral, Central and Bridge) that you have in use:

 VgcManager.startAs(.Central, appIdentifier: "vgc", customElements: CustomElements(), customMappings: CustomMappings())

Note that when this method is used for start-up, you cannot pass nil to customElements, and so you should include a customElements class without any mappings, as described here.

Peripheral Side Versus Central Side Mappings

Although mapping is supported on both the Peripheral and the Bridge/Central, it is recommended that mapping be done on the Central since it prevents the need to send double values.

Control of which style of mapping is used is here, and the default is false:

VgcManager.usePeripheralSideMapping = true

If You Don't Need Custom Mappings

You can pass a customMappings() with no mappings defined to startAs.