Adding Cutscenes to your Swift Playground Books
Whilst working on my WWDC 17 Scholarship playground, I decided that I wanted to arrange my submission in the form of a playground book with a cutscene at the beginning.
If you have ever had the chance to try Apple’s ‘Learn to Code’ books within the Swift Playgrounds App for iPad then I’m sure you’ll agree with me in saying that the cutscenes are beautifully animated. I wanted to achieve similar quality in my submission. However, cutscenes aren’t documented too well at the moment so I had to do a bit of digging myself to figure out how they work.
With that in mind and for the benefit of my fellow WWDC 17 scholarship applicants/future authors of playground books, I wanted to write this post to demonstrate the best way, that I have found, of creating good looking, animated cutscenes within your project.
Once you have setup your playground books structure and the location of the cutscene folders ,as documented by Apple in the playground book format guide, you can generate attractive, animated HTML, CSS and JS using Tumult Hype. This is the tool that Apple has used to create the cutscenes in the ‘Learn to Code’ books. This tool also has a 14 day free-trial which suits us scholarship applicants nicely! 😉
Creating a Cutscene using Hype 🎞
With Hype 3 installed, you can begin creating cutscenes. I found this tool very intuitive when first using it and there is a fantastic introduction video available which shows you how to animate text, images etc. It’s incredibly easy to get something good looking.
To demonstate the basics of what you can do I have created a basic one page scene which animates text moving in from the top with an elastic timing function.
In addition to single animated scenes, hype allows you to add multiple scenes and link them together. You can add additional scenes on the left and then insert buttons using the ‘Elements’ drop-down on the top bar. In order to get the scenes to move back and forth between each other you need to assign the appropriate actions to each button.
You can see above that I have added an additional scene and placed buttons in each corner to allow the user to navigate back and forth through my short cutscene. Take particular notice of the actions panel on the right which is setup appropriately for the ‘previous’ button — when the user taps the button it jumps to the previous scene. Button actions should be fairly self-explanatory and as with most of the features of Hype, they are well documented so head to the documentation if you have any issues. 🙃 You can test the functionality of your cutscene navigation in Safari by clicking the icon in the top bar of Hype. Doing this will give you an idea of how your cutscene will appear in and work in Swift Playgrounds
Before we export the cutscene and set it up in our playground book there is one thing to fix… At the moment the next button on our last scene doesn’t lead anywhere. Since there are no further scenes for the user to view we want to return them to the next page in our playground book. To do this, add a new action to the ‘Next’ button on our final scene. The action should be set to ‘Go to URL…’ with ‘@next’ as the URL.
If you test this button in Safari, like we have done before with the other navigation buttons, it will not work. This is to be expected though as the ‘@next’ link will only work when the cutscene is running in Swift Playgrounds.
The cutscene we have created can now be exported from Hype. To do this, go to File > Export as HTML 5 > Folder… Name the export appropraitely (eg. lower camel case, no spaces) as you will have to reference it again in Xcode later. Once you have exported from Hype, you will be left with an HTML file and a .hyperesources folder. These two files should be moved to the ‘Resources’ folder within the appropriate .cutscenepage folder in your Playground Book.
All that’s left to do now is to update the Manifest.plist file in our .cutscenepage folder to reference the HTML file that was generated by Hype. Ensure that the Manifest.plist file in the Chapter file is also updated to include the new Playground Cutscene page folder.
Having completed these steps, the animated cutscene you created in Hype should now display nicely in the Swift Playgrounds App when you transfer your playground over to the app.
Summary
Of course you don’t have to use Hype 3 to create your cutscenes, you can code them yourself but using Hype is certainly the best way that I have found for swiftly (sorry) creating animated cutscenes and it seems to be used by Apple too, so that must count for something. 😇
I hope this post helps some future playground authors as well as my fellow WWDC applicants. I’m not usually one for writing tutorial style blog posts or even blog posts at all for that matter so I’ve tried to explain things as well as I can. If you have any issues or don’t understand a section in this post, please do comment below or contact me on Twitter and I’ll try to help the best I can. ☺️
Special thanks to @kabiroberai for informing me of the ‘@next’ URL when working with cutscenes.
