Mission system - API - Generic mission methods

= mission_start -- OK =

Introduced in: alpha2.0

Arguments: None

Return value: None

Description: This is a method you define, and that gets called when the mission starts. That's usually where you introduce the mission to the player, ask him to perform an action, and then call the wait_for method.

Example:  class MyMission extends Mission { ...   function mission_start { $this->say("Welcome to the mission!"); ...

= go_to_site -- OK =

Introduced in: alpha2.0

Arguments: go_to_site($url, "callback_method_name")
 * $url = string (the URL of the new page to display to the player)
 * "callback_method_name" = string (the name of the method of the mission class that will get called once the user has been redirected to the new site)

Return value: None

Description: Changes the website the player is currently browsing to a new URL, and then calls back the method of the mission class called "callback_method_name".

Example:  class MyMission extends Mission { ...   function my_method { $this->say("Let me show you a website I like"); $this->go_to_url("http://barbie.com/", ken_talking); ...

function ken_talking { $this->say("Welcome to Barbie.com!"); ...

= wait_for =

Introduced in: alpha2.3 (was wait_for_action in previous versions)

Arguments: wait_for(ACTIONS, "callback_method_name", [arg1=$value1, [arg2=$value2, [...]]]);
 * ACTIONS = constants (the actions that will trigger calling the callback_method_name method - see below)
 * "callback_method_name" = string (the name of the method of the mission class that will get called)
 * arg1, arg2... = name of the action-specific argument (see description of actions below)
 * $value1, $value2... = value of the action-specific argument (see description of actions below)

Return value: None (will throw an exception if one of the action-specific arguments are missing)

Description: Allows to define a method that will be called when the ACTION is performed, for example as a result of an action of the player. The wait_for method doesn't block the execution of the rest of the method it is called in - you can put code after it and it will be executed immediately. Depending on the action, wait_for can take additional arguments and can call the callback_method_name method with arguments, depending on the action.

Several actions can be monitored simultaneously: just specify several actions as the first parameter, separated by '&'. You will then need to specify the extra arguments for all the corresponding actions, and the callback method will get the arguments corresponding to each of the specified actions.

Example:  class MyMission extends Mission { ...   function my_method { ...       $this->say("Please hack or scan this website"); $this->wait_for(HACK & SCAN, "my_other_method"); }

function my_other_method { $this->say("Well done!"); ...

Actions:
 * REPLY - Waits for the player to hit the "Reply" button 
 * Extra argument: None
 * Argument passed to the callback method: None
 * REPLY_TEXT - Adds a text input field next to the "Reply" button, waits for the player to enter some text in it and press "Reply", and then removes the text field 
 * Extra argument: None.
 * Argument passed to the callback method: answer=$answer_text, with $answer_text being the text entered by the player
 * REPLY_YESNO - Waits for the player to reply something containing either "yes" or "no"
 * Extra argument: None.
 * Argument passed to the callback method: $yesno, with $yesno being "Yes" or "No"
 * URL - Waits until the player navigates to a given URL
 * Extra argument: url=$url_string, with $url_string being the exact URL the user must navigate to
 * Argument passed to the callback method: None
 * URL_REGEX - Waits until the player navigates to a URL matching a given regex pattern
 * Extra argument: url_regex=$url_regex_string, with $url_regex_string being the regex pattern that must match a URL the user navigates to.
 * Argument passed to the callback method: url_matches=$regex_matches with $regex_matches being the regex match for the URL
 * HACK - Waits until the player hacks a page 
 * Extra argument: None.
 * Argument passed to the callback method: hack_success:$hack_success with $hack_success being true for a successful hack, false otherwise
 * DATA_UPDATE - Waits until a given data object gets updated, either as a result of an action of the player or of another player
 * Extra argument: data=$data_object, with $data_object being a DataObject.
 * Argument passed to the callback method: data=$data_object, with $data_object being the object passed to wait_for)
 * CUSTOM_BUTTON - Adds a button with a custom text to the interface, waits until the button is pressed, and then removes the custom button
 * Extra argument: button_text=$button_label_text, with $button_label_text being the text displayed in the custom button
 * Argument passed to the callback method: None.
 * LEADERBOARD - Waits until the player accesses the leaderboard
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * SITE_LIST - Waits until the player accesses his list of hacked sites
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * LOGIN - Waits until the player tries to login
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * EDIT_PROFILE - Waits until the player edits his profile
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * REGISTER - Waits until the player registers
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * REPLENISH_HACK_POINTS - Waits until the hack points of the player are replenished (level up)
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * REPLENISH_SCAN_POINTS - Waits until the scan points of the player are replenished (level up)
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * LOGOUT - Waits until the player logs out
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * FORGOT_PASSWORD - Waits until the player asks to recover his login password
 * Extra argument: None.
 * Argument passed to the callback method: None.
 * SEND_MESSAGE - Waits until the player sends a message to another player
 * Extra argument: None.
 * Argument passed to the callback method: None.

= give_reward =

Introduced in: alpha2.3 (was wait_for_action in previous versions)

XXX To describe

= say -- OK =

Introduced in: alpha2.0

Arguments: say($text)
 * $text: string (the text to display to the user)

Return value: None

Description: Displays the text passed as an argument to the player, in a chat-like interface.

Example:  class MyMission extends Mission { ...   function my_method { $this->say("Hello!"); ...

= stop_waiting_for -- OK =

Introduced in: alpha2.3 (was clear_action in alpha2.0)

Arguments: stop_waiting_for(ACTIONS, "callback_method_name")
 * ACTIONS = constants (actions declared in a former wait_for method)
 * "callback_method_name" = string (the name of the method of the mission class that was mentioned in the wait_for call)

Return value: None

Description: Cancels the effect of a previous wait_for call.

Example:  class MyMission extends Mission { ...   function step1 { $this->wait_for(HACK & SCAN, "step2a"); $this->wait_for(URL, "step2b", url="http://google.com/"); }

function step2a { $this->stop_waiting_for(URL, "step2b"); ...