Guides and Sample Code

Developer

Playground Book Format Reference

On This Page

Playground Book Package

With the playground book package format, you can create a document that includes features such as playground pages, live views containing iOS views, and animated cutscenes. Figure 1-1 shows a screenshot from Learn to Code 1.

Figure 1-1Learn to Code 1 image: ../Art/SP_learn_to_code_2x.png

Content Hierarchy

A playground book is a package—a type of document with a file and folder structure. The parts of a book package form a nested hierarchy of folders. At the top is the book, then the chapters, and finally the individual pages and their content. The books, chapters, and pages include manifest information and optional items shared between the book, chapter, or page. Figure 1-2 shows the general hierarchy of files and folders for the playground book package format.

Figure 1-2Package folder hierarchy image: ../Art/SP_package_format.pdf

The package format uses a combination of folder name extensions, specially named folders, and specially named files. Manifest files for a book, and for each chapter and page, contain configuration information such as the order of chapters or the name of a page.

Folder Name Extensions

The book package, chapters, and pages use folder name extensions to indicate their type. Table 1-1 describes the folder name extensions and lists their locations in the hierarchy.

Table 1-1Folder name extensions

Extension

Level

Description

.playgroundbook

Book

The top-level folder for the playground book

.playgroundchapter

Chapter

A chapter in the book

.playgroundpage

Page

An individual page containing a playground and an optional, always-on live view

.cutscenepage

Page

An individual page containing a cutscene

Folders in the Package Structure

The package structure consists of specially named folders with no folder name extensions. These folders contain the book, the chapters in the book, and the pages in each chapter. Table 1-2 describes the folders in the package structure and lists the containing folder for each.

Table 1-2Package structure folder names

Folder name

Containing folder

Description

Contents

The top-level .playgroundbook folder

Contains all the other files and folders for the playground book

Chapters

Contents

Contains all the chapter folders for the book

Pages

.playgroundchapter

Contains all the page folders for the chapter

Shared Code Folders

Shared code is stored in folders named Sources. The contents of the folders are shared by the level in the hierarchy at which they are defined and all levels below that. For example, code in the Sources folder at the book level is available to all chapters and pages, whereas code in the Sources folder at the chapter level is available to all pages in that chapter but not to any other chapter.

Table 1-3 describes the shared code folder names and lists their containing folders.

Table 1-3Shared code folder names

Folder name

Containing folders

Description

Sources

Contents

.playgroundchapter

.playgroundpage

A folder containing shared Swift code

Public and Private Resources Folders

Resources, such as images, sounds, and text files, are stored in specially named folders with no folder name extensions. Any resources that you want users to be able to access from the file picker or image picker go in a PublicResources folder. Any resources that you don’t want users to access, such as localization or hints files, go in a PrivateResources folder.

Like shared code folders, the contents of resource folders are shared by the level in the hierarchy at which they are defined and all levels below that. When page content references a resource by name, it consults the PublicResources and PrivateResources folders at the page, chapter, and book levels, resolving in the following ways:

  • If a page, chapter, or book has a resource with the same name in both the PublicResources and the PrivateResources folders, the resource in the PublicResources folder is used.

  • If a page has a resource with the same name as its containing chapter, or a chapter has a resource with the same name as its containing book, the resource associated with the higher level is used.

Table 1-3 describes the resources folder names and lists their containing folders.

Table 1-4Public and private resources folder names

Folder name

Containing folders

Description

PublicResources

Contents

.playgroundchapter

.playgroundpage

.cutscenepage

A folder containing public resources, such as images and text files

PrivateResources

Contents

.playgroundchapter

.playgroundpage

.cutscenepage

A folder containing private resources, such as images, text files, hints, and localization files

Localized Resources Folders

Localized resources are stored in folders named with a locale identifier and the .lproj folder name extension. For example, resources for English-speaking users go in en.lproj folders, and resources for French-speaking users go in fr.lproj folders.

Table 1-5 describes the folder name extension and lists its locations in the hierarchy.

Table 1-5Localized resources folder extensions

Extension

Containing folders

Description

.lproj

PublicResources

PrivateResources

A folder containing localized assets for the specified locale

Specially Named Files

Configuration information, playground contents, and the source code for always-on live views are in specially named files.

Table 1-6 describes the specially named files and lists their containing folders.

Table 1-6Specially named files

File name

Containing folders

Description

Manifest.plist

Contents

.playgroundchapter

.playgroundpage

.cutscenepage

A property list that defines the attributes for a book, chapter, or page

Contents.swift

.playgroundpage

A required file with the initial contents of the playground page

LiveView.swift

.playgroundpage

An optional file used to specify an always-on live view; the code in this file is executed when the page is opened

Creating Playground Books

You need to use both a Mac running Xcode and an iPad to create a playground book. The first step in development is creating a skeleton structure for the book. A simple approach is to start with an existing playground book, which you can get by downloading Starter.playgroundbook from the Apple developer website.

Any changes to a book, such as adding a new page, require modifying content files, manifest files, and the folder structure. Changes made to a book in Swift Playgrounds, such as entering code into an editable text field, do not change the underlying pages. The suggested workflow is:

  1. Make targeted changes to the book’s content and structure in Xcode

  2. Transfer the updated book into Swift Playgrounds using iCloud or AirDrop

  3. Open the updated book and test the changes

  4. Note any additional changes that are needed, and return to step 1