diff options
Diffstat (limited to 'inc')
| -rw-r--r-- | inc/Inventory.inc | 70 | ||||
| -rw-r--r-- | inc/Item.inc | 57 | ||||
| -rw-r--r-- | inc/Monster.inc | 45 | ||||
| -rw-r--r-- | inc/account.inc | 20 | ||||
| -rw-r--r-- | inc/craftmine.inc | 13 | ||||
| -rw-r--r-- | inc/dungeon.inc | 50 | ||||
| -rw-r--r-- | inc/guild.inc | 30 | ||||
| -rw-r--r-- | inc/messages.inc | 34 | ||||
| -rw-r--r-- | inc/mine.inc | 24 | ||||
| -rw-r--r-- | inc/perso.inc | 28 | ||||
| -rw-r--r-- | inc/savegame.inc | 78 | ||||
| -rw-r--r-- | inc/shop.inc | 60 |
12 files changed, 492 insertions, 17 deletions
diff --git a/inc/Inventory.inc b/inc/Inventory.inc index 3e0137d..4a1add8 100644 --- a/inc/Inventory.inc +++ b/inc/Inventory.inc @@ -2,18 +2,44 @@ require_once("perso.inc"); +/** + * Represent the player's Inventory. + * Implemented as a singleton in the session. + * + * @package inc\Inventory.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ class Inventory { - + /** + * @var array Arrays of array with Item object and Item's count as int + */ public $items = array(); + /** + * Checks if the Inventory was already created in the session + * + * @return boolean true if Inventory was already created, false otherwise + */ public static function created() { return !empty($_SESSION["inventory"]); } + /** + * Returns the Inventory's content from the session. + * + * @return array array of Items and number + */ public static function sendContent() { return self::get()->items; } + /** + * Returns the Inventory from the session. + * Implements the singleton pattern. + * + * @return Inventory the Inventory object + */ public static function get() { if(!self::created()) { $_SESSION["inventory"] = new Inventory(); @@ -21,6 +47,12 @@ class Inventory { return $_SESSION["inventory"]; } + /** + * Adds an Item object to the Inventory, incrementing the Item's count if it was already present. + * + * @param Item $item Item to add to the Inventory + * @return array Item and Item's count + */ private function _addItem($item) { foreach($this->items as $k => $object){ if($object[0] == $item){ @@ -33,12 +65,24 @@ class Inventory { return $tab; } + /** + * Adds an Item object to the singleton's Inventory from session. + * + * @param Item $item Item to add to the Inventory + * @return array Item and Item's count + */ public static function addItem($item) { $inv = self::get(); $tab = $inv->_addItem($item); return $tab; } + /** + * Removes an Item object from the Inventory, not taking into account the Item's count. + * + * @param Item $item Item to remove from the Inventory + * @return void + */ private function _removeItem($item) { foreach($this->items as $k => $object) { if($object[0] == $item) { @@ -48,11 +92,23 @@ class Inventory { } } + /** + * Removes an Item object to the singleton's Inventory from session, not taking into account the Item's count. + * + * @param Item $item Item to remove from the Inventory + * @return void + */ public static function removeItem($item) { $inv = self::get(); $inv->_removeItem($item); } + /** + * Consumes an Item object from the Inventory, decrementing the Item's count and removing it if count reaches 0. + * + * @param Item $item Item to consume from the Inventory + * @return array|false Item and updated Item's count, false if it was not found + */ private function _useItem($item) { foreach($this->items as $k => $object){ if($object[0] == $item) { @@ -70,12 +126,24 @@ class Inventory { return false; } + /** + * Consumes an Item object to the singleton's Inventory from session, decrementing the Item's count and removing it if count reaches 0. + * + * @param Item $item Item to consume from the Inventory + * @return array|false Item and updated Item's count, false if it was not found + */ public static function useItem($item) { $inv = self::get(); $it = $inv->_useItem($item); return $it; } + /** + * Generates an XML tree describing the Inventory + * + * @param SimpleXMLElement $root root XML element to add the Inventory's Items to + * @return void + */ public function addToXML($root) { foreach($this->items as $item) $item[0]->addToXML($root, $item[1]); diff --git a/inc/Item.inc b/inc/Item.inc index a8ee302..435ca1c 100644 --- a/inc/Item.inc +++ b/inc/Item.inc @@ -2,13 +2,50 @@ require_once("perso.inc"); +/** + * Represent an Item in the shop or in the Inventory. + * + * @package inc\Item.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ class Item { + + /** + * @var string Name of the item. + */ public $name = ""; + + /** + * @var int Item's cost. + */ public $cost = 0; + + /** + * @var string Item's icon. + */ public $icon = ""; + + /** + * @var string Item's description. + */ public $desc = ""; + + /** + * @var array Item's features as an associative array + */ public $feat = array(); + /** + * Item's constructor + * + * @param string $name Item's name + * @param int $cost Item's cost + * @param string $icon Item's icon + * @param string $desc Item's description + * @param array $feat associative array of strings describing the Item's features + * @return void + */ function __construct($name, $cost, $icon, $desc, $feat) { $this->name = $name; $this->cost = $cost; @@ -17,6 +54,11 @@ class Item { $this->feat = $feat; } + /** + * Applies Item's features on the player. + * + * @return void + */ function consume() { foreach($this->feat as $k => $v) { switch($k) { @@ -26,6 +68,13 @@ class Item { } } + /** + * Generates an XML tree describing the Item + * + * @param SimpleXMLElement $xml root XML element to add the Item's property to + * @param int $count numbers of Items + * @return void + */ function addToXML($root, $count) { $item = $root->addChild("item"); $item->addChild("name", $this->name); @@ -38,12 +87,18 @@ class Item { $item->addChild("count", $count); } + /** + * Generates an Item object from an XML tree + * + * @param SimpleXMLElement $xml root XML element representing the Item + * @return void + */ public static function fromXML($xml) { $feats = array(); foreach($xml->feat[0] as $k => $v) $feats[(string)$k] = (string)$v; - return new static((string)$xml->name, +(string)$xml->cost /* convert to number */, (string)$xml->icon, (string)$xml->desc, $feats); + return new static((string)$xml->name, +(string)$xml->cost /* convert to number */, (string)$xml->icon, (string)$xml->desc, $feats); // Call constructor } } diff --git a/inc/Monster.inc b/inc/Monster.inc index ae48691..d00532f 100644 --- a/inc/Monster.inc +++ b/inc/Monster.inc @@ -1,14 +1,54 @@ <?php - +/** + * Represent an Item in the shop or in the Inventory. + * + * @package inc\Monster.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ class Monster { + /** + * @var string Name of the Monster. + */ public $name = ""; + + /** + * @var string Monster's icon. + */ public $icon = ""; - public $desc = ""; + + /** + * @var desc Monster's description. + */ + public $desc = ""; // TODO: unused + + /** + * @var int HP of the Monster. + */ public $hp = 1; + + /** + * @var int Exp given by this monster. + */ public $xp = 0; + + /** + * @var int Monster's level. + */ public $level = 1; public $power = 1; + /** + * Monster's constructor + * + * @param string $name Monster's name + * @param int $level Monster's level + * @param int $hp Monster's HP + * @param int $power Monster's power + * @param int $xp Exp given by the Monster + * @param string $icon Item's icon + * @return void + */ function __construct($name, $level, $hp, $xp, $power, $icon) { $this->name = $name; $this->level = $level; @@ -16,7 +56,6 @@ class Monster { $this->xp = $xp; $this->power = $power; $this->icon = $icon; - } } diff --git a/inc/account.inc b/inc/account.inc index 6f398bb..f7e3c05 100644 --- a/inc/account.inc +++ b/inc/account.inc @@ -1,6 +1,20 @@ <?php +/** + * Manages player's account: debit and credit. + * + * @package inc\account.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ + require_once("messages.inc"); +/** + * Debits the account of a certain amount of gold. + * + * @param int $amount amount to debit + * @return boolean true if player had enough gold, false otherwise + */ function debitAccount($amount) { if($_SESSION["mine"]["gold"] < $amount) { sendError("gold_insufficient"); @@ -10,6 +24,12 @@ function debitAccount($amount) { return true; } +/** + * Credits the account of a certain amount of gold. + * + * @param int $amount amount to credit + * @return void + */ function creditAccount($amount) { $_SESSION["mine"]["gold"] += $amount; } diff --git a/inc/craftmine.inc b/inc/craftmine.inc index f5dbbb1..7dd5ba4 100644 --- a/inc/craftmine.inc +++ b/inc/craftmine.inc @@ -1,10 +1,23 @@ <?php +/** + * Sends all data from previous session on page load. + * + * @package inc\craftmine.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ require_once("mine.inc"); require_once("shop.inc"); require_once("dungeon.inc"); require_once("perso.inc"); +/** + * Sends all data from previous session on page load. + * All data from the different modules are packed in an array. + * + * @return void + */ function sendCraftMine() { $data = array("gold" => sendMine(), "shop" => sendShop(), diff --git a/inc/dungeon.inc b/inc/dungeon.inc index d6b80fc..bf99685 100644 --- a/inc/dungeon.inc +++ b/inc/dungeon.inc @@ -1,12 +1,25 @@ <?php +/** + * Manages the dungeon. + * + * @package inc\dungeon.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ + require_once("messages.inc"); require_once("account.inc"); require_once("Monster.inc"); require_once("perso.inc"); +/** + * Loads all the dungeon's monsters from the XML file data/monsters.xml. + * + * @return array contains all the Monster objects + */ function generateMonster(){ $monsters = simplexml_load_file('data/monsters.xml'); - $dungeon = array("cost"=>(string)$monsters["cost"],"monsters"=>array()); + $dungeon = array("cost"=>(string)$monsters["cost"],"monsters"=>array()); //TODO: again, cost is a string? foreach($monsters as $f){ $floor = (string)$f["name"]; $dungeon["monsters"][$floor] = array(); @@ -22,16 +35,32 @@ function generateMonster(){ return $dungeon; } +/** + * Marks the dungeon as accessible in the session. + * + * @return void + */ function initDungeon() { - $_SESSION["dungeon"]["access"] = true; + $_SESSION["dungeon"]["access"] = true; // TODO: is the $_SESSION["dungeon"] array useful (and created beforehand)? } +/** + * Returns the dungeon array if it was created. + * + * @return array dungeon array as created by generateMonster + */ function sendDungeon() { if(!empty($_SESSION["dungeon"])) return $_SESSION["dungeon"]; else return false; } +/** + * Allows acces to the dungeon in the session and sends it to the client. + * Debits the dungeon's ticket cost from the player's gold. + * + * @return void + */ function buildDungeon() { $dungeon=generateMonster(); if(!empty($_SESSION["dungeon"])) { @@ -39,11 +68,16 @@ function buildDungeon() { } elseif(debitAccount($dungeon["cost"])) { initDungeon(); - $_SESSION["mine"]["gold"] -= $dungeon["cost"]; + $_SESSION["mine"]["gold"] -= $dungeon["cost"]; // TODO: Account was already debited echo json_encode($dungeon); } } +/** + * Sends monsters for a specific floor as specified by the floor POST parameter to the client. + * + * @return void + */ function launchDungeon(){ $f= $_POST["floor"]; $dungeon=generateMonster(); @@ -51,6 +85,11 @@ function launchDungeon(){ echo json_encode($opponent); } +/** + * Updates floor and monster number from the POST parameters in the session. + * + * @return void + */ function sendDungeonProgress(){ $f= $_POST["floor"]; $nb=$_POST["mob"]; @@ -59,6 +98,11 @@ function sendDungeonProgress(){ reusable(); } +/** + * Marks the dungeon as not accessible in the session. + * + * @return void + */ function exitDungeon(){ $_SESSION["dungeon"] = false; diff --git a/inc/guild.inc b/inc/guild.inc index 1666b15..537b87a 100644 --- a/inc/guild.inc +++ b/inc/guild.inc @@ -1,6 +1,19 @@ <?php +/** + * Manages miners guild. + * + * @package inc\guild.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ +/** + * Amount of gold required to build the miners guild. + */ define("GUILD_COST",10); +/** + * Amount of gold required to hire a miner. + */ define("MINER_COST",5); function initMinersIfNeeded() { @@ -10,6 +23,12 @@ function initMinersIfNeeded() { $_SESSION["mine"]["miners"] = 0; } +/** + * Create the miners guild in the session. + * Debits GUILD_COST from the player's gold. + * + * @return void + */ function createGuild(){ if(!empty($_SESSION["guild"])) { sendError("guild_already_built"); @@ -20,6 +39,12 @@ function createGuild(){ } } +/** + * Hire one miner. + * Debits MINER_COST from the player's gold. + * + * @return void + */ function hireMiner(){ if(!isset($_SESSION["guild"])){ sendError("guild_not_yet_created"); @@ -31,6 +56,11 @@ function hireMiner(){ } } +/** + * Returns the number of miners currently in the guild. + * + * @return int number of miners in the guild + */ function sendMiners(){ initMinersIfNeeded(); return $_SESSION["mine"]["miners"]; diff --git a/inc/messages.inc b/inc/messages.inc index 97e1da2..7b0d624 100644 --- a/inc/messages.inc +++ b/inc/messages.inc @@ -1,5 +1,15 @@ <?php +/** + * Server to client error/info messages list and helpers. + * + * @package inc\messages.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ +/** + * Messages list. + */ $messages = array( "shop_already_built" => "You have already built a shop.", "gold_insufficient" => "You don't have enough gold.", @@ -19,6 +29,14 @@ $messages = array( "upload_success" => "Save file uploaded successfully: %s", ); +/** + * Sends a message to the client. + * + * @param string $type message type, for example "info" or "error" + * @param string $msg message content + * @param string $fmt optional parameters to apply when formating message string + * @return void + */ function sendMessage($type, $msg, $fmt = null) { global $messages; $text = $messages[$msg]; @@ -26,10 +44,26 @@ function sendMessage($type, $msg, $fmt = null) { echo json_encode(array($type => $text)); } +/** + * Sends an error message to the client. + * Simple wrapper calling sendMessage with "error" as $type. + * + * @param string $msg message content + * @param string $fmt optional parameters to apply when formating message string + * @return void + */ function sendError($msg, $fmt = null) { sendMessage("error", $msg, $fmt); } +/** + * Sends an info message to the client. + * Simple wrapper calling sendMessage with "info" as $type. + * + * @param string $msg message content + * @param string $fmt optional parameters to apply when formating message string + * @return void + */ function sendInfo($msg, $fmt = null) { sendMessage("info", $msg, $fmt); } diff --git a/inc/mine.inc b/inc/mine.inc index 76dfb50..fb5f612 100644 --- a/inc/mine.inc +++ b/inc/mine.inc @@ -1,5 +1,17 @@ <?php +/** + * Manages the mine. + * + * @package inc\mine.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ +/** + * Initializes the gold amount and miners count in the session. + * + * @return void + */ function initMineIfNeeded() { if(empty($_SESSION["mine"])) $_SESSION["mine"] = array("gold" => 0); @@ -7,9 +19,14 @@ function initMineIfNeeded() { $_SESSION["mine"]["gold"] = 0; } +/** + * Transfers all gold from the mine to the player's account. + * + * @return void + */ function withdrawMine() { $amount = intval($_POST["amount"]); - if(!empty($_SESSION["dungeon"])) { + if(!empty($_SESSION["dungeon"]) && !empty($_SESSION["dungeon"]["flat"])) { // player in dungeon sendError("cant_withdraw_in_dungeon"); return; } @@ -19,6 +36,11 @@ function withdrawMine() { echo json_encode($_SESSION["mine"]["gold"]); } +/** + * Returns the amount of gold currently owned by the player. + * + * @return int amount of gold available + */ function sendMine() { initMineIfNeeded(); $mine = $_SESSION["mine"]; diff --git a/inc/perso.inc b/inc/perso.inc index 2a514bb..e38fb4c 100644 --- a/inc/perso.inc +++ b/inc/perso.inc @@ -1,11 +1,29 @@ <?php +/** + * Manages player's stats: life, experience, level. + * + * @package inc\perso.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ +/** + * Returns all player's stats after initializing them if needed. + * + * @return int[] arrays containing player's stats + */ function sendPerso() { if(empty($_SESSION["perso"])) initPerso(); return $_SESSION["perso"]; } +/** + * Increases a player's stat. + * + * @param int $prop stat to increase + * @return void + */ function increasePerso($prop, $num) { if(empty($_SESSION["perso"])) initPerso(); @@ -69,6 +87,11 @@ function reusable(){ } } +/** + * Copies stats given in POST request to session. + * + * @return void + */ function updatePerso(){ $hp = $_POST["hp"]; $maxHP = $_POST["maxHP"]; @@ -84,6 +107,11 @@ function updatePerso(){ $_SESSION["perso"]["bonusPower"] = +$bonusPower; } +/** + * Initializes the player's stats. + * + * @return void + */ function initPerso(){ $_SESSION["perso"]["hp"] = 5; $_SESSION["perso"]["maxHP"] = 5; diff --git a/inc/savegame.inc b/inc/savegame.inc index 6d92af2..3e3ffcc 100644 --- a/inc/savegame.inc +++ b/inc/savegame.inc @@ -1,11 +1,35 @@ <?php +/** + * Load and save the game. + * + * @package inc\savegame.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ require_once("inc/messages.inc"); require_once("inc/Inventory.inc"); require_once("inc/Item.inc"); +/** + * Directory to save to and load from. + * The PHP/Apache user must have write permission on this directory. + * Use the following commands to give write permissions to the http group: + * <samp> + * sudo chown :http data/save + * sudo chmod g+w data/save + * </samp> + */ define("SAVEDIR", "data/save"); +/** + * Recursively generates an XML tree from an array. + * If objects are found, call addToXML() methods which should serialize the object as a child of the XML tree passed as parameter. + * + * @param array $table an array with mixed type elements to convert to XML + * @param SimpleXMLElement $xml root XML to add the elements to + * @return void + */ function genXML($table, $xml) { foreach($table as $k => $v) { if(is_object($v)) { // Object: either Item or Inventory @@ -18,22 +42,44 @@ function genXML($table, $xml) { } } +/** + * Generates the XML save tree from the session. + * + * @return void + */ function genSave() { $save = new SimpleXMLElement("<save/>"); genXML($_SESSION, $save); return $save; } +/** + * Generates the save file name using current date/time. + * The date function will use the server's timezone which could be inconsistent with the client timezone. + * + * @return string the generated file name + */ function genFilename() { return "craftmine-".date("d-m-Y_H-i-s").".save.xml"; } +/** + * Save the XML save tree as an XML file named after the results of genFilename in SAVEDIR. + * Fails and send an error the the client if permissions are incorrectly set. Watch for errors in PHP log. + * + * @return void + */ function saveGame() { $save = genSave(); if($save->asXML(SAVEDIR."/".genFilename())) sendInfo("gamesave_ok"); else sendError("gamesave_error"); } +/** + * Sends the current game or a specific save file given by the filename GET parameter to the client. + * + * @return void + */ function downSave() { $save = ""; $filename = ""; @@ -53,11 +99,24 @@ function downSave() { echo $save; } +/** + * Sends the list of available saves to the client. + * Warning: this function changes directory. + * + * @return void + */ function listSaves() { chdir(SAVEDIR); // Go to SAVEDIR folder, avoiding leading folder name in file list echo json_encode(glob("*.save.xml")); } +/** + * Reads an XML tree and deserializes it to an array. + * + * @param SimpleXMLElement $xml root XML to read the elements from + * @param array $table an empty array to stores the elements to, passed by reference + * @return void + */ function parseSave($xml, &$table) { // Passing $table by reference foreach($xml as $k => $v) { if($v->count() == 0) { // No child, treat as string @@ -76,6 +135,11 @@ function parseSave($xml, &$table) { // Passing $table by reference } } +/** + * Deletes a save file given as the filename POST parameter. + * + * @return void + */ function deleteSave() { if(empty($_POST["filename"])) return; $path = SAVEDIR . "/" . basename($_POST["filename"]); // remove any leading directory @@ -84,6 +148,12 @@ function deleteSave() { else sendError("gamesave_delete_fail"); } +/** + * Loads a save file given as the filename POST parameter to the session. + * Empties the session beforehand. + * + * @return void + */ function loadSave() { if(empty($_POST["filename"])) return; $xml = simplexml_load_file(SAVEDIR . "/" . $_POST["filename"]); @@ -95,6 +165,14 @@ function loadSave() { parseSave($xml, $_SESSION); } +/** + * Reads a save file sent by the client. + * Parse the received file then generate it again to clean it for any unwanted + * and make sure that it is a valid XML save file. + * XML errors are simply ignored and an error is sent to the client if something wrong happens. + * + * @return void + */ function uploadSave() { $fname = basename($_FILES['savefile']['name']); $src = $_FILES['savefile']['tmp_name']; diff --git a/inc/shop.inc b/inc/shop.inc index 69161e1..2dbd19d 100644 --- a/inc/shop.inc +++ b/inc/shop.inc @@ -1,4 +1,11 @@ <?php +/** + * Manages the shop. + * + * @package inc\shop.inc + * @author Alexandre Renoux + * @author Pierre-Emmanuel Novac + */ require_once("messages.inc"); require_once("account.inc"); @@ -6,19 +13,24 @@ require_once("Item.inc"); require_once("Inventory.inc"); require_once("perso.inc"); +/** + * Loads all the shop's items from the XML file data/items.xml. + * + * @return array contains all the Item objects + */ function loadShop(){ - $items = simplexml_load_file('data/items.xml'); - $shop = array("cost"=>(string)$items["cost"],"items"=>array()); - foreach($items as $cat){ + $items = simplexml_load_file('data/items.xml'); //TODO: handle errors + $shop = array("cost"=>(string)$items["cost"],"items"=>array()); //TODO: cost is a string? + foreach($items as $cat){ // Loop over all categories $category = (string)$cat["name"]; $shop["items"][$category] = array(); - foreach($cat as $item){ + foreach($cat as $item){ // Loop over all items inside a category $feats = array(); - foreach($item->features[0] as $k => $v) + foreach($item->features[0] as $k => $v) // Reads features $feats[(string)$k] = (string)$v; $shop["items"][$category][] = new Item( (string)$item->name, - intval($item->cost), + intval($item->cost), //Note: cost is an int here. (string)$item->icon, (string)$item->description, $feats); @@ -27,6 +39,12 @@ function loadShop(){ return $shop; } +/** + * Gets an Item object from the shop from its name. + * + * @params string $name the name of the object to search for + * @return Item|false the Item object or false if the item was not found + */ function getItem($name) { $shop=loadShop(); foreach($shop["items"] as $cat) { @@ -40,16 +58,32 @@ function getItem($name) { return false; } +/** + * Marks the shop as created in the session. + * + * @return void + */ function initShop() { $_SESSION["shop"] = true; } +/** + * Returns the shop array if it was created. + * + * @return array shop array as created by loadShop + */ function sendShop() { if(!empty($_SESSION["shop"])) return loadShop(); else return false; } +/** + * Creates the shop in the session and sends it to the client. + * Debits the shop's cost from the player's gold. + * + * @return void + */ function buildShop() { $shop=loadShop(); if(!empty($_SESSION["shop"])) { @@ -61,14 +95,24 @@ function buildShop() { } } +/** + * Debits the item's cost specified as the item POST parameter, adds it to the Inventory and sends it to the client. + * + * @return void + */ function buyItem() { $item = getItem($_POST["item"]); if($item && debitAccount($item->cost)) { - $tab = Inventory::addItem($item); - echo json_encode($tab); //renvoyer un tableau avec comme première entrée $item et comme deuxième entrée le nombre + $tab = Inventory::addItem($item); + echo json_encode($tab); // Sends an array with the Item as first member and count as second. } } +/** + * Invoke useItem on an item passed as the item POST parameter, sends to the client the updated player stats and the item. + * + * @return void + */ function useItem(){ $item = getItem($_POST["item"]); $it = Inventory::useItem($item); |