We'll start by laying down the basic principle behind the game's creation, and a summary of its rules.

Supercargo is a mobile port of a popular puzzle game, wherein the player controls an onscreen avatar that can move in the four cardinal directions. The avatar's progress is blocked by walls that completely bound the area and create shapes inside that boundary. There are boxes distributed throughout the area, and if the player attempts to move their avatar onto one box, it will push the box if there is an empty space across the box from the player's avatar. Boxes cannot be pulled or slid across the avatar's direction of motion. There are a number of goal spaces throughout the game area, equal to the number of boxes; when each box is placed on a goal area and each goal area is occupied by a box, the level is complete. Players' completion of a level is scored according to the number of distinct steps taken by their character to achieve a solution, with lower scores being more highly rated.

This is the fundamental design summary. It summarizes the core rules of Sokoban: there is one player who can move in the four major directions; the player can push boxes if there is room, but not pull them; there are goal spaces to take the boxes to, with one for each box, although any box can go on any goal. It tells us that there are two major kinds of features that don't move (walls and goals) and two kinds of features that do move (the player and boxes). We'll use this strategy when designing the game internals, to separate the map into a moving layer and a non-moving layer.

This section also explains the win condition; for each box in the "moving" layer, there is a goal at the same point in the non-moving layer, and vice versa. We'll need this in the fifth task, Making the game playable, to recognize wins.

This also says that we'll need to keep track of the number of moves, to determine how good the solution was. We're only going to count moves that change the board (move a box) and not every step the player takes moving into position.

Let's go into more detail about how the user will use the device to control the game.

To receive player input on mobile platforms, input of desired directions of movement will be accomplished by tapping near that edge of the screen. In exploring possible solutions, undo is a critical feature, so undoing the last move that pushed a box will be possible by shaking the device. A counter in the corner of the screen will indicate how many moves the player has taken to reach the displayed game state. If the screen has not been touched for several seconds, the display fades until the next touch to allow for unimpeded contemplation.

This describes the various mechanisms that the user will use to interact with the game. It tells us that we need to be able to recognize taps on different areas of the screen, but not on specific objects, which will be important for the interface layer. It says that we have to recognize shakes of the device, and that we have to be able to back up to the condition before certain steps.

It also describes the informative features of the interface (very minimal in this game) and a feature to make the game feel more responsive. However, this feature will be entirely contained in the interface; the core game does not need to know whether the move count is visible to the user, it only needs to know what the move count is.

Next, we specify the requirement we discussed at the beginning of the project, to save progress.

To facilitate preserving progress across multiple sessions, the game will save a move list and update it for each move added. When the user opens a level for which a move history is in progress, the program will ask them whether they wish to resume or discard that game. Completing a level discards its accumulated history.

Some of this was implied by the need to undo, but we'll need a persistent move history, one that we can reload if the game is run again later. This also explains what will happen if a level was not completed when the game was interrupted. This is the core design goal of this project, but because the rest of the game needs to be completed first, it will wait for the last task.

The format is well established, but let's confirm that we subscribe to the same definition.

Levels will be loaded from text files in a format standard for this type of puzzle game. Each line of a text file represents one row of the grid on which the game is played, where a # character indicates a square filled with a wall, a . (period) character indicates a goal space for a box, a $ indicates a box not on a goal space, a * character indicates a box initially positioned on a goal space, a space character denotes blank floor, an @ character indicates the player's starting avatar position on plain floor, and a + character indicates the avatar's starting position on a goal space. A level can contain exactly one @ or + character, and the number of $ characters should equal the total number of . and + characters.

This is a common text format used to store Sokoban levels, referred to as a .sok file. For this reason, the module that will translate portions of the files into in-memory representations of playable levels will be called sok.lua. This guideline also tells us that there can be single spaces in the level description (* and +) that affect both the static portion of the level (goal spaces) and the movable part (player or boxes). This will inform the method we'll use to process the file in task two, Loading a level from a file.

A single text file can contain multiple levels. A level consists of all consecutive lines that contain only characters recognized as part of the level format ( [#$.+*@ ] ). The convention is that each level will be preceded by a line containing its sequence number in the file, and followed by a tilde ( ~ ).

This also tells us about the level data format. We'll need to know which level is desired when loading from a file. We'll also need to be prepared to parse through multiple levels and keep track of which one we're processing.

Now that we understand the written design and some of its ramifications, we'll outline what components are needed and what events they'll use to communicate.

The major components will be Game and Shell. These represent two distinct modes, and the app will only be in one at any given time. For this reason, and because they each have distinct displays and modes of interaction, they will be represented by two different storyboard scenes in Corona as follows: