Mission system - Developer Tutorial

= Introduction =

Missions
HackIt includes a powerful-but-easy mission scripting engine. The basic principle is to give the player something to do on the Web ("find the website of an oil company"), and then monitor his actions to know when he has completed it (here, know when he has arrived on bp.com for example).

The mission system thus provides the mission developer with ways to communicate with the player, and the ability to know what the player is doing on the Web at any time.

Audience
The syntax of the mission engine is voluntarily kept simple, to allow anyone with a basic knowledge of PHP programming to be able to create his own missions. You do not need to know the inner working of the rest of the game - the engine does the hard work for you, and tries to give you access to the informations you need about what the player is doing in the simplest manner.

= Getting started - Principles =

The usual mission structure goes this way:

Step 1 - Talking to the player
First you ask the player to do something - this is presented as a chat message to the player: $this->say("Hello - can you go on an oil company website for me please?");

Step 2 - Waiting for an action from the player
You wait for the player to perform the corresponding action (here, changing the website he is currently seeing to one that is from an oil company): $this->wait_for_action(GO_TO_SITE, "my_callback_function");

Step 3 - Checking the action of the player
When the player navigates to another website, the mission engine will call the my_callback_function function that you wrote, where you will be able to check if the website the player just arrived on is the one you were expecting: if($this->site-&gt;domain == "bp.com") { $this->say("Well done!"); }

Or, better, you could even check if the delicious.com tags for this website contains "oil", to allow the player to choose any oil company he wants: if($this->site-&gt;has_tag("oil") {    $this->say("This website is definitely related to oil!"); }

= Hello World! =

Now, how does a mission file looks like? Here is the traditionnal HelloWorld.php file, that shows you the basic structure. You will notice that we use a class definition - don't worry though, you don't need to know object-oriented programming to script the mission system.

 say("Hello World!");

return true; } }

?>

Let's go through the different parts.

Mission description
 

This allows the mission engine to find the necessary information about the mission. You only need to change the following values:
 * The class name: change HelloWorld to the name of your mission
 * The mission name: set $mission_name to a human-readable version of your mission name
 * The mission description: set $mission_description to a short one-line description of the mission, that will be visible to the player

Beginning of the mission
 say("Hello World!");

return true; } }

?>

The mission_start method is the method that is called by the engine when the mission starts. This is usually where you introduce the mission to the player, before waiting for him to do something. Here, we simply say "Hello World!" to him, and then we add this line to exit the method:

 function mission_start {       $this->say("Hello World!");

return true; } ?>

To tell the mission engine that everything went fine. See below for more details about the return value of methods.

Modifying the player environment
Saying "Hello World" to the player is nice already, but let's see if we can't do better. Maybe we could also show him the wikipedia page that explains what "Hello world" is all about...

To do this, we'll use the following function, that will change the page the player's browser is displaying:

 say("Hello World!"); $this->go_to_site("http://en.wikipedia.org/wiki/Hello_world_program");

return true; } }

?>

= Handling user actions =

 $this->wait_for_action(REPLY, 'mission_start_2');

Types of actions:  define ('REPLY',1); define ('GO_TO_SITE',2); define ('HACK',4); define ('SCAN',8); define ('INTERFACE_ACTIONS',16);

Return true or false

= Reference =

See Mission system - API

= Differences with current implementation =


 * Change: Base class name changed to Mission
 * Add: Default mission_start method (but keep public $start_function to change the default value)
 * Add: $this-&gt;current_site-&gt;domain points to base domain
 * Add: $this-&gt;current_site-&gt;has_tag("oil") to check delicious tag
 * Change: $this-&gt;go_to_site : the 2nd parameter is optional. And rename to go_to_url

To add to this document and change in the missions system

 * Add: "repeatable" mission parameter
 * Change: $this-&gt;play_data['home_url'] =&gt; $this-&gt;player-&gt;home_url
 * if($_GET['result']=='fail') =&gt; if($this-&gt;last_action-&gt;result == FAIL)
 * if($_GET['tag']!='internet') =&gt; if($this-&gt;current_site-&gt;has_tag("internet"))
 * rewards on player instead of mission:
 * $this-&gt;player-&gt;give_reward(1, "max_hack_points"); // Add one point to the maximum of hack points
 * $this-&gt;player-&gt;give_reward(1, "max_scan_points"); // Same thing with scan points
 * $this-&gt;player-&gt;replenish_hackscan_points;
 * Find solution to not switch method when switching page: $this-&gt;go_to_site("http://community.hackit.cx/", 'navigate_to_forum'); (General issue of changing pages? Adding # in URL to avoid page change?)
 * uniformize $this-&gt;wait_for_* calls. Maybe rename all to $this-&gt;wait_for(ACTION, "method_callback", *args) ? But what about calls "hidden" by higher level methods in mission meta classes? What about custom actions defined by missions?

To add to this document

 * return true not necessary

Hooks / missions

 * user mistakes handling:
 * how to warn about a mistake
 * how to give a way for the player to re-read or go back (chat history?)
 * hacking missions (integration of hackit elements: hack/scan, animations, hack&amp;scan points, ownership, leaderboard, latest changes)
 * external threat: virus that spreads and needs X players to hack each website within 24 hours or it will spread to more websites (evolution independent of player action, mission starts/continues at any time)
 * get string in page: quizz for HR
 * suggesting/rating/writing/improving a mission (includes multi-categories missions)
 * Unit tests for missions