developpers:documentation_mod []

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
====== Tutoriel - Création d'un mod pour OGSpy ======

Afin de développer un mod OGSpy, plusieurs règles doivent être respectées.

===== Nom et version du mod =====

Le nom du mod devra être écrit en minuscules et ne devra pas contenir de caractères spéciaux. Ce nom de mod est utilisé sur le système de fichier du serveur donc doit être à la fois simple et concis.

Ce nom n'est pas le nom affiché à l'utilisateur : il peut être personnalisé dans le fichier version.txt (Voir plus bas la composition de ce fichier)

Le numéro de version devra être de la forme X.Y.Z
  * X étant le numéro de version Majeur (Incrémenté lors d'une évolution importante du Mod)
  * Y étant le numéro de version Mineur (Incrémenté lors d'une évolution légère)
  * Z étant le numéro incrémenté pour les corrections de bugs.

===== Organisation du mod =====
==== Fichiers requis ====

Les fichiers requis sont les suivants :

  * **__install.php__** : fichier d'installation du mod, il ne sera exécuté lorsque le mod sera installé via l'administration d'OGSpy.
  * **__uninstall.php__** : l'inverse, fichier de désinstallation du mod, exécuté lorsque le mod sera désinstallé via l'administration OGSpy.
  * **__update.php__** : fichier exécuté à la mise à jour du mod, que ce soit via l'administration OGSpy ou via le mod AutoUpdate.
  * **__version.txt__** : fichier contenant certaines informations relative à votre mod, il n'est pas exécuté mais est lu par OGSpy lors de l'installation du mod.

Voici le code minimum de ces fichiers. Si votre mod ne crée pas de table il n'y a pas grand chose à modifier. Si au contraire votre mod a besoin de tables en plus, nous vous conseillons de regarder comment cela est fait dans des mods déjà existants (prenez exemple sur des mods qui fonctionnent correctement avec la dernière version d'OGSpy).

<note warning>Tout les fichiers de votre mod doivent utiliser l'encodage UTF-8 (Sans BOM) !</note>

<file php install.php>
<?php

if (!defined('IN_SPYOGAME')) {
    exit('Hacking Attempt!');
}

$mod_folder = 'nom du dossier du mod'; // à modifier

if (install_mod($mod_folder)) {
    // Si besoin de créer des tables, à faire ici
}
else {
    echo "<script>alert('Un problème a eu lieu pendant l'installation du mod, corrigez les problèmes survenus et réessayez.');</script>";
}

</file>

<file php uninstall.php>
<?php

if (!defined('IN_SPYOGAME')) {
    exit('Hacking Attempt!');
}

global $table_prefix;

$mod_uninstall_name  = 'nom du mod'; // à modifier

// S'il n'y a qu'une seule table à supprimer
$mod_uninstall_table = $table_prefix .'table1'; // à modifier

// S'il y en a plusieurs à supprimer
$mod_uninstall_table = $table_prefix .'table1, '. $table_prefix .'table2'; // à modifier

uninstall_mod($mod_uninstall_name, $mod_uninstall_table);

</file>

<file php update.php>
<?php

if (!defined('IN_SPYOGAME')) {
    exit('Hacking Attempt!');
}

$mod_folder = 'nom du dossier du mod'; // à modifier
$mod_name   = 'nom du mod'; // à modifier

update_mod($mod_folder, $mod_name);

</file>

<file text version.txt>
nom du mod
version du mod (sous la forme x.y.z)
titre, menu, action, root, link, active, admin
Version OGSPy minimale requise
</file>

Le fichier version.txt ne contient donc que 4 lignes. Pour la troisième ligne, les informations sont les suivantes :

  * titre : le nom de votre mod.
  * menu : le nom que votre mod prendra dans le menu OGSpy.
  * action : la valeur du paramètre GET "action" (exemple avec le mod AutoUpdate : http://www.mon-serveur-ogspy.fr/ogspy/index.php?action=**__autoupdate__**).
  * root : le nom du dossier contenant les fichiers de votre mod.
  * link : le fichier PHP qui sera appelé lorsqu'on cliquera sur votre mod dans le menu.
  * active : un mod peut être actif ou inactif (installé mais impossible de l'utiliser), mettez 1 si vous voullez que votre mod soit actif juste après avoir été installé ou 0 si vous voulez qu'il soit inactif après installation.
  * admin : mettez 1 si votre mod ne peut être utilisé que par des administrateurs, 0 si c'est pour tout le monde.

<note important>Les apostrophes doivent être échappées avec un backslash (exemple, si le nom de votre mod dans le menu est **L'Univers** vous devez mettre **L\'Univers**).</note>

La dernière ligne contient la version OGSpy demandée.

Exemple complet:

<file text version.txt>
Superapix
0.1.1
superapix,superapix,superapix,superapix,index.php,1,1
3.2.0
</file>

==== Vos fichiers ====

Le dernier fichier requis est le points d’entrée de votre mod, celui que vous avez mis dans a la place de "link" dans le fichier //version.txt//. À part ça, vous être libre d'organiser vos fichiers et vos ressources comme vous le souhaitez. Voici un exemple d'un fichier "link" :

<file php mon-link.php>
<?php

if (!defined('IN_SPYOGAME')) {
    exit('Hacking attempt!');
}

require_once('views/page_header.php');

?>
<style type="text/css">
    body {
       background-color: white;
    }
    
    .mon-mod-p {
        color: black;
        font-size: 26px;
    }
</style>
<?php

echo '<p class="mon-mod-p">Hello World!</p>';

require_once(views/page_tail.php);

</file>

===== Accès à la base de données =====
//TODO: wiki à mettre à jour//

L'accès à la base de données ne peut se faire n'importe comment, il doit se faire à travers la variable global $db, instance de classe sql_db définie dans includes/mysql.php. Utiliser les méthodes du genre mysql_query() est possible mais fortement déconseillé ! Les méthodes disponibles sont les suivantes :

<file php includes/mysql.php>

class sql_db {
    // Permet d'exécuter une requête SQL quelconque.
    //
    // $query : requête SQL
    // $dieOnSQLError : si la requête provoque une erreur, arrête le script PHP et affiche l'erreur
    // $logQuery : enregistre la requête dans les logs si $server_config['debug_log'] vaut 1
    //
    // Retourne le résultat de la requête SQL.
    //
    // Exemple : $db->sql_query('SELECT user_name, user_password FROM '. TABLE_USER);
    //
    function sql_query($query, $dieOnSQLError = true, $logQuery = true);
    
    // Récupère une ligne d'une requête SQL. Si $query_id vaut 0, la méthode s'appliquera sur la dernière requête exécutée.
    // Équivalent à mysql_fetch_array($query_id, MYSQL_NUM).
    //
    // Retourne donc un tableau indexé numeriquement.
    //
    // Exemple : while (list($username, $password) = $db->sql_fetch_row()) {
    //               echo 'Pseudo: "'. $username .'"<br />';
    //               echo 'Hash du password : "'. $password .'"';
    //           }
    //
    function sql_fetch_row($query_id = 0);
    
    // Équivalent à sql_fetch_row mais retourne un array numérique et associatif.
    //
    function sql_fetch_assoc($query_id = 0);
    
    // Nombre de ligne concernées par la dernière requête (ou celle spécifiée).
    //
    // Exemple : $db->sql_numrows(); // retourne le nombre d'utilisateur dans la table TABLE_USER
    //
    function sql_numrows($query_id = 0);
    
    // Retourne le nombre d'entrées modifiées par la dernière requête INSERT, UPDATE, REPLACE ou DELETE.
    //
    function sql_affectedrows();
    
    // ID (int) de la dernière requête exécutée par $db->sql_query($query).
    //
    function sql_insertid();
    
    // Libère les ressources renvoyées par la dernière requête (ou celle spécifiée)
    //
    function sql_free_result($query_id = 0) {
    
    // Retourne un tableau avec l'entrée 'message' et l'entrée 'code' contenant respectivement le message et le code de l'erreur
    // générée par la dernière requête (ou celle spécifiée).
    //
    function sql_error($query_id = 0);
    
    // Retourne le nombre de requête exécutée.
    //
    function sql_nb_requete();
    
    // Échappe la chaîne de caractères donnée. Équivalent à mysql_real_escape_string().
    //
    function sql_escape_string($str);
}

</file>

Afin d'avoir accès à la variable $db vous devez faire un :

<PHP>
<?php

// ...

global $db; // c'est tout !

$db->sql_query(...);

// ...

?>
</PHP>

===== Les variables OGSpy =====

Pour une raison de sécurité, toutes les variables POST et GET ont été remplacées.

<PHP>
echo $pub_exemple; // à la place de echo $_POST['exemple'];
echo $pub_exemple; // à la place de echo $_GET['exemple'];
</PHP>

En ce qui concerne les tables d'OGSpy de base, vous avez le droit d'insérer des éléments dedans, ou de supprimer celles que vous avez mises mais vous avez en aucun cas, le droit de les supprimer ou de les altérer, par contre vous avez le droit de créer vos propres tables. N'oubliez pas lors de la création de vos tables que le préfixe existe et peux changer. C'est pour cela que nous vous conseillons de définir vos tables en haut de la page comme ceci:

<PHP>
define('TABLE_EXEMPLE', $table_prefix.'exemple');
</PHP>

et voici la liste des tables OGSpy:

<PHP>
define('TABLE_CONFIG', $table_prefix.'config');
define('TABLE_GROUP', $table_prefix.'group');
define('TABLE_RANK_PLAYER_FLEET', $table_prefix.'rank_player_fleet');
define('TABLE_RANK_PLAYER_POINTS', $table_prefix.'rank_player_points');
define('TABLE_RANK_PLAYER_RESEARCH', $table_prefix.'rank_player_research');
define('TABLE_RANK_ALLY_FLEET', $table_prefix.'rank_ally_fleet');
define('TABLE_RANK_ALLY_POINTS', $table_prefix.'rank_ally_points');
define('TABLE_RANK_ALLY_RESEARCH', $table_prefix.'rank_ally_research');
define('TABLE_SESSIONS', $table_prefix.'sessions');
define('TABLE_SPY', $table_prefix.'spy');
define('TABLE_STATISTIC', $table_prefix.'statistics');
define('TABLE_UNIVERSE', $table_prefix.'universe');
define('TABLE_UNIVERSE_TEMPORARY', $table_prefix.'universe_temporary');
define('TABLE_USER', $table_prefix.'user');
define('TABLE_USER_BUILDING', $table_prefix.'user_building');
define('TABLE_USER_DEFENCE', $table_prefix.'user_defence');
define('TABLE_USER_FLEET', $table_prefix.'user_fleet');
define('TABLE_USER_FAVORITE', $table_prefix.'user_favorite');
define('TABLE_USER_GROUP', $table_prefix.'user_group');
define('TABLE_USER_SPY', $table_prefix.'user_spy');
define('TABLE_USER_TECHNOLOGY', $table_prefix.'user_technology');
define('TABLE_USER_PLANET', $table_prefix.'user_planet');
define('TABLE_MOD', $table_prefix.'mod');
define('TABLE_MOD_CAT', $table_prefix.'mod_cat');
define('TABLE_MOD_RESTRICT', $table_prefix.'mod_restrict');
define('TABLE_PARSEDSPY', $table_prefix.'parsedspy');
define('TABLE_PARSEDRC', $table_prefix.'parsedRC');
define('TABLE_PARSEDRCROUND', $table_prefix.'parsedRCRound');
define('TABLE_ROUND_ATTACK', $table_prefix.'round_attack');
define('TABLE_ROUND_DEFENSE', $table_prefix.'round_defense');
define('TABLE_MP', $table_prefix.'mp');
</PHP>

dans TABLE_CONFIG se trouve toutes les configurations d'OGSpy (allez directement dans phpmyadmin pour voir ce qui peux vous intéresser), alors si vous souhaitez en lire une, utilisez simplement ça:

<PHP>
$server_config['lavariable']
</PHP>


===== Utilisation des paramètres =====

Des fonctionnalités ont été développées au sein d'OGspy pour faciliter la vie des Modders.

Ici nous allons décrire la gestion des paramètres. Ces paramètres sont enregistrés dans la base de données dans la table "ogspy_mod_config" et sont donc persistants.

==== mod_set_option ====

Permet d'ajouter un paramètre de configuration et sa valeur pour un mod donné.
<PHP>
/**
 * @param string $param Nom du paramètre de configuration
 * @param string $value Valeur du paramètre de configuration
 * @return boolean Retourne true/false selon le résultat de l'enregistrement en base de données
*/
function mod_set_option($param, $value) 
</PHP>


==== mod_del_option ====

Permet d'effacer un paramètre de configuration pour un mod donné.
<PHP>
/**
 * @param string $param Nom du paramètre de configuration
 * @global $db
 * @return boolean Retourne true/false selon le résultat de l'enregistrement en base de données
*/
function mod_del_option($param)
</PHP>


==== mod_get_option ====

Permet de lire la valeur d'un paramètre de configuration pour un mod donné.

<PHP>
/**
 * @param string $param Nom du paramètre de configuration
 * @global $db
 * @return string Retourne la valeur du paramètre demandé
*/
function mod_get_option($param)
</PHP>