Now that PointClickPress is almost in beta I’ve been working on building an actual game with PCP to find bugs and any other issues. I thought this would be a good time to write a tutorial on how to use some of PointClickPress’s features. I’m going to start with an explanation of Locations since it may not be immediately apparent what they are or how they should be used.

Locations

• Scenes link to Locations (not Scene to Scene)
• Locations may have Actions attached to them
• One Location can hold many Scenes
• The parent Location determines what child Scene is served
• The default Scene in a Location is the Scene with no value
• A Location’s value is a variable that can be assigned the value of a Scene

Let’s walk through a scenario where each of these rules are used.

Setup

So you’ve created a story called “MyStory” and initially it is set up with two locations like this:

Each room location is set up with one scene. So each Location looks something like this:

This is what the My Room Scene looks like:

In the “My Room” Scene’s Grid there is a Link action which connects “My Room” to the “My Other Room” Location.

Now when the a player plays “MyStory” they will start in the “MyRoom” Location in the Scene “My Room” and they will be able to click on the door and move in the the “My Other Room” Location and see the “My Other Room” Scene.

That’s pretty straight forward.

But what if we wanted to do something a little more interesting? What if the second room’s lights were turned off so the player couldn’t see anything until the lights were turned on?

First we would have to create a second Scene in the “My Other Room ” Location that portrayed the “My Other Room” Location with its lights off. We will give this new scene a value of “lights_off”

Now we give our original “My Other Room” Scene a value of “lights_on”. So when we are done the “My Other Room” Location should look like this.

Now we need a way to turn the lights on and off. In the “My Room” Scene in the “My Room” Location let’s add a light switch:

On the light switch we’ll add a Grid Action. We will use the Ternary ‘if’ Statement. The Action value will be

$my_other_room = ($my_other_room == 'lights_off')?'lights_on':'lights_off';

Notice how we can use the value of the Location as a variable and assign it the value of a scene here. Now when the switch is clicked it will turn the lights on and off.

This will work fine if the user clicks the switch before they enter the “My Other Room” Location, but what happens if they enter the Location without clicking the switch? Which Scene would get loaded?

At first it seems like nothing happens. Then we discover that nothing works anymore. Since the PointClickPress engine is using ajax to load the scene the error is hidden from us.* We can refresh the page to see the error.

No Scene id
Did you set your starting scene? Otherwise this is usually caused because there is no scene with the value you asked for in this location.

Since the default Scene is the one without a value and now we don’t have a scene without a value we will instead get an error when we enter the Location without clicking the switch. We can fix this by setting an initial value for the $my_other_room variable. We will add an Assign Action at the story level. Story level actions are only executed when the story begins and are a great place to put initialization variables.

$my_other_room = 'lights_off';

Now when the story starts the “My Other Room” Location will know which scene to load.

Alternate solution
An alternate way to have solved this issue is to have made the ‘lights_off’ scene instead be the default scene with a value of ”. Then that would be loaded by default and your light switch Action would be:

$my_other_room = ($my_other_room == '')?'lights_on':'';

*You can use Firebug to see what is being returned from PointClickPress to help you debug. You can also turn on and use the Debugging Plugin.