Solarus Wiki

A wiki for the Solarus engine community

Outils pour utilisateurs

Outils du site


fr:tutorial:getting_started

Chap. 2Sommaire

Chapitre 1 - Mise en place

Bienvenue dans ce tutoriel vous permettant de développer depuis le début votre propre jeu avec le moteur Solarus ! Dans cette première partie, nous allons voir comment configurer le moteur pour lancer l'écran titre de votre jeu. Cet écran titre se composera uniquement d'une image.

Prérequis

Vous devez avoir Java (minimum Java 7) installé sur votre machine pour pouvoir faire fonctionner l'éditeur de quête. Sachez que cet éditeur subit une refonte et qu'il sera totalement indépendant de java d'ici quelques temps. Le moteur n'a besoin de rien de particulier pour fonctionner, les diverses librairies dont il dépend étant incluses lors du téléchargement ou de l'installation selon votre système.

Pour créer une quête, vous aurez à programmer en langage Lua vos scripts de maps et de menus. Cette série de tutoriels vous expliquera le langage Lua au fur et à mesure, et les fonctions Lua disponibles dans Solarus, mais il est tout de même nécessaire de connaître des notions de base de programmation (peu importe le langage). Si vous souhaitez vous initier au language Lua, nous vous recommandons le livre Programming in Lua.

Téléchargement du moteur

Dans un premier temps, vous devez télécharger le moteur Solarus. À l'heure où nous écrivons ce tutoriel, la dernière version disponible est la version 1.0.4, mais vous pourrez suivre le tutoriel même avec une version plus récente. Dans les numéros de versions, nous ignorerons la plupart du temps le troisième chiffre car il ne n'introduit que de corrections de bugs et jamais d'incompatibilités. On parlera donc de la version 1.0.

Solarus 1.0 possède encore quelques éléments codés en dur, c'est-à-dire que vous ne pouvez pas modifier. Il s'agit essentiellement de la boîte de dialogue et de l'écran de game-over. Ces éléments pourront être personnalisés à partir de la version 1.1, qui n'est pas encore sortie au moment d'écrire ces lignes. De plus, certains fichiers devront être modifiés à la main car l'éditeur de quête ne permet pas encore de les éditer graphiquement. Cette série de tutoriels vous expliquera comment faire.

Lien de téléchargement du moteur Solarus.

Dans ce tutoriel, nous détaillons la marche à suivre si vous êtes sous Windows, mais la procédure est similaire sur tous les systèmes d'exploitation.

Les fichiers téléchargés sont au format archive et non pas exécutable. Extrayez cette archive où vous le souhaitez. Pour des raisons pratiques, le dossier utilisé dans ce tutoriel sera C:\Solarus. L'archive contient deux dossiers et les deux fichiers de licence/readme. Le premier dossier nommé solarus contient le moteur (un fichier exécutable). Le second nommé solarus_quest_editor contient l'éditeur de quêtes, un logiciel permettant de modifier les maps, les tilesets (ensembles de tuiles composant les maps), les sprites, bref tout ce qui aura trait à votre jeu.

Une fois les fichiers extraits, si vous essayez de lancer le jeu, une erreur se produit. En effet, le moteur a besoin d'un dossier spécifique pour pouvoir se lancer : un dossier nommé data contenant la quête elle-même. Le moteur a créé un fichier error.txt qui va vous aider dans votre développement. Ce fichier contient les messages d'erreurs qui se sont produits lors du dernier lancement du moteur. Ce fichier est très important et vous devrez apprendre à le lire.

Pour l'erreur actuelle, nous avons dans error.txt :

No quest was found in the directory '.'. To specify your quest's path, run: C:\Solarus\solarus.exe path/to/quest

Ce message signifie que comme vous n'avez pas indiqué de dossier de quête en lançant le jeu, le moteur a pris le par défaut le répertoire courant (représenté par un point “.”) mais n'a pas trouvé de dossier de quête, donc rien ne peut se lancer. Vous pourriez créer le dossier de quête à la main, mais ce serait un travail extrêmement long et fastidieux. C'est pour cela qu'existe fait le second dossier de l'archive, à savoir solarus_quest_editor.

Création de votre quête

Dans ce dossier, lancez le fichier commençant par solarus-editor. Ici, il va vous demander au démarrage le dossier “root” de votre projet, c'est-à-dire le dossier comprenant le dossier “data”, ce dernier contenant les fichiers de votre quête. Comme vous n'en avez pas encore, annulez cette fenêtre (cette fenêtre sera retirée de l'éditeur dans Solarus 1.1). Vous arrivez sur l'interface, plutôt vide pour l'instant, de Solarus Quest Editor, l'éditeur de quête. Faites QuestNew quest, et choisissez le dossier C:\Solarus\solarus où se trouve le moteur (pour des raisons pratique car souvenez-vous : il va chercher le dossier de quête dans le répertoire courant).

Comme vous pouvez le constater, l'éditeur vous indique que certains fichiers sont encore à faire/modifier à la main, mais ces fichiers seront directement créés dans les futures versions. Plus exactement, les sous-dossiers nécessaires au bon fonctionnement du jeu seront créés automatiquement à partir de la 1.1. Pour commencer, vous allez devoir modifier le fichier quest.dat. Il est pour l'instant rempli avec des informations par défaut.

Configuration de votre quête

Pour modifier le fichier quest.dat qui se trouve dans data avec votre éditeur de texte préféré (Notepad++ est très fortement conseillé). Ce fichier est un fichier de données utilisé par le moteur, la syntaxe ressemble beaucoup au Lua mais il s'agit bien d'un fichier de données et non de programmation. Voici le contenu du fichier lorsqu'il vient d'être créé par l'éditeur de quête :

quest{
  -- Format of your quest data files. You should not change this unless you
  -- know what you are doing.
  solarus_version = "1.0",
 
  -- Directory where your quest will write its savegames and setting files.
  -- It will be a subdirectory of '$HOME/.solarus/', automatically created by
  -- the engine. Its name should identify your quest, to avoid confusion with
  -- other Solarus quests that might also be installed on the user's machine.
  -- You must define it before you can use savegames or setting files.
  -- Uncomment the line below and set its value to the name of that directory:
  -- write_dir = "",
 
  -- Title of the window. You should probably put the title of your game here.
  title_bar = "A game made with Solarus. Edit quest.dat to change this title!",
}

Décryptons un peu ce fichier. Toutes les lignes qui commencent par --, ce sont des lignes dites de commentaire, c'est-à-dire qu'elles ne seront pas interprétées par le moteur. Autant dans les fichiers de configuration, les commentaires ne sont pas extrêmement utiles (car vous ne les modifierez pas souvent, et le moteur devrait à terme tous les gérer), autant dans vos fichiers de code vous pouvez, vous DEVEZ écrire des commentaires aussi souvent que possible pour expliquer votre état d'esprit, car lorsque vous écrivez du code qui vous semble logique à un instant T vu que vous y avez réfléchi pendant 3h, et que vous revenez sur ce code quelques mois plus tard pour faire une modification, si vous n'avez pas commenté ce code vous vous retrouvez à devoir repasser 3h à réfléchir sur le pourquoi vous avez abordé le problème sous cet angle. Mais dans ce fichier, les commentaires aident surtout les personnes venant de créer leurs quêtes à savoir ce qu'elles doivent faire.

La 4ème ligne indique la version du moteur qu'utilisera la quête, ici solarus_version = 1.0 signifie que le jeu sera compatible avec le moteur Solarus 1.0.

La ligne 12 est un commentaire, mais il faut le décommenter : c'est dans le dossier que vous mettrez que seront vos sauvegardes. Cela permet de faire plusieurs quêtes et d'empêcher les sauvegardes de s'écraser les unes les autres. Le nom que vous mettrez dans cette variable sera dans votre_dossier_utilisateur/.solarus/. Par exemple, sur Windows, si l'utilisateur connecté s'appelle John, et que le nom indiqué dans write_dir est “my_game”, les sauvegardes se trouveront dans C:\Users\John\.solarus\my_game. Sur Linux, ce sera dans ~/.solarus/my_game. Ce dossier est un dossier caché, n'oubliez donc pas de les afficher si vous souhaitez accéder au répertoire de sauvegarde. Pour ce tutoriel, nous allons écrire dans le dossier “tuto_solarus”.

A la ligne 15 se trouve le nom qui sera affiché dans la bar de titre du jeu. Mettons par exemple “Ma première quête !”. Sauvegardez le fichier et tentez de lancer le jeu. Si vous voyez des “?” se mettre à la place des accents, c'est que votre fichier a été sauvegardé au mauvais format. Tous les fichiers de données utilisés par Solarus doivent être encodés en UTF-8. Si vous êtes sur Notepad++, faites EncodageConvertir en UTF-8 (sans BOM). Le “sans BOM” est important, sinon vous aurez une fatale car un caractère invisible sera inséré au début du fichier. Notez que vous pourrez également changer le titre de cette fenêtre à tout moment dans le jeu grâce à une fonction spécifique. Ainsi, vous pouvez personnaliser le titre selon où se trouve le héros, etc. Vous remarquerez au fur et à mesure toute l'étendue du Lua.

Le fichier à la fin ressemble donc à ceci :

quest{
  -- Format of your quest data files. You should not change this unless you
  -- know what you are doing.
  solarus_version = "1.0",
 
  -- Directory where your quest will write its savegames and setting files.
  -- It will be a subdirectory of '$HOME/.solarus/', automatically created by
  -- the engine. Its name should identify your quest, to avoid confusion with
  -- other Solarus quests that might also be installed on the user's machine.
  -- You must define it before you can use savegames or setting files.
  -- Uncomment the line below and set its value to the name of that directory:
  write_dir = "tuto_solarus",
 
  -- Title of the window. You should probably put the title of your game here.
  title_bar = "Ma première quête !",
}

Comme vous avez pu le constater, le jeu se lance sur un écran noir, car votre quête est vide : elle vient juste d'être créée. La seule chose que vous avez changé, c'est où s'écrira les sauvegardes et quel titre aura votre jeu. Nous allons de ce pas lui faire un écran titre, histoire de l'habiller un peu.

Un écran-titre

Ce ne sera pas un vrai menu que nous allons faire, mais juste afficher une image pour commencer. Vous pouvez prendre n'importe quelle image que vous voulez pour ce faire. Dans notre cas nous allons prendre cette image. Pour cela, nous allons écrire nos premières lignes de programmation en Lua, mais juste avant copiez l'image que vous venez de télécharger dans data\sprites (il faut créer le dossier à la main pour la version 1.0, alors que la version 1.1 initialisera les dossiers à la création de la quête). Allez dans main.lua qui se trouve à côté de quest.dat. Voici le code qu'il contient :

-- This is the main Lua script of your project.
-- You will probably make a title screen and then start a game.
-- See the Lua API! http://www.solarus-games.org/solarus/documentation/
 
-- Below is just an example of quest that does almost nothing.
-- Feel free to change this!
function sol.main.on_started()
  -- This function is called when Solarus starts.
  print("Welcome to my quest.")
end
 
function sol.main.on_finished()
  -- This function is called when Solarus stops or is reset.
  print("See you!")
end

Décryptons encore une fois ce nouveau fichier. Les six premières lignes sont des commentaires générés par l'éditeur de quête à la création. Il y a ensuite deux fonctions : sol.main.on_started() et sol.main.on_finished(). Il faut savoir avant tout qu'en Lua, tout est tableau, et la syntaxe “quelquechose.untruc” signifie qu'on accède à l'élément “untruc” dans le tableau “quelquechose”. Ici, sol se réfère au moteur Solarus, qui contient plusieurs éléments dont main. Ce main va appeler des fonctions tout seul : au démarrage il va appeler on_started et lorsqu'on fermera le jeu, il va appeler on_finished.

Dans un premier temps, nous allons déclarer une variable locale dans le fichier, variable qui contiendra notre image. Ajoutez donc juste, en dehors des fonctions déjà existantes (donc par exemple après on_started vers la ligne 17) :

local title_img = sol.surface.create("title_img.png")

Que vient-on d'écrire ? On crée une variable appelée “title_img”, puis on crée une surface que l'on range dans cette variable. Pour créer la surface, on appelle la fonction sol.surface.create avec en paramètre le nom de l'image à charger. Le fait que cette variable soit en dehors de toute fonction fait qu'elle sera initialisée avant même l'appel du sol.main.on_started. Maintenant que l'on a notre image, on va pouvoir l'afficher. Pour cela, on va écrire une nouvelle fonction juste en-dessous de la création de la variable :

function sol.main:on_draw(screen)
  title_img:draw(screen)
end

A nouveau, expliquons un peu ce que l'on vient de faire. On vient de définir une des fonctions prévues par le moteur, cette fonction s'appelle on_draw et fait partie de sol.main. Le moteur va appeler cette fonction répétitivement pour dire “dessine ce que tu dois dessiner sur cet écran”. Et quand le moteur va demander ça, nous allons lui dire “tu prends l'image title_img qu'on a initialisée un peu plus haut, et tu la dessines sur l'écran”. D'où la seule ligne de cette fonction, title_img:draw(screen). Notre fonction on_draw prend un paramètre, l'écran. Ce paramètre est envoyé automatiquement par le moteur car je vous rappelle, c'est le moteur qui appelle votre fonction on_draw.

À ce stade, on remarque déjà qu'il y a deux grandes catégories de fonctions dans Solarus selon le sens dans lequel elles sont appelées : * Les fonctions fournies par Solarus et que vos scripts Lua peuvent appeller, comme sol.surface.create() ou encore title_img:draw(screen). * Les fonctions que vous définissez vous-même et que Solarus appelle automatiquement (lorsqu'elles existent), comme sol.main:on_draw(screen). Ces fonctions ont un nom qui commence toujours par “on_”, et nous les appelons des évènements.

Toutes ces fonctions, y compris les évènements, sont précisément documentées dans l'API de référence Solarus.

Vous remarquerez que pour certaines fonctions, on utilise une syntaxe avec le symbole deux-points : objet:fonction(). En fait, la notation objet:fonction() est juste un raccourci pour dire objet.fonction(objet). Les fonctions on_started et on_finished devraient elles aussi être au format avec “:” au lieu de “.”, c'est un oubli sans conséquence qui sera sans doute rectifié dans Solarus 1.1.

Si vous sauvegardez et que vous lancez le jeu, vous devriez avoir votre image qui s'affiche. Vous remarquez que l'image est dessinée depuis le coin haut-gauche de l'écran. C'est parce que comme vous n'avez pas précisé où afficher l'image, elle s'affiche en 0, 0. C'est-à-dire que le coin haut gauche de l'image est aux coordonnées haut-gauche de l'écran. Vous pouvez changer ces coordonnées, par exemple en mettant title_img:draw(screen, 20, 50). Relancez le jeu et vous verrez la différence par vous-même. Amusez-vous à faire quelques tests de coordonnées pour mieux appréhender le côté “les coordonnées sont en rapport avec le coin haut-gauche à chaque fois”.

Voici au final le fichier main.lua que vous avez :

-- This is the main Lua script of your project.
-- You will probably make a title screen and then start a game.
-- See the Lua API! http://www.solarus-games.org/solarus/documentation/
 
-- Below is just an example of quest that does almost nothing.
-- Feel free to change this!
function sol.main.on_started()
  -- This function is called when Solarus starts.
  print("Welcome to my quest.")
end
 
function sol.main.on_finished()
  -- This function is called when Solarus stops or is reset.
  print("See you!")
end
 
local title_img = sol.surface.create("title_img.png")
function sol.main:on_draw(screen)
  title_img:draw(screen, 20, 50)
end

Exercice

Nous n'allons pas faire un exercice très compliqué ici. Sachant que l'écran fait une taille de 320×240 (donc : 320 pixels de large sur 240 de haut), et que l'image que fournie fait 120×120, trouvez d'abord les coordonnées pour mettre l'image en bas à droite, et enfin les bonnes coordonnées pour centrer l'image en largeur et en hauteur, histoire d'avoir un semblant d'écran titre qui déchire.

Correction

Pour mettre l'image en bas à droite, c'est très simple car il suffit de prendre la taille du réceptacle (ici 320×240) et de retirer la taille de l'image (120×120) pour avoir les bonnes coordonnées. Donc, en mettant title_img:draw(screen, 320 - 120, 240 - 120) nous avons l'image en bas à droite. Pour avoir l'image au milieu, on ne peut pas simplement diviser la taille de l'écran par deux, car cela mettrait le coin haut gauche de l'image au centre de l'écran. Il faut donc faire title_img:draw(screen, (320 - 120) / 2, (240 - 120) / 2).

Vous remarquerez que l'on peut mettre les opérations complètes dans les paramètres, car ça aide à comprendre la logique de ce qu'on y a mis. Vous pourriez y mettre le résultat tout aussi rapidement, mais le jour où vous changez la taille de l'écran de jeu, les coordonnées ne seront plus valides. L'idéal serait de remplacer les chiffres en dur (320 et 240) de l'écran par des données reçus dynamiquement, et faire de même pour l'image, mais cette version nous suffira pour ce chapitre.

Chap. 2 : Votre première mapSommaire

fr/tutorial/getting_started.txt · Dernière modification: 2018/12/22 14:14 (modification externe)