On this web page I will walk you through the World Variables of Cocoaban, the parts (or Types), the code that I have established (and which we will all work to hone and improve), and the basics for creating a new level.

World Variables

Types

Rules

Creating Your Own Levels

Submitting Your Levels

The Cocoaban game was inspired by a Newton port of the Sokoban game. I figured, "Why not combine my two geeky passions (Newton and Cocoa) and create a Cocoa project?" The downloadable Cocoaban authoring kit, which is used on this page to illustrate how to take part in this Cocoa project, has two boards with the code necessary to move between board 1 and 2 as well as 2 and the incomplete board 3. Additionally, the Types needed for the game are included, as well as the sound effects used in the game.

The purpose of the game is to move the packages to the Goal area in each board. The Cocoaban character can push the packages from the left, right, above, and from below. He cannot pull a package toward him, though. It is possible to get a package stuck in an area on the board from which it is impossible to remove the package. Once all the packages are in the goal area, the game progresses to the next level.

World Variables

There is one World Variable that control the progress of the game: packages.

The packages variable keep track of how many packages have been moved into the goal area. Once the required amount of packages are in the Goal area, the game progresses to the next level.

When the game starts there is already one package in the Goal area, which is recorded in the packages variable.

See the Rules section for more information about how the boards change.

Types

Cocoaban comes with a collection of Types upon which we will base all subsequent levels.

Cocoaban is the main character in this game.

Package is the piece that one maneuvers through the board to the Goal area.

Wall is used to build the boards.

Goal is the area where one needs to move all the packages on the particular level.

Additionally, there are several Appearances for the Cocoaban Type:

 

These Appearances are used to give a sense of animation when the Cocoaban character moves a package. You can modify any of the Cocoaban appearances without affecting how the rules work.

Rules

There are several simple rules associated with several of the types. These rules make the game function. You should study how each of these rules work so you can create new levels that work with the existing rules.

Rules for Cocoaban Type

The Cocoaban type has rules that govern his movement and his appearance when he is moving a package. There are many rules that affect the Cocoaban's appearance, his ability to move, and his interactions with the other types. The rules for the Cocoaban type became increasingly complex with release 2.0. Here is a sample of a "package moving" rule:

The rules for the Cocoaban character should remain fixed, as its only purpose is to provide a means for the user to move the packages on the board. You may, however, alter its appearance without affecting how the rules work.

Rule for Package Type

The Package Type has two rule sets. One rule tracks whether the Package Type has been placed in the Goal area.

It is important to notice the "in?" Variable, which tracks whether or not the piece has been placed in the Goal area. If the Package Type has been moved into the Goal area by the Cocoaban character, then this rule "fires," causes a sound to be played, and changes the "in?" Piece Variable to "yes" as well as adding 1 to the World Variable "packages." This variable keeps the game from playing the chime sound over and over.

The second rule set tracks the "level switching" in the game:

These rules were handled by the Goal Type in the original release of the Cocoaban authoring kit but have been switched to the Package Type in version 2.0. This switch was made because the Goal Type is actually deleted from the board as Packages are moved into the Goal area. Therefore, the Package Type had to be responsible for determining whether or not it is appropriate to progress to the next level.

Let us consider how the game determines whether it is appropriate to move from board 1 to board 2. First, examine the rules for how the Package Type queries the World Variables:

The Package Type first checks to see if the Current Board is board 1. Each board will have different numbers of packages that need to be moved to the Goal area, so it is important to first query which board is being played.

Second, the packages World Variable is checked to make certain that all the packages have been moved to the Goal area.

Once these requirements have been met, the game changes boards.

First, board 2 is put into the Current Board World Variable. Second, the Package Type chimes. Additionally, the packages World Variables is reset, readying it for the next board.

top

---

Creating Your Own Levels

Creating your own levels using the Cocoaban authoring kit is quite easy. The code is written so that you can add your own level, duplicate a piece of existing code, and have your game up and running in no time. This section will walk you through the customization process.

First, you should download a copy of the Cocoaban authoring kit. It's a self-extracting archive and should decompress when you double-click its icon.

Once you have the file you are ready to start building your own levels. The World comes with three boards already in place: the first two are completely built levels based on the first two levels of the Newtoban game and the standard Sokoban set. The third board is empty except for a patch of Goal area and a couple of packages. You might chose to completely re-create boards 1 and 2, or leave them as they are and start your own level on board 3. For the sake of this tutorial we are going to leave boards 1 and 2 as they are and work on customizing board 3.

Part I: setting up the board

The generic board 3 is pretty plain:

I customized my board 3 to look like this:

From here we'll take a look at how I set up the board. Then we'll look at how I modify the existing code to handle this board and the transition to the next board.

Setting up the World Variables

The World Variable "packages" must be configured for your board. The default set up has one package already in the Goal area.

We will reset the "package" variable to 0, so it is ready for your customized level.

Writing the Rules for the Package Type

Next, we need to modify our Package Type rule so that it will allow us to progress to the next board. First, we need to create another board. In this case we'll call this new level "board 4." Go to the Board menu and choose New Board:

If you go back to the Board menu and choose Show Boards you will see we now have a board 4 that we can work with:

Open the Rules for the Package Type by double-clicking on any Package Type. You will see a window that looks similar to this:

If you hold down the Option key on the keyboard and click with the mouse and drag the "board 2 -> 3" rule down, then release the mouse button, it will duplicate the rule. Rename the rule something like "board 3 -> 4."

Now we will edit the "board 3 -> 4" rules so they will work to move us ahead to the next board when we complete our goal of moving all the packages into the Goal area. Double-click on the "board 3 -> 4" rule, which opens this window. We will need to change two areas in order to make this rule work correctly:

First, I changed the "Current Board equals board 3" to make certain that this rule will only work when we are on board three. Second, I changed the number of packages, 9 in this case, to properly reflect how many packages need to be moved to the Goal area before the level is complete.

Now we must change the rest of the rule to work. Looking at the Package Type rules again, you will notice that we need to specify to which board we are moving upon completion of this level:

I have changed the second variable "Put board 4 Into Current Board" so that when all the packages are moved into the Goal area we will move to board 4.

Customization of the Cocoaban authoring kit is quite simple. The only rule that needs modification, so long as all other constraints have been observed, is the Package Type Rule that controls moving between levels. Once you have created a new board it is only a matter of duplicating the existing Package Rule, changing three settings, and you will be ready to play your game.

Submitting Your Cocoaban Level

Once you have created, tested, and debugged your World and its new level or levels, you can choose to submit your level to Josh Burker. He will then post your Cocoaban World along with the other submitted Worlds on the Cocoaban web page. You can help Josh by preparing your Cocoaban World for download as an AutoPlayer. Here's what you should do.

Preparing Your World as an AutoPlayer

If you want to share your Cocoaban World with people, it needs to be in a specific file format. First, decide whether you are including the original two levels. If not, simply go to the Board menu, select Show Boards, then click on and delete board 1 and board 2. You should make sure you are currently on a board other than board 1 or board 2 when you decide to delete them to avoid crashing Cocoa.

Next, go to the File menu and select "Build AutoPlayer...":

This will create a stand-alone application that any Mac can use.

Next, email Josh your AutoPlayer. He will test it to make certain that it works, then post it on the Cocoaban web page!

page created by Josh Burker

October 30, 2000

Updated May, 2003

Cocoa™, the graphic user interface in Cocoa™ and anything else having to do with Cocoa™ are trademarks of Apple Computer and are used here for noncommercial purposes.