Nonoku - Creating a Background

So, I was getting bored of looking at a grey background and, as a break from cleaning up, refactoring, and adding the fiddly (nut necessary) UI code, I decided to run up a quick background.

The original version of Nonoku had a vertical gradient fill, light to dark, with subtle diagonal striping. I liked this so decided to reproduce it. However, it made sense to me to implement this in code. Since I’m using SpriteKit already, rendering to an SKEffectNode which rasterises the nodes made sense (the background is not animated so I can basically update once and be done).

There’s no native way, as far as I’m aware, to draw a gradient on a node, so the first thing would be to create an SKTexture. Again, since this is a one time deal, I’m not too worried. I’ve done something similar before so I already knew I could use a CIFilter to generate this. From that, I can get a CIImage. That can be passed to a CIContext to create a CGImage which can finally be passed to the SKTexture which I’ll pass into an SKSprite.

From reviewing the CIFilter documentation, I can get a list of available filters as follows: 

class func filterNames(inCategory category: String?) -> [String]

Even better, under the list of category constants, there is kCICategoryGradient. For this kind of quick exploratory code, I usually start a Swift Playground to spike out the things I don’t know.

So, skipping a step, I have this:

print("\(CIFilter.filterNames(inCategory: kCICategoryGradient))")
let filter = CIFilter(name: "CILinearGradient")
print("\(filter?.attributes)")

The list of filterNames has a couple of likely contenders, CILinearGradient and CISmoothLinearGradient. They take the same attributes (two colours, and two vectors) so I ended up trying both. In my use case I couldn’t see any difference between the two so decided to stick with CILinearGradient. If it ever comes up as an issue, it’s a very simple change to make.

CIFilter.attributes() gives me a list of the supported attributes, and a brief description of them. That's enough to define how I'm going to use it so I can leave the playground and come back to my code.

Since I want to create a new SKTexture with this gradient it makes sense to do it as an extension on SKTexture. I need the size, the start colour, and the end colour. I could add additional logic here but, following YAGNI (You Ain’t Gonna Need It), I am only interested in a vertical gradient so that’s all I’ll support.

extension SKTexture {
    convenience init?(size: CGSize, color1: SKColor, color2: SKColor) {
        guard let filter = CIFilter(name: "CILinearGradient") else {
            return nil
        }
        let startVector = CIVector(x: 0, y: size.height)
        let endVector = CIVector(x: 0, y: 0)
        filter.setValue(startVector, forKey: "inputPoint0")
        filter.setValue(endVector, forKey: "inputPoint1")
        filter.setValue(CIColor(color: color1), forKey: "inputColor0")
        filter.setValue(CIColor(color: color2), forKey: "inputColor1")

        let context = CIContext(options: nil)
        let rect = CGRect(x: 0, y: 0, width: size.width, height: size.height)
        guard let filterImage = filter.outputImage,
            let image = context.createCGImage(filterImage, from: rect) else {
            return nil
        }

        self.init(cgImage: image)
    }
}

Interestingly, whilst I can just get a ciColor from a UIColor (SKColor aliases UIColor), I can’t use it in the CIFilter due to the following issue.

*** -CIColor not defined for the UIColor UIExtendedSRGBColorSpace 0.666667 0.223529 0.223529 1; need to first convert colorspace.

Instead, I had to create a new instance of CIColor with the UIColor. I’m not sure if there are any issues associated with this, but it’s working fine for me so far.

From there, I just created an SKSpriteNode with the generated texture. The lines were just stroked SKShapeNodes with a CGPath which just have a defined start and end point.

So here’s how it looks:

It’s still early so I’m not sure if this is the final version but it does make the game easier to play as it’s much easier to tell where the empty spaces are. Also, with this approach I can easily generate backgrounds with different colours so I hav…

It’s still early so I’m not sure if this is the final version but it does make the game easier to play as it’s much easier to tell where the empty spaces are. Also, with this approach I can easily generate backgrounds with different colours so I have a bunch of options.

Unit Testing - Mocking In Swift

Mocking is a useful tool when writing unit tests. Due to limitations in the current swift version, there aren’t any real mocking frameworks like the ones you see for Java and Obj-C. That said, there are work arounds. Here’s a quick one when you need a one-off:

Method to test:

func crossDissolve(toIdentifier identifier: StoryboardIdentifier) {
    let nextViewController = viewController(forIdentifier: identifier)
    nextViewController.modalPresentationStyle = .fullScreen
    nextViewController.modalTransitionStyle = .crossDissolve
    show(nextViewController, sender: self)
}

This just performs a simple cross-dissolve between two view controllers (the one it’s on to the new one).There are four things to validate:

  1. The UIViewController passed to show(_:sender:) is the one expect.
  2. The sender is correct
  3. That the presentation style is fullScreen
  4. The transition style is crossDissolve

Since it doesn’t return any values I’m going to have to capture them instead. The method under test is crossDissolve(…) so I don’t want to change that behaviour. Everything else is fair game though. In this case, if I intercept the call to show(…) I can capture the parameters passed and validate them.

Since this is a one-off I can nest a class inside my test and capture the values appropriately. Then I can fill in the test.

func testCrossDissolve() {
    class MockSut: UIViewController {
        var showViewController: UIViewController?
        var showSender: Any?
        override func show(_ vc: UIViewController, sender: Any?) {
            showViewController = vc
            showSender = sender
        }
    }
    let mockSut = MockSut()
    mockSut.crossDissolve(toIdentifier: .gameViewController)
    XCTAssertNotNil(mockSut.showViewController as? GameViewController)
    XCTAssertEqual(mockSut.showSender as? UIViewController, mockSut)
    XCTAssertEqual(mockSut.showViewController?.modalPresentationStyle, .fullScreen)
    XCTAssertEqual(mockSut.showViewController?.modalTransitionStyle, .crossDissolve)
}

So, we’re creating a subclass of UIViewController and overriding a method that is called by the method we are interested in testing. Then we can use assertions to complete our test.

Of course, this could get messy if we had a bunch of test cases which needed to handle overrides. In that case I’d move the MockSut class out of the function and into the parent class. If I needed it outside of this specific set of tests, I’d move it into its own class so it could be used in multiple places.

Cleaning Up The Code

So, looking back over the last code, I realised that I was overthinking it massively. The original reasoning behind it didn’t hold up, so I fixed it.

protocol NavigationProtocol {
    func viewController(forIdentifier identifier: StoryboardIdentifier) -> UIViewController
}

extension NavigationProtocol {
    private var storyboard: UIStoryboard {
        return UIStoryboard(name: "Main", bundle: nil)
    }

    func viewController(forIdentifier identifier: StoryboardIdentifier) -> UIViewController {
        return storyboard.instantiate(withIdentifier: identifier)
    }
}

Yep, that’s a bit smaller. Hooray.

Bonus - time for unit tests ;)

func testInstantiateViewController_Splash() {
        let viewController = sut.viewController(forIdentifier: .splashViewController)
        XCTAssertTrue(viewController is SplashViewController)
    }

    func testInstantiateViewController_MainMenu() {
        let viewController = sut.viewController(forIdentifier: .mainMenuViewController)
        XCTAssertTrue(viewController is MainMenuViewController)
    }

Swift Generics

After installing SwiftLint I was going through resolving the issues. Fortunately, I hadn’t too many problems, mostly because it’s still a small project.

Some longish lines did catch my attention though.

enum StoryboardIdentifier: String {
    case splashViewController
    case mainMenuViewController
    case levelSelectViewController
    case optionsViewController
    case gameViewController
}

fileprivate extension UIStoryboard {
    func instantiateAppViewController(withIdentifier identifier: StoryboardIdentifier) -> UIViewController {
        return instantiateViewController(withIdentifier: identifier.rawValue)
    }
}

fileprivate class NavigationAssistant {
    private static let mainStoryboard = UIStoryboard(name: "Main", bundle: nil)

    private static var splashViewController: SplashViewController {
        return (mainStoryboard.instantiateAppViewController(withIdentifier: .splashViewController) as? SplashViewController)!
    }

    private static var mainMenuViewController: MainMenuViewController {
        return (mainStoryboard.instantiateAppViewController(withIdentifier: .mainMenuViewController) as? MainMenuViewController)!
    }

    private static var levelSelectViewController: LevelSelectViewController {
        return (mainStoryboard.instantiateAppViewController(withIdentifier: .levelSelectViewController) as? LevelSelectViewController)!
    }

    private static var optionsViewController: OptionsViewController {
        return (mainStoryboard.instantiateAppViewController(withIdentifier: .optionsViewController) as? OptionsViewController)!
    }

    private static var gameViewController: GameViewController {
        return (mainStoryboard.instantiateAppViewController(withIdentifier: .gameViewController) as? GameViewController)!
    }

As often seems to happen, on revisiting I can see a way to improve it. First off, it's a little bit verbose in the naming. Changing instantiateAppViewController to just instantiate shortens everything up to get it well under the limit. AppViewController is superfluous, named only to stop a naming collision between the extension and the actual class, and ViewController for the thing it is returning. instantiate could possibly be improved upon but it's clear enough in context for the moment.

That’s minor stuff though. What really caught my eye is that I’m repeating the same code over and over. That cast is kind of messy since I’m kind of cheating SwiftLint there. Without that I had return mainStoryboard.instantiateAppViewController(withIdentifier: .splashViewController) as! SplashViewController which is marginally shorter but it’s not really the problem. What I don’t like is that it’s the same call each time with the only change being the Type I’m casting to. If, instead of casting back as a UIViewController, I was to cast back as the type I was expecting then that would save a bunch of repeated code.

I’ve used generics a bunch of times but I keep forgetting about them - at least when I’m first writing out the code. That’s not necessarily a bad thing since the current way works and I’ve come back to it eventually to clean things up. That’s partly my reasoning for writing this post though, to remember to use these things (appropriately).

So, modify the call which returns the UIViewController to return a generic. Easy:

fileprivate extension UIStoryboard {
    func instantiate<T>(withIdentifier identifier: StoryboardIdentifier) -> T {
        return (instantiateViewController(withIdentifier: identifier.rawValue) as? T)!
    }
}

Fairly straight forward, still have that ugly ‘cast to optional, force unwrap’ to appease SwiftLint. Wait a second, SwiftLint also has a rule about force unwrapping! Optional, but maybe there’s a better way.

guard let viewController = instantiateViewController(withIdentifier: identifier.rawValue) as? T else {
    fatalError("Could not instantiate viewController")
 }
return viewController

There we go. Now it’s explicit what the behaviour is meant to be. It’s a little more code but no-one scanning the code should be confused by the intent.

So the whole thing looks like this now. Much better. The repeated logic is now in a single place. I'm happier with how it looks and, whilst there might be more lines, it feels more compact. I think there are some other improvements that can be made but that goes outside the scope of this post.

enum StoryboardIdentifier: String {
    case splashViewController
    case mainMenuViewController
    case levelSelectViewController
    case optionsViewController
    case gameViewController
}

fileprivate extension UIStoryboard {
    func instantiate<T>(withIdentifier identifier: StoryboardIdentifier) -> T {
        guard let viewController = instantiateViewController(withIdentifier: identifier.rawValue) as? T else {
            fatalError("Could not instantiate viewController")
        }
        return viewController
    }
}

fileprivate class NavigationAssistant {
    private static let mainStoryboard = UIStoryboard(name: "Main", bundle: nil)

    private static var splashViewController: SplashViewController {
        return mainStoryboard.instantiate(withIdentifier: .splashViewController)
    }

    private static var mainMenuViewController: MainMenuViewController {
        return mainStoryboard.instantiate(withIdentifier: .mainMenuViewController)
    }

    private static var levelSelectViewController: LevelSelectViewController {
        return mainStoryboard.instantiate(withIdentifier: .levelSelectViewController)
    }

    private static var optionsViewController: OptionsViewController {
        return mainStoryboard.instantiate(withIdentifier: .optionsViewController)
    }

    private static var gameViewController: GameViewController {
        return mainStoryboard.instantiatZ(withIdentifier: .gameViewController)
    }

Acquisition: Live on the App Store

So I started with (not so) grand ambitions of walking through the process of reviving Acquisition. What actually happened was a few flurries of activity which eventually got it working again across all device sizes in a way that will hopefully hold up. The only real pain point in the end was fixing the iPad issues. Since I couldn't change from a universal app to an iPhone only one (intended as a temporary fix since resolving the iPhone issues was slightly easier and would ensure that everyone has a working version) I had to get it all working in one go.

The most important thing is that it's working properly, again (and has been for a couple of months now). So far, no crashes.

You can download it from the app store.

 

Acquisition: Bringing it back to life

The first game I launched on the App Store, targeting iOS 4.3... It still sells on occasion and I've found some problems with it. This is some early code so it'll be an interesting experiment to see just how difficult it is to resurrect to a working state. Let's see what we're working with...

2016-02-29 22:16:54.449 Acquisition[27180:2115785] *** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Application windows are expected to have a root view controller at the end of application launch'

Uh oh... That's an auspicious start. Let's get this show on the road. I've seen this error before so I know how to fix it. Just go into the AppDelegate and add the following line:

[self.window setRootViewController:viewController];

And we're in... ok - next.

... ok then

... ok then

Hmm, didn't know it was going to be this bad. Time to do some heavy duty cleaning.

Unity: Building a keypad - Redux

One of the more popular posts has been on creating a keypad. However, I hadn't really thought of it as a tutorial and just as an example of something I'd been messing with. It's time to address that.

The full project is available on Github: https://github.com/stepheng/UnityKeycodeExample

This is what we're going to end up with...

This is what we're going to end up with...

This differs from the previous version in that the UI runs in the world space. This is based on some pictures of touch screen based keypad door locks I've seen. So, the first step is to set up the scene.

Create an Empty Object at 0,0,0.

Add a Cube to the object and scale it to 1, 4/3, 0.1. Our keypad is going to have a 3:4 aspect ratio as our button layout will be 3x4. 

Create a new, dark, material, and apply it to the cube. Just create a New Material and change the Albedo colour to something close to black. Give it a smoothness of 0.75. This isn't required but will make the lights we're going to use to show the status of the keypad more visible.

Add a Canvas to the empty object. Position it at 0, 0, -0.0501.
Set the Render Mode to World Space.
Since we're rendering the UI in world space we need to set an appropriate size and scale. The Width and Height values are used for rendering the UI whilst the Scale is used for rendering it in the world. We're maintaining a 3:4 ratio for the Canvas so the values need to be a suitably scaled up version. I picked 900 and 1200 for my Canvas. Set the X and Y scales to be 1/Width (in my case, 1/900). You'll see that the Canvas will be scaled to the size of the Cube.

CanvasSettings.JPG

Add two new point lights to the Cube Set one to red, and one to green. These will be the indicators that the keypad is working. Set the light positions at -0.125, 0.5, -1.5, and 0.125, 0.5, -1.5.

Create a Button on the Canvas. We'll be resizing it in code later so the actual values we use here don't matter too much. Set an image for the button background. I made a 256x256 circle (filled white on transparent background) to get a higher quality image. If you don't want to use that, the Knob image that is included in Unity will work for test purposes.

Set the colour to #92B2FFFF and change the normal colour to #FFFFFF00, the highlighted colour to #F5F5F540, and the pressed colour to #FFFFFFFF. This will tint the image we're using as the background of the button to a light blue. We're making it transparent when the button isn't active, partially visible when the mouse hovers over it, and fully opaque when pressed. I also increased the Fade Duration to 0.25. Play around and find something you like.

Expand the Button in the object Hierarchy window so you can see the Text object. Set the colour to the same value you used as the image background (e.g. #92B2FFFF). You can change this if you want a different effect.

Drag the Button object into the Assets window to create it as a prefab. Delete the Button object from the Hierarchy.

Time to do some scripting. I'm assuming C# for these purposes.

Create a new script called Keypad and another called KeypadHandler.

Add Keypad to the Canvas, and KeypadHandler to the Cube.

In Keypad, declare an Interface for the keyboard.

internal interface IKeypadInterface {
    void KeypadSuccess(Keypad keypad);
    void KeypadFailure(Keypad keypad);
    void KeypadUpdated(Keypad keypad);
}

public class Keypad : MonoBehaviour {
  
}

We'll use this for communicating events that occur on the Keypad.

The next step is to build the keypad.

[RequireComponent(typeof(Canvas))]
public class Keypad : MonoBehaviour {
    Canvas parent;

    [SerializeField]
    Button buttonPrefab = null;

    [SerializeField]
    int columnCount = 3;

    [SerializeField]
    string[] buttonValues = { "X", "0", "OK", "1", "2", "3", "4", "5", "6", "7", "8", "9" };

    [SerializeField]
    int submitIndex = 2;

    [SerializeField]
    int cancelIndex = 0;

    [SerializeField]
    string keycode = "1234";

    [SerializeField]
    GameObject keypadHandler;
    IKeypadInterface keypadInterface;

    string internalKeypadValue = "";
    public string KeypadValue {
        get { return internalKeypadValue; }
    }

    // Use this for initialization
    void Start() {
        parent = GetComponent<Canvas>();
        keypadInterface = keypadHandler.GetComponent<IKeypadInterface>();

        BuildKeypad();
    }
}

There's a bunch of stuff here, but to break it down.

We're declaring some variables and using [SerializeField] to tell Unity to make them available in the inspector. This allows us to configure our keypad. buttonPrefab will be the prefab we created earlier. buttonValues is an array we use to label the buttons. submitIndex and cancelIndex are the index of the buttons which submit the code, or cancel it. the Canvas parent is a reference to the Canvas object our Button is in. We get that in the Start method. keypadHandler is the GameObject we added the KeypadHandler the script to, and keypadInterface is used to get the reference to the script class itself since Unity won't recognise the interface we declared in the inspector.

Add a new method, BuildKeypad, to generate the buttons.

    private void BuildKeypad() {
        // Get canvas size and correct for scaling
        RectTransform rectTransform = parent.GetComponent<RectTransform>();
        float parentWidth = rectTransform.rect.width * parent.scaleFactor;
        float parentHeight = rectTransform.rect.height * parent.scaleFactor;

        // Calculate button size
        float buttonSize = parentWidth / columnCount;
        // Minimum x position
        float buttonXStart = -(parentWidth - buttonSize) / 2;
        // Minimum y position
        float buttonYStart = -(parentHeight - buttonSize) / 2;
        Vector3 buttonPos = new Vector3(buttonXStart, buttonYStart, 0);
        for (int i = 0; i < buttonValues.Length; i++) {
            // Create new button from prefab
            Button button = Instantiate<Button>(buttonPrefab);
            // Add button to the Canvas
            button.transform.SetParent(transform, false);
            // Set button text
            button.GetComponentInChildren<Text>().text = buttonValues[i];
            // Set position of button
            button.GetComponentInChildren<RectTransform>().anchoredPosition = buttonPos;
            // Set size of button
            button.GetComponentInChildren<RectTransform>().sizeDelta = new Vector2(buttonSize, buttonSize);
            // Create a new primitive within the loop for the button, otherwise it will use the last value of i
            int buttonIndex = i;
            // Call ButtonPress with buttonIndex when a button is clicked
            button.onClick.AddListener(delegate { ButtonPress(buttonIndex); });
            // Increment x position
            buttonPos.x += buttonSize;
            // If we're at the far column, reset x and increment y
            if (i % columnCount == columnCount - 1) {
                buttonPos.x = buttonXStart;
                buttonPos.y += buttonSize;
            }
        }
    }

Not much to add that isn't in the comments. This assumes square buttons so you could have separate values for the width and height of the buttons. 

Lastly, add methods to handle button presses and validation of the keypad value.

    void ButtonPress(int buttonIndex) {
        if (buttonIndex == cancelIndex) {
            internalKeypadValue = "";
            keypadInterface.KeypadUpdated(this);
            return;
        } else if (buttonIndex == submitIndex) {
            ValidateKeypadValue();
            return;
        }

        string buttonValue = buttonValues[buttonIndex];
        internalKeypadValue += buttonValue;
        if (keypadInterface != null) {
            keypadInterface.KeypadUpdated(this);
        }
    }

    void ValidateKeypadValue() {
        if (internalKeypadValue.Equals(keycode)) {
            keypadInterface.KeypadSuccess(this);
        } else {
            keypadInterface.KeypadFailure(this);
        }
        internalKeypadValue = "";
    }

ButtonPress(int) will be called when a button is clicked on. If buttonIndex matches cancelIndex, we reset the value and call KeypadUpdated(Keypad). ValidateKeypadValue() will be called when OK is clicked. This will fire KeypadSuccess(Keypad), or KeypadFailure(Keypad), and reset the value. If neither are matched, we get the string value of the button from our buttonValues array and append it to the internalKeypadValue string.

Validating the value is just a simple string comparison. We can set the value we use for comparison directly in the Unity inspector window so our keypad can be re-used in multiple locations with different codes without any code changes. 

Open the KeypadHandler script. This one is much simpler.

public class KeypadHandler : MonoBehaviour, IKeypadInterface {

    [SerializeField]
    Light failLight = null, passLight = null;

    void Awake() {
        failLight.enabled = false;
        passLight.enabled = false;
    }

    public void KeypadSuccess(Keypad keypad) {
        passLight.enabled = true;
    }

    public void KeypadFailure(Keypad keypad) {
        failLight.enabled = true;
    }

    public void KeypadUpdated(Keypad keypad) {
        Debug.Log(keypad.KeypadValue);
        passLight.enabled = false;
        failLight.enabled = false;
    }
}

We set IKeypadInterface as an interface on this. Then declare the point lights we created earlier. In Awake, we turn the lights off by disabling them. Then we implement the methods declared in IKeypadInterface. On success, we enable passLight. On failure, we enable failLight. On a normal update (any keypress except 'OK') we turn the lights off.

Check everything builds. Fix any errors.

Now all we need is to hook everything up. Go back to Unity and select the Cube. If the scripts are compiling successfully you'll see Fail Light and Pass Light fields in the inspector under KeypadHandler script. Drag the appropriate point lights from the Hierarchy window to the fields (you can also click on the target icon to the right of the field and assign from that window).

Now, select the Canvas. Under the Keypad (Script) section you'll see our new fields. The only ones you need to set are Button Prefab (drag in the Button prefab we created earlier) and the Keypad Handler. Drag the Cube to the Keypad Handler field and we're done. 

Try entering a pass code (1234 by default), or try entering the wrong one and trying to submit it. Check that the lights are hooked up. If everything's working you should be finished. To take it further, implement a new handler for unlocking a door. This could even be, plausibly, expanded to provide a basic UI for more complicated controls (e.g. remote controlling items in the world, basic menu/dialog selection).

The full project is available on Github: https://github.com/stepheng/UnityKeycodeExample