CoreWar - Documentation Technique

Documentation Technique

Avant-Propos

Le projet est développé sous Visual J++ version 1.1. Mais je n'utilise aucune spécificité de Microsoft, le code doit donc être compatible avec toutes les VM Java. Enfin j'espère, car certaines classes ont été générées automatiquement par Visual J++. Si vous rencontrez des problèmes d'interface (car c'est de ces classes dont il s'agit), merci de m'avertir.

Cette documentation technique est un peu maigre, il s'agit plutôt d'un guide de lecture des fichiers sources (qui sont par ailleurs très commentés).

Les Classes

On peut séparer les classes du projet en deux catégories : les classes relatives à l'interface du jeu (peu intéressantes) et les classes relatives à un ordinateur virtuel.

Les classes relatives à l'interface

DialogLayout / implements LayoutManager
Classe générée par Visual J++ utilisée par d'autres classes générées permettant de gérer le positionnement des contrôles dans les fenêtres.

CtrlLoadSource
DlgLoadSource / extends Frame
CtrlLoadSource a été générée par Visual J++ et elle utilise DialogLayout. Cette classe doit être utilisée dans une Frame (ou classe dérivée). Elle gère les contrôles se trouvant dans la fenêtre de chargement d'un source.
DlgLoadSource utilise CtrlLoadSource. Cette classe gère la fenêtre de chargement de source.

CtrlMainWindow
CoreWarFrame / extends Frame
CoreWar / extends Applet implements Runnable
CtrlMainWindow a été générée par Visual J++ et elle utilise DialogLayout. Elle gère les contrôles se trouvant dans la fenêtre principale de l'Applet.
L'applet peut également fonctionner en dehors du navigateur, dans ce cas CoreWarFrame est la fenêtre principale de l'application.
CoreWar est la classe exécutable du projet : elle contient la fonction main(...) qui est appelée quand le programme est exécuté en dehors d'un navigateur (ou AppletViewer) et elle dérive de Applet, ce qui lui permet d'être insérée dans une page Web. La classe CoreWar utilise CtrlMainWindow. L'applet contient une CPU ainsi qu'un MemoryViewer. Elle se contente de gérer la mise à jour de l'affichage et d'envoyer régulièrement des tops d'horloge à sa cpu.

MemoryViewer / extends Canvas
Première classe intéressante : MemoryViewer permet de visualiser le contenu d'une Memory.

Les classes relatives à un ordinateur virtuel

Memory
Un objet Memory est composé d'un certain nombre de cases contenant des Instructions. Memory fonctionne comme une mémoire circulaire, c'est-à-dire que la case 0 est à côté de la case n-1, où n est le nombre de cases. Il est donc impossible de lire en dehors de la mémoire et tous les tests de validité sont effectués par la classe : ceci sécurise et simplifie énormément le code. Il n'y a pas besoin de tester la validité de i avant de lire ou écrire en case i. Memory corrige la valeur i automatiquement.

Process
Un objet Process représente un processus qui s'exécute dans une CPU. Process contient un pointeur vers sa prochaine instruction et l'exécute quand on lui donne la main. C'est également Process qui gère son attente sur les instructions. La logique voudrait que ce soit la CPU qui fasse ce boulot, et ce sera sans doute le cas dans une prochaine version.

CPU
Une CPU est composée d'une Memory de n cases et d'une liste de Process qui s'exécutent pacifiquement (!) dans cette Memory. Elle dispose également d'un compilateur qui lui permet de transformer un code source en assembleur en code machine. Quand la CPU reçoit un top d'horloge, elle exécute la prochaine instruction du prochain processus actif puis passe au processus suivant.

Instruction
Classe abstraite (non instanciable) servant de base à toutes les autres instructions. Quand on ajoute une nouvelle instruction au programme, elle doit obligatoirement dériver de Instruction et en redéfinir ses méthodes abstraites. Instruction contient une méthode statique createInstruction qui permet de créer une instruction en fonction du nom passé en paramètre. createInstruction existe en trois versions : création d'une instruction sans paramètres, avec un paramètre et avec deux paramètres. Ainsi, l'appel de Instruction.createInstruction("DAT",0,0) crée un objet DAT 0. Le compilateur de la CPU utilise bien entendu createInstruction. La méthode createInstruction n'a pas à être modifiée lorsque l'on ajoute une nouvelle instruction au programme.

DAT
MOV
ADD, SUB, MUL, DIV, MOD, MIN
AND, OR, XOR, NOT
JMP, JMZ, JMG, DJZ
CMP
RND
FORK, KILL / extend Instruction
Toutes ces classes définissent le comportement des différentes instructions composant le jeu. Elles dérivent toutes de Instruction. Toutes les explications sur le fonctionnement d'une classe dérivée de Instruction se trouvent dans le modèle d'instruction. Utilisez ce modèle si vous souhaitez ajouter une instruction au programme. Une Instruction s'exécute toujours dans le cadre d'un Process et c'est l'Instruction qui plante le Process en cas d'erreur. C'est également l'Instruction qui positionne le pointeur vers la prochaine instruction du Process.

ERR / extends DAT
ERR est en fait un DAT 0 en erreur. ERR sert uniquement à rendre le programme plus lisible.

Les Fichiers

A l'exception de DlgLoadSource qui se trouve dans CoreWar.java, il y a un .java par classe. Le nom du .java est identique au nom de la classe. Le fichier new_instruction.txt contient le modèle à remplir lors de la création d'une nouvelle Instruction (voir ci-dessous).

Création d'une nouvelle Instruction

Pour ajouter une nouvelle instruction au jeu, il suffit de remplir correctement le modèle. Pas besoin de modifier le reste ! Une petite compilation, et l'instruction est directement utilisable. Elle doit avoir un nom en MAJUSCULES, même si dans les sources ACW (Assembleur CoreWar) on peut écrire en minuscules.

[NicoLaB] [CoreWar]