Etape 1 – Cases et sous-cases

Au niveau de granularité le plus grossier, le plateau de jeu est découpé en 13 lignes de 15 cases chacune, pour un total de 195 cases.

Chaque case du plateau est identifiée par sa position sur le plateau, donnée par une paire de coordonnées entières (x, y). La première de ces coordonnées (x) désigne la colonne, la seconde (y) désigne la ligne. Chacune de ces composantes est positive, 0 désignant la première colonne ou ligne. La case (0,0) se trouve dans le coin nord-ouest (haut-gauche) du plateau.

Ces conventions sont illustrées sur l'image ci-dessous qui montre le découpage du plateau en cases, ainsi que les coordonnées des quatre cases des coins.

Chaque case possède quatre voisines : une au nord (en haut), une à l'est (à droite), une au sud (en bas) et une à l'ouest (à gauche). Cela est vrai même pour les cases se trouvant dans les bords du plateau, leur voisines étant par convention celles du bord opposé. Cela revient à considérer que le plateau est un tore.

Par exemple, les quatre cases voisines de la case (0,0) sont :

1. la case (0,12) au nord,
2. la case (1,0) à l'est,
3. la case (0,1) au sud,
4. la case (14,0) à l'ouest.

Au niveau de granularité le plus fin, chaque case du plateau est subdivisée en 16 lignes de 16 colonnes de sous-cases.

L'image ci-dessous montre le découpage en sous-cases des quatre cases du coin nord-ouest du plateau, ainsi que les coordonnées des sous-cases aux quatre coins. Attention, étant donné que le plateau n'est pas montré en entier, la sous-case dans le coin bas-droite de l'image n'est pas la sous-case bas-droite du plateau. Cette dernière a les coordonnées (239,207).

La sous-case se trouvant à 8 lignes et 8 colonnes du coin nord-ouest de la case la contenant est définie comme étant la sous-case centrale de sa case, même si elle ne se trouve bien entendu pas exactement au centre. Sur l'image ci-dessus, les sous-cases centrales des quatre cases visibles sont coloriées en jaune.

Tout comme les cases, les sous-cases possèdent chacune exactement quatre voisines, une dans chaque direction.

Il est parfois utile d'ordonner les cases du plateau en une séquence linéaire. Il existe un très grand nombre de manières d'ordonner les cases en une séquence linéaire, mais nous n'en utiliserons que deux dans ce projet :

1. l'ordre de lecture,
2. l'ordre en spirale.

L'ordre de lecture consiste à partir de la case de coordonnées (0,0) et à poursuivre dans l'ordre dans lequel on lit les caractères sur une page, c-à-d de gauche à droite et de haut en bas. En informatique, cette manière d'ordonner les éléments d'un tableau bidimensionnel est souvent appelé row-major order, terminologie que nous utiliserons ici.

L'ordre en spirale consiste à partir de la case de coordonnées (0,0) puis à continuer en spirale, en commençant par la première ligne.

Ces deux manières d'ordonner les cases sont présentées dans la figure ci-dessous pour un petit plateau de 3 lignes de 4 colonnes chacune. Le numéro inscrit dans chaque case correspond à son index dans l'ordre illustré, la première case ayant l'index 0.

L'énumération Direction du paquetage ch.epfl.xblast, publique, définit les quatre directions utilisées dans le jeu, à savoir (dans l'ordre) :

1. N, pour nord,
2. E, pour est,
3. S, pour sud,
4. W, pour ouest (west en anglais).

Cette énumération définit de plus les méthodes suivantes :

• Direction opposite(), qui retourne la direction opposée de celle à laquelle on l'applique (S pour N, W pour E, etc.),
• boolean isHorizontal(), qui retourne vrai si et seulement si la direction à laquelle on l'applique est horizontale à l'écran (E ou W),
• boolean isParallelTo(Direction that), qui retourne vrai si et seulement si la direction à laquelle on l'applique est parallèle à la direction that (une direction n'est parallèle qu'à elle-même et à sa direction opposée).

La classe Cell du paquetage ch.epfl.xblast, publique, finale et immuable, représente une case. Elle possède plusieurs attributs publics et statiques. Les trois premiers d'entre eux, de type int, donnent des informations concernant les dimensions du plateau :

• COLUMNS, le nombre de colonnes du plateau (15),
• ROWS, le nombre de lignes du plateau (13),
• COUNT, le nombre total de cases du plateau (le produit de COLUMNS et ROWS).

Les deux attributs suivants sont des tableaux dynamiques de cases, de type List<Cell> (et non pas ArrayList<Cell>, pour une raison expliquée plus bas), contenant la totalité des cases du plateau, ordonnées selon les ordres décrits précédemment :

• ROW_MAJOR_ORDER, la totalité des cases du plateau en ordre de lecture,
• SPIRAL_ORDER, la totalité des cases du plateau en ordre spirale.

La technique à utiliser pour initialiser ces attributs est décrite plus bas, de même que le type List.

En plus de ces attributs statiques, la classe Cell offre un unique constructeur publique :

• Cell(int x, int y), qui construit la case avec les coordonnées x et y données ; des valeurs quelconques sont acceptées pour les coordonnées, mais elles sont normalisées avant d'être stockées, c-à-d ramenées à un entier compris entre 0 et 14 (inclus) pour x, et entre 0 et 12 (inclus) pour y (voir plus bas).

Finalement, la classe Cell offre les méthodes publiques suivantes :

• int x(), qui retourne la coordonnée x normalisée de la case,
• int y(), qui retourne la coordonnée y normalisée de la case,
• int rowMajorIndex(), qui retourne l'index de la case dans l'ordre de lecture,
• Cell neighbor(Direction dir), qui retourne la case voisine, dans la direction donnée ; sachant que le plateau de jeu est (conceptuellement) torique, cette voisine existe toujours.
• boolean equals(Object that), qui redéfinit la méthode equals de Object et retourne vrai si et seulement si l'objet that est une case et ses coordonnées normalisées sont identiques à celles de la case réceptrice,
• String toString(), qui redéfinit la méthode toString de Object et retourne une représentation textuelle de la case, constituée de ses coordonnées entre parenthèses, p.ex. (14,12) pour la case du coin sud-est.

La redéfinition de la méthode toString n'est pas indispensable, mais peut faciliter le déboguage et les tests.

Notez que cette classe n'est pas complète, il lui manque encore une redéfinition de la méthode hashCode. Il vous sera demandé de l'ajouter dans une étape ultérieure, une fois que son utilité aura été étudiée dans le cours.

La classe SubCell du paquetage ch.epfl.xblast, publique, finale et immuable, représente une sous-case. Elle offre une unique méthode publique et statique :

• SubCell centralSubCellOf(Cell cell), qui retourne la sous-case centrale de la case donnée.

En plus de cette méthode statique, la classe SubCell offre le constructeur public suivant :

• SubCell(int x, int y), qui construit la sous-case de coordonnées x et y données ; comme pour les cases, des valeurs quelconques sont acceptées pour ces coordonnées, mais elles sont normalisées avant d'être stockées, en ramenant la coordonnée x à un entier compris entre 0 et 239, et la coordonnée y à un entier compris entre 0 et 207.

Cette classe possède de plus les méthodes publiques suivantes :

• int x(), qui retourne la coordonnée x normalisée de la sous-case,
• int y(), qui retourne la coordonnée y normalisée de la sous-case,
• int distanceToCentral(), qui retourne la distance de Manhattan à la sous-case centrale la plus proche (voir plus bas),
• boolean isCentral(), qui retourne vrai si et seulement si la sous-case est une sous-case centrale,
• SubCell neighbor(Direction d), qui retourne la sous-case voisine, dans la direction donnée ; comme pour les cases, cette voisine existe toujours,
• Cell containingCell(), qui retourne la case contenant cette sous-case.
• boolean equals(Object that), qui redéfinit la méthode equals de Object et retourne vrai si et seulement si l'objet that est une sous-case et ses coordonnées normalisées sont identiques à celles de la sous-case réceptrice,
• String toString(), qui redéfinit la méthode toString de Object et retourne une représentation textuelle de la sous-case, constituée de ses coordonnées entre parenthèses, p.ex. (239,207) pour la sous-case du coin sud-est.

Comme pour la classe des cases, il faudra ultérieurement ajouter une redéfinition de la méthode hashCode à la classe des sous-cases.

Pour vous aider à démarrer ce projet, nous vous fournissons exceptionnellement une archive Zip contenant des tests unitaires JUnit pour cette étape.

Pour pouvoir utiliser ces tests, il vous faut tout d'abord les importer dans votre projet en suivant les indications d'importation d'archive Zip dans Eclipse, puis ajouter la bibliothèque JUnit à votre projet, en suivant les explications à ce sujet.

Attention : nous ne garantissons pas l'exhaustivité de ces tests et nous nous réservons le droit d'utiliser des tests plus complets que ceux-ci pour noter votre projet.

En plus des tests unitaires, l'archive ci-dessus contient un fichier nommé NameCheck01.java. Les méthodes de la classe qu'il définit font référence à la totalité des noms des classes et méthodes de cette étape. Cela vous permet de vérifier que vous avez correctement nommé les différentes entités qu'il vous est demandé de programmer. Cela est très important, car la moindre faute dans un nom nous empêcherait d'exécuter nos tests unitaires lors du rendu testé de la mi-semestre.

Nous vous fournirons de tels fichiers pour toutes les étapes jusqu'au rendu testé, et il vous faut penser à vérifier qu'Eclipse en signale aucune erreur dans l'un de ces fichiers avant de faire un rendu, faute de quoi celui-ci se verrait refusé par notre système.

Une fois les tests exécutés avec succès, il reste à documenter la totalité des entités publiques (classes, attributs et méthodes) définies dans cette étape, au moyen de commentaires Javadoc. Vous pouvez écrire ces commentaires en français ou en anglais, en fonction de votre préférence, mais vous ne devez utiliser qu'une seule langue pour tout le projet.

Les commentaires Javadoc sont des commentaires structurés que l'on peut attacher aux différentes entités d'un programme (classes, interfaces, attributs et méthodes). On les reconnaît au fait qu'ils commencent par une barre oblique suivie de deux astérisques (/**).

Les commentaires Javadoc peuvent inclure des étiquettes (tag), qui commencent par un arobas (@). Même s'il existe de nombreuses étiquettes, les plus importantes sont :

1. L'étiquette @author, qui est suivie du nom d'un des auteurs de la classe ou interface à laquelle elle est attachée. Peut apparaître plusieurs fois s'il y a plus d'un auteur.
2. L'étiquette @param, qui est suivie du nom d'un paramètre de l'entité à laquelle on l'attache (méthode ou constructeur) et d'une description de la signification de ce paramètre.
3. L'étiquette @throws, qui est suivie du nom d'une exception qui peut être levée par la méthode à laquelle on l'attache et d'une description des cas dans lesquels elle est levée.
4. L'étiquette @return, qui est suivie d'une description de la valeur retournée par la méthode à laquelle on l'attache.

Pour ce projet, vous avez l'obligation de lister la totalité des auteurs de chaque classe, interface ou énumération publique que vous rendez. Le prénom et le nom de chaque auteur doit être suivi de son numéro SCIPER entre parenthèses.

Pour illustrer l'utilisation des différentes étiquettes mentionnées plus haut, voici ce à quoi la documentation d'une classe modélisant un nombre rationnel pourrait ressembler :

/**
 * Un nombre rationnel.
 *
 * @author Marie Durand (654321)
 * @author Jean Dupond (123456)
 */
public final class Rational {
  private final int numerator, denominator;

  /**
   * Construit un nombre rationnel avec le numérateur
   * et le dénominateur donnés.
   *
   * @param numerator
   *            le numérateur
   * @param denominator
   *            le dénominateur (doit être non nul)
   * @throws IllegalArgumentException
   *             si le dénominateur est nul
   */
  public Rational(int numerator, int denominator) {
    if (!(denominator != 0))
      throw new IllegalArgumentException();
    this.numerator = numerator;
    this.denominator = denominator;
  }

  /**
   * Retourne le numérateur de ce nombre rationnel.
   * @return le numérateur de ce nombre rationnel
   */
  public int numerator() {
    return numerator;
  }

  // … méthodes
}

Deux commandes Eclipse sont d'une grande aide lorsqu'on rédige des commentaires Javadoc :

1. Dans le menu Source, l'entrée Generate Element Comment permet de générer un squelette de commentaire Javadoc pour l'élément sous le curseur.
2. Dans le menu Source, l'entrée Format Element permet de reformatter l'élément sous le curseur. Lorsqu'on l'utilise dans un commentaire Javadoc, celui est reformatté de manière plaisante.