Virtual Game Controller (VGC) makes it simple to create software-based controllers for games and other purposes, enabling you to easily control one iOS device with another (or multiple other devices, such as in the case of a tvOS game). The framework wraps Apple's GCController Framework API, making it easy to simulatenously support both your own software-based controllers and hardware-based controllers that conform to the MFi standard, with a single code base. The GCController API supports both reading the values of game controller elements directly (polling) as well as registering to be called when a value changes using a block-based handler. VGC operates the same way and supports all of the features of the GCController API for both software- and hardware-based controllers.
While VGC is typically used to have an iOS device act as a controller for another iOS or tvOS device, it can also be used where two iOS devices act as peers, with a shared game environment presented on each device. In that type of implementation, user inputs through on-screen controls flow through the framework and are processed by the handlers on both devices. VGC supports easy creation of custom element types, including images and Data types, so that game logic such as state can be coordinated between the two devices. This capability is perfect for table-top games with two players, including ARKit games where you want both players to see and act on a common game space.
Important: The framework comes with a rich set of sample apps for iOS, tvOS, and MacOS, including both SceneKit and SprikeKit examples. A considerable amount of documentation appears as comments in the iOS Peripheral and iOS Central sample projects, and using those two projects on seperate devices is the best place to start. Next, consider trying the SceneKitShipDemo, which really gives a feel for how the framework can enhance a game. If you have trouble getting the sample projects to work or any other questions, contact me at virtualgamecontroller@gmail.com.
VirtualGameController is a drop-in replacement for Apple's Game Controller framework, so it can be easily integrated into existing controller-based games.
VirtualGameController may be useful in the following cases:
Platform-specific framework projects are included in the workspace. A single framework file supports both Peripherals (software-based controllers) and Centrals (that is, your game).
import VirtualGameController
Note that you currently need to import GameController
as well.
See the instructions on the Wiki for utilizing Objective C. ``
Preliminary support is in place for CocoaPods.
In order to integrate using Carthage, add VGC to your Cartfile:
github "robreuss/VirtualGameController"
Then use platform-specific commands to create the build products that you need to add to your project:
carthage update --platform iOS
carthage update --platform OSX
carthage update --platform tvOS
carthage update --platform watchOS
The project includes a pair apps that implement most of the available framework features and settings, as well as providing a generally helpful test environment.
NOTE: You cannot run more than one app using simulators at one time because of IP address sharing. Run a Central or Peripheral in a simulator, and use hardware devices to interact.
The Peripheral_iOS
sample project provides a reference implementation of a software-based game controller. Once you have implemented VGC in your game (Central) you can use the Peripheral_iOS app to test it:
The Central_iOS
sample project provides a reference implementation of a Central (your game, to which Peripherals connect). It provides a straightforward way of testing your implementation of Peripherals:
Feel free to contact me with any questions either using LinkedIn or virtualgamecontroller@gmail.com.
VirtualGameController is a wrapper around Apple's Game Controller framework, and so working with hardware controllers with VGC is the same as it is with Apple's Game Controller framework. See the Game Integration section below and the sample projects for additional details.
The MIT License (MIT)
Copyright (c) [2018] [Rob Reuss]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.