SAÉ - Développement IHM

Préambule :

• Tout ce tutoriel est basé sur un ordinateur avec une distribution type debian/ubuntu, un SDK Java du type openjdk+openjfx 11/17, et l'IDE Intellij IDEA.
• Ces hypothèses sont valables notamment pour les machines du département.
• Si vous utilisez votre propre ordinateur sous windows/mac, les procédures d'installation logicielle seront relativement semblables mais avec des différences notables, par exemple dans les chemins d'accès aux éléments installés.
• De même, si vous installez un sdk ou une version de javaFx différente, vous vous exposez à des incompatibilités avec le framework boardifier. 

• Pour suivre ce tutoriel, il faut d'abord suivre celui qui implémente le jeu en mode console : Tutoriel 1 : créer un jeu de plateau en mode texte avec boardifier-console
• En effet, seules les différences dans la modélisation et l'implémentation des classes des parties modèle, vue et contrôleur sont abordées ici.
• Comme on va le constater, ces différences ne sont pas très importantes, et elles concernent principalement :
  • la classe principale du jeu,
  • les classes de la partie vue permettant de représenter visuellement les jetons et le plateau de jeu,
  • la gestion des interactions avec la souris.
• A côté de cela, des modifications mineures doivent être faites sur les classes du modèle, notamment pour tenir compte de la sélection d'un pion avec la souris.

L'objectif de de tutoriel est de présenter le développement d'un jeu de plateau grâce à Boardifier. C'est un framework de développement Java basé sur la bibliothèque graphique JavaFx. C'est le "grand frère" de boardifier-console, car il en reprend les principes essentiels, notamment l'utilisation du paradigme MVC strict, mais avec des classes basées sur Javafx pour la mise en place des parties vue et contrôle. Malgré cela, la partie modèle est identique, ainsi qu'environ 80% du code des classes de contrôle et de vue est identique. C'est pourquoi il est relativement aisé de passer d'une version console à une version graphique, puisque tout le côté fonctionnel peut être repris.

Pour suivre ce tutoriel, il faut donc d'abord suivre celui qui implémente le jeu en mode console : Tutoriel 1 : créer un jeu de plateau en mode texte avec boardifier-console.

Dans la suite de cet article, seules les différences dans la modélisation et l'implémentation des classes des parties modèle, vue et contrôleur sont abordées. Comme on va le constater, ces différences ne sont pas très importantes, et elles concernent principalement :

• la classe principale du jeu,
• les classes de la partie vue permettant de représenter visuellement les jetons et le plateau de jeu,
• la gestion des interactions avec la souris.

A côté de cela, des modifications mineures doivent être faites sur les classes du modèle, notamment pour tenir compte de la sélection d'un pion avec la souris.

Avant de commencer le développement, il convient d'aborder les principales différences entre les deux versions du framework boardifier.

Pour la partie modèle, les classes sont identiques à l'exception de la méthode update() de GameElement dont les paramètres changent : update(double width, double height, GridGeometry gridGeometry).  La valeur de ces paramètres est directement fournit par le contrôleur général, lorsque le modèle est mis à jour à chaque frame. Ces 3 paramètres correspondent à la taille en pixel de l'élément, et un objet donnant la géométrie visuelle de la grille (taille des cellules en pixel notamment) si l'élément est dans une grille. Normalement, en MVC le modèle n'a pas accès aux informations relatives au visuel mais il y a des exceptions. Par exemple, s'il faut déplacer un élément dans l'espace, il est parfois nécessaire de connaître sa forme et/ou la forme de la grille dans laquelle il se trouve pour savoir si le déplacement est possible. Dans "The Hole", ce genre de cas n'existe pas, mais comme boardifier est fait pour être général, ces exceptions sont prévues.

Pour la partie vue, presque toutes les classes sont différentes puisque c'est Javafx qui est utilisé pour faire le rendu visuel. En revanche, les principes généraux de création du visuel ne changent pas beaucoup par rapport à boardifier-console :

• La vue générale est représentée par la classe View, que l'on va instancier dans la classe principale (celle de main() ), en fournissant le modèle en paramètre. On peut cependant créer une sous-classe, afin de définir une barre de menu spécifique pour le jeu à implémenter.
• Le "panneau" principal de dessin, sur lequel vont être placés les éléments visuels (les looks) est représenté par la classe RootPane, qui hérite de la classe Javafx Pane. Le contenu par défaut du RootPane est un fond gris et un texte basique, qui peuvent servir de panneau d'introduction, avant de lancer une partie. Si l'on veut changer ce contenu par défaut, on crée une sous-classe et on redéfinit la méthode createDefaultGroup()​ (cf. ci-dessous).
• Les looks sont définis grâce aux sous-classes existants de ElementLook, ou bien en en héritant. La différence est que les looks sont créés grâce aux classes Javafx telles que Rectangle, Circle, Text, ...
• Pour chaque stage du jeu, on crée une sous-classes de GameStageView, afin de créer et stocker les éléments visuels (les looks) du stage. La différence est qu'il faut créer des looks avec des tailles en pixels au lieu de caractères.

 Pour la partie contrôle, il y a également des différences notables avec le mode console, notamment afin de gérer les mouvements des éléments graphiques et les interactions utilisateur grâce au clavier/souris. De ce fait, on a :

• un contrôleur de l'animation : c'est lui qui va contrôler le temps qui passe et qui va régulièrement demander au contrôleur global de "mettre à jour" le jeu. Ce contrôleur n'a jamais besoin d'être redéfini.
• un contrôleur du clavier : par défaut il ne fait rien, mais on peut créer une sous-classe pour détecter l'appui sur certaines touches.
• un contrôleur de souris : par défaut il ne fait rien, mais on peut créer une sous-classe pour faire des actions en fonction de clic ou déplacement souris.
• un contrôleur des actions : par défaut il ne fait rien, mais on peut créer une sous-classe pour faire des actions lorsqu'un élément graphique de javafx (bouton, case à cocher, menu, ...) est cliqué.
• un contrôleur global : il contient presque tout ce qui est nécessaire pour mettre à jour le jeu, mais il faut obligatoirement créer une sous-classe pour pouvoir instancier les sous-contrôleurs énoncés ci-dessus, et définir ce qui se passe quand un joueur a fini son tour, ou bien quand un stage est terminé.

La dernière différence concerne les animations et la classe ActionPlayer. Elle est différente du mode console, puisqu'elle ajoute la possibilité de "jouer" des animations à l'écran, pour représenter une action de jeu. 

La super classe (dans le modèle) représentant les animations est Animation mais ce sont ses sous-classes qui sont réellement utilisables.

Animation ne contient que ce qui est nécessaire à toutes les animations, c.a.d des attributs représentant la durée de l'animation, une liste d'objets AnimationStep contenant les "pas" de l'animation, et un callback qui sera appelé à la fin de l'animation (par défaut ne fait rien).

AnimationStep est une simple "enveloppe" pour une liste de nombres à virgule. Les valeurs que l'on met dans cette liste dépend entièrement de ce dont on a besoin comme information pour représenter l'animation. Par exemple, pour une animation du type mouvement, cette liste va contenir les coordonnées x,y de l’élément à déplacer à un pas donné le l'animation. Si on veut faire changer l'apparence d'un élément, la liste va plutôt contenir l'indice d'une des apparences possible de l'élément (cf. DiceElement).

A l'heure actuelle, gamifier ne propose qu'un nombre limité d'animation, basées sur un changement soit de position, soit d'apparence. Il y a ainsi :

• MoveAnimation : prend en paramètre des coordonnées de départ et d'arrivée dans l'espace. La liste d'AnimationStep ne contiendra que 2 pas, avec ces coordonnées. Cela provoque une animation de type téléportation.
• LinearMoveAnimation  : idem que MoveAnimation mais en spécifiant un vitesse ou un temps de déplacement. La liste d'AnimationStep est remplie avec autant de pas que nécessaire pour respecter le temps ou la vitesse. Chaque pas contient des coordonnées dans l'espace, qui sont sur la ligne reliant le point d'arrivée et de départ.
• FaceAnimation : prend en paramètre la liste des indices d'apparence que doit prendre l'élément., ainsi que le temps en ms entre chaque changement d'indice.
• CyclicFaceAnimation : idem que FaceAnimation mais en faisant une boucle dont la longueur est donnée en paramètre.

Du fait de la présence d'une interface graphique, il y a plus de besoins que dans le jeu en mode console. Après discussion avec nous-même, on établit le scénario suivant :

• lancement de l'application => la fenêtre principale n'affiche qu'un panneau d'introduction,
• lancement d'un partie, avec un joueur humain contre un joueur ordinateur,
• fin de partie => affichage d'une boite de dialogue pour dire qui est le gagnant, et qui permet de quitter le jeu ou débuter d'une nouvelle partie.

Parallèlement, on choisit de maquetter le jeu comme suivant :

• la fenêtre principale contient une barre de menu, avec un unique menu contenant les items : "Start game", "Introduction", "Exit".
• le panneau d'introduction contient seulement le texte "The Hole".
• la boite de dialogue de fin de partie contient un texte signalant qui gagne ou bien si la partie est nulle, ainsi que 2 boutons intitulés "Start Game" et "Exit"
• le panneau de jeu est globalement divisé comme ci-dessous :

Le scénario d'une partie est le suivant :

• le joueur humain est le premier joueur et reçoit les pions noirs, l'ordinateur les rouges.
• lorsque c'est le tour de l'humain, il doit d'abord sélectionner un de ses pions en cliquant dessus. Le pion change d'apparence pour signaler qu'il est sélectionné.
• si ce pion peut être placé, les cases possibles changent d'apparence.
• si un pion est sélectionné et que le joueur re-clique dessus, il est désélectionné. Si c'est un autre pion, il ne se passe rien.
• si un pion est sélectionné et que le joueur clique sur une case possible, le pion est déplacé dans cette case, via une animation graphique.
• c'est ensuite au joueur ordinateur de jouer, qui décider quel pion jouer et où le mettre. La sélection de ce pion n'est pas visible. Seule l'animation de déplacement doit être faite.

A partir de ces élément, on peut établir une liste synthétique des fonctionnalités et de sous-fonctionnalités dont elles dépendent :

• lancer une partie,
• quitter le jeu,
• revenir au panneau d'introduction,
• construire le visuel du panneau d'introduction, du panneau de jeu, du dialogue final,
• sélectionner un pion :
  • trouver la liste des éléments de jeu contenant les coordonnées d'un clic souris,
  • déterminer la liste des cases possibles pour ce pion,
  • faire changer l'apparence d'un pion pour indiquer qu'il est (dé)sélectionné.
  • faire changer l'apparence d'une case de la grille pour indiquer que c'est une case de destination (im)possible.
• désélectionner un pion :
  • faire changer l'apparence d'un pour indiquer qu'il est (dé)sélectionné.
  • faire changer l'apparence d'une case de la grille pour indiquer que c'est une case de destination (im)possible.
• mettre un pion dans une case possible :
  • trouver la liste des éléments de jeu contenant les coordonnées d'un clic souris,
  • trouver dans la grille quelle case est cliquée,
  • lancer une animation qui déplace visuellement le pion vers sa case de destination.
• calculer un déplacement de pion (pour l'ordinateur)
• détecter la fin de partie,
• calculer le résultat de la partie.

Nous allons voir que grâce à Boardifier, l'essentiel de ces fonctionnalités sont écrites, soit totalement, soit presque entièrement. Qui plus est, si on réutilise le code du jeu en mode console, les trois dernières sont également déjà écrites.

• Le plus simple est d'utiliser la solution du jeu en mode console comme base.
• Il suffit de copier les sources de cette solution dans un nouveau répertoire, puis de remplacer le répertoire boardifier avec le contenu de l'archive du framework boardifier : [ télécharger ]

Exemple (en supposant que les sources du jeu en mode console se trouvant dans ~/code/Java/HoleConsole) :

cd ~/code/Java
mkdir Hole
cd Hole
cp -r ../HoleConsole/src .
cd src
rm -rf boardifier
// télécharger l'archive boardifier.tgz et la placer dans le rep. courant.
tar zxf boardifier.tgz

• Il suffit ensuite de créer un projet Idea, comme indiqué dans les tutoriels.

Les modifications des classes du modèle sont relativement limitées et concernent seulement 3 classes :

• HoleStageFactory : modifier les coordonnées des éléments en pixels, et créer un TextElement pour représenter le nom du joueur courant dans la scène (contrainte non présente dans la version console)
• HoleStageModel : ajouter tout ce qui concerne le TextElement (attribut +  getter/setter), et ce qui concerne la sélection d'un pion (état de la sélection & définition du callback quand on sélectionne un pion)

Remarque : pour fournir à boardifier le callback utilisé lors de la sélection d'un pion, il suffit d'appeler la méthode onSelectionChange() dans setupCallbacks() (même principe qu'en mode console avec onPutInGrid() ). Cette méthode prend en paramètre le callback, sous la forme d'une fonction lambda. Dans le cas présent, il suffit de vérifier si un pion est sélectionné. Si oui, on calcule les case atteignables en fonction du pion sélectionné, et sinon on remet à zéro les cases atteignables :

       onSelectionChange( () -> {
            // get the selected pawn if any
            if (selected.size() == 0) {
                board.resetReachableCells(false);
                return;
            }
            Pawn pawn = (Pawn) selected.get(0);
            board.setValidCells(pawn.getNumber());
        });

• Pawn : redéfinir la méthode update() afin de jouer l'animation si elle existe.

Remarque : dans un jeu où les seules animations consistent à bouger des éléments (pions, cubes, ...), on peut utiliser le code "universel" suivant pour jouer une animation de déplacement linéaire :

    public void update(double width, double height, GridGeometry gridGeometry) {
        // if must be animated, move the pawn
        if (animation != null) {
            AnimationStep step = animation.next();
            if (step != null) {
                setLocation(step.getInt(0), step.getInt(1));
            }
            else {
                animation = null;
            }
        }
    }

Toutes ces modifications sont relativement simples à mettre en place et se retrouvent dans la solution téléchargeable en fin d'article.

// do a cast get a variable of the real type to get access to the attributes of HoleStageModel
HoleStageModel stage = (HoleStageModel)model.getGameStage();
HoleBoard board = stage.getBoard(); // get the board
...
// create action list. After the last action, it is next player's turn.
ActionList actions = new ActionList(true);
// get the dest. cell center in space.
GridLook look = (GridLook) control.getElementLook(board);
Coord2D center = look.getRootPaneLocationForCellCenter(rowDest, colDest);
// create the move action
GameAction move = new MoveAction(model, pawn, "holeboard", rowDest, colDest, AnimationTypes.MOVE_LINEARPROP, center.getX(), center.getY(), 10);
actions.addSingleAction(move);

...
public class PawnLook extends ElementLook {
    private Circle circle;
    public PawnLook(int radius, GameElement element) {
        super(element);
        Pawn pawn = (Pawn)element; // unless you did somthing stupid in HoleStageView, it IS really a Pawn instance !
        circle = new Circle();
        circle.setRadius(radius);
        if (pawn.getColor() == Pawn.PAWN_BLACK) {
            circle.setFill(Color.BLACK);
        }
        else {
            circle.setFill(Color.RED);
        }
        circle.setCenterX(radius);
        circle.setCenterY(radius);
        // add the circle to the look
        addShape(circle);
        // to fulfill ...
    }
    @Override
    public void onSelectionChange() {
        // to fulfill ...
    } 
    public void onChange() { }
}

...
public class HoleStageView extends GameStageView {
    public HoleStageView(String name, GameStageModel gameStageModel) {
        super(name, gameStageModel);
        width = 650;
        height = 450;
    }

    @Override
    public void createLooks() {
        HoleStageModel model = (HoleStageModel)gameStageModel;

        addLook(new HoleBoardLook(320, model.getBoard()));
        addLook(new PawnPotLook(120,420,model.getBlackPot()));
        ... // to fulfill        
}

...
public class HoleRootPane extends RootPane {
    ...
    @Override
    public void createDefaultGroup() {
        Rectangle frame = new Rectangle(600, 100, Color.LIGHTGREY);
        Text text = new Text("Playing to The Hole");
        text.setFont(new Font(15));
        text.setFill(Color.BLACK);
        text.setX(10);
        text.setY(50);
        // put shapes in the group
        group.getChildren().clear();
        group.getChildren().addAll(frame, text);
    }
}

...
public class HoleView extends View {

    private MenuItem menuStart;
    private MenuItem menuIntro;
    private MenuItem menuQuit;

    public HoleView(Model model, Stage stage, RootPane rootPane) {
        super(model, stage, rootPane);
    }

    @Override
    protected void createMenuBar() {
        menuBar = new MenuBar();
        Menu menu1 = new Menu("Game");
        menuStart = new MenuItem("New game");
        menuIntro = new MenuItem("Intro");
        menuQuit = new MenuItem("Quit");
        menu1.getItems().add(menuStart);
        menu1.getItems().add(menuIntro);
        menu1.getItems().add(menuQuit);
        menuBar.getMenus().add(menu1);
    }
    ...
}

public void nextPlayer() {
    // use the default method to compute next player
    model.setNextPlayer();
    // get the new player
    Player p = model.getCurrentPlayer();
    // change the text of the TextElement
    HoleStageModel stageModel = (HoleStageModel) model.getGameStage();
    stageModel.getPlayerName().setText(p.getName());
    if (p.getType() == Player.COMPUTER) {
        System.out.println("COMPUTER PLAYS");
        HoleDecider decider = new HoleDecider(model,this);
        ActionPlayer play = new ActionPlayer(model, this, decider, null);
        play.start();
    }
}

...
public class HoleControllerAction extends ControllerAction implements EventHandler<ActionEvent> {
    // to avoid lots of casts, create an attribute that matches the instance type.
    private HoleView holeView;

    public HoleControllerAction(Model model, View view, Controller control) {
        super(model, view, control);
        // take the view parameter to define a local view attribute with the real instance type, i.e. HoleView.
        holeView = (HoleView) view;
        // set handlers dedicated to menu items
        setMenuHandlers();
        ...
    }

    private void setMenuHandlers() {
        ...
        // set event handler on the MenuQuit item
        holeView.getMenuQuit().setOnAction(e -> {
            System.exit(0);
        });
    }
    ...
}