Cheats

Cheats is an implementation of console-style cheat codes (such as the Konami code) for iOS apps. It includes a UIGestureRecognizer for recognizing cheat codes. Combine a sequence of actions consisting of swipes, shake gestures, taps and key presses to create a cheat code for unlocking features or Easter eggs in your app.

example

Features

  • [x] Combine a sequence of actions to make a cheat code for unlocking a feature or Easter egg in an iOS app.
  • [x] Provides a UIGestureRecognizer for ease of integration with UIViewController.
  • [x] Available for integration through Cocoapods, Carthage or Swift Package Manager.

Cheats

To learn more about how to use Cheats, take a look at the blog post or make use of the table of contents below:

Installation

Cocoapods

CocoaPods is a dependency manager which integrates dependencies into your Xcode workspace. To install it using RubyGems run:

gem install cocoapods

To install FeatureFlags using Cocoapods, simply add the following line to your Podfile:

pod "Cheats"

Then run the command:

pod install

For more information see here.

Carthage

Carthage is a dependency manager which produces a binary for manual integration into your project. It can be installed via Homebrew using the commands:

brew update
brew install carthage

In order to integrate Cheats into your project via Carthage, add the following line to your project's Cartfile:

github "rwbutler/Cheats"

From the macOS Terminal run carthage update --platform iOS to build the framework then drag Cheats.framework into your Xcode project.

For more information see here.

Swift Package Manager

The Swift Package Manager is a dependency manager for Swift modules and is included as part of the build system as of Swift 3.0. It is used to automate the download, compilation and linking of dependencies.

To include Cheats as a dependency within a Swift package, add the package to the dependencies entry in your Package.swift file as follows:

dependencies: [
    .package(url: "https://github.com/rwbutler/Cheats.git", from: "4.2.0")
]

Usage

Cheats consists of a core and UI component - only the core component is available through Swift Package Manager due to the dependency of the UI component on UIKit.

Making a Cheat Code

Creating a cheat code involves creating a sequence of actions that the user must perform correctly in order to unlock the cheat. Action may consist of swipes or key presses:

let actionSequence: [CheatCode.Action] = [.swipe(.up), .swipe(.down), .swipe(.left), .swipe(.right), .keyPress("a"), .keyPress("b")]

Once the sequence of actions has been defined, instantiate a Cheat and optionally provide a callback which will be invoked to feedback the user's progress as they complete the sequence of actions required to unlock the cheat:

let cheat = CheatCode(actions: actionSequence) { [weak self] cheatCode in
    switch cheatCode.state() {
        case .matched: // correct
            print("Cheat unlocked!")
        case .matching: // correct *so far*
            print("Further actions required to unlock cheat.")
        case .notMatched: // incorrect
            print("Cheat incorrect.") 
        case .reset: // initial state / sequence reset
            print("Cheat code sequence reset")      
}

As shown in the above code snippet, it is possible to query the state of the CheatCode at any time via the state() function on the CheatCode instance. The CheatCode.State enum is able to take on three states:

  • matched - indicates that the user has successfully completed the cheat code.
  • matching - indicates that the user has partially completed the cheat code with further actions required in order to successfully unlock the cheat.
  • notMatched - indicates that the user got one of the actions wrong whilst attempting the cheat code action sequence.
  • reset - indicates that the user has not yet begun to input the cheat code sequence or the sequence has been reset to its initial state.

Reset

Should the CheatCode enter the .notMatched state then the user cannot retry the cheat until reset() has been invoked to reset the user's sequence of actions. If using the CheatCodeGestureRecognizer (see below), this is performed automatically by the gesture recognizer.

Actions

Actions are the building blocks of cheat code sequences. Available actions are:

  • keyPress - For whenever a key on the keyboard is pressed.
  • shake - When the user shakes the device.
  • swipe - In the directions up, down, left and right.
  • tap - Specified with the number of taps required.

If at any time, the next action required to complete the cheat code sequence is needed, this can be retrieve using nextAction() which optionally returns a CheatCode.Action if any further actions are required in order to complete the sequence.

Likewise previousAction() will return the last action successfully completed by the user as part of the cheat code sequence.

Gesture Recognizers

Cheats provides the CheatCodeGestureRecognizer, a subclass of UIGestureRecognizer, to make integration with UIViewController / UIView straightforward.

To make use of the gesture recognizer, instantiate it with a CheatCode instance as described above along with the target and action selector (as you would with any other UIGestureRecognizer). Then simply add the gesture recognizer to the desired view:

let gestureRecognizer = CheatCodeGestureRecognizer(cheatCode: cheatCode, target: self, action: #selector(actionPerformed(_:)))
view.addGestureRecognizer(gestureRecognizer)

GitHub