Pages

Welcome to my blog

My name is Gilles Charbonneau

I am a long time 2d animator and I would like to share with you some of the tips and tricks I have learned over the years by posting tutorials and articles on this blog.

Gilles

Programmation dans Anime Studio - La base

*** This is a French translation of Scripting in Anime Studio - The basics ***

J'ai tout tenté afin de rester loin de la programmation dans Anime Studio, vraiment tout, mais je savais que ce n'était qu'une question de temps avant que je plonge, et j'ai plongé en beauté!

Pour la plupart des gens, la programmation est un sujet obscur qui fait un peu peur par son aspect technique. Mais n'ayez crainte, la programmation, et tout particulièrement dans Anime Studio, n'est pas aussi terrible que vous pourriez le croire.

Pour quelles raisons la programmation est-elle à la fois une bonne et une mauvaise chose pour les utilisateurs d'Anime Studio?

Et bien, en tout premier lieu, elle permet la création d'outils permettant de grandement améliorer votre méthode de travail.

La programmation permet aussi d'étendre les capacités d'Anime Studio avec la création d'outils permettant des tâches que le logiciel ne peut faire à la base, par exemple, la création d'outils aidant à l'animation de personnages.

La seule mauvaise chose concernant la programmation, c'est qu'obligatoirement elle prend sur le précieux temps d'animation, mais il s'agit ici d'un compromis équitable, puisque les possibilités qu'apporte la programmation sont presque sans fin.

La programmation dans Anime Studio se fait à l'aide du langage Lua, langage qui prit naissance en 1993.

Il y a deux raisons qui m'incitent à créer ce tutoriel, la première est que j'affectionne ce genre de travail.

La deuxième est que la programmation est de loin l'aspect le plus technique de l'utilisation d'anime Studio et qu'il existe très peu de documentation spécifique à la programmation pour cet excellent logiciel d'animation.

De plus, le peu de documentation existante est généralement trop technique pour un profane n'ayant peu, ou jamais fait de programmation.

Je ferais donc de mon mieux afin d'exposer le plus simplement possible les fondements de la programmation en Lua pour Anime Studio.

Bon, assez bavardez et commençons par le début.

En premier lieu, vous pourrez trouver le script complet ici.

gc_createcircle.zip 1kb

Mais avant même de pouvoir commencer, il est bon de voir les bases de la programmation et quelques-uns de ses concepts généraux.

Je vais tout mettre en oeuvre afin de rendre le processus le plus agréable possible.

LES OUTILS

Afin de pouvoir programmer, il vous suffit d'avoir un éditeur de texte permettant de sauvegarder en fichier texte.

Notepad est un excellent éditeur sous Windows, mais une excellente et gratuite alternative est développer Notepad, un éditeur de texte multilingue offrant diverses fonctions et de plus très facile d'utilisation.

CONCEPTS DE BASE

Fonctions: Les fonctions sont des programmes à l'intérieur de programmes. Elles sont des petits programmes s'exécutant à l'intérieur du programme principal.

Elles sont généralement utilisées pour de petites tâches, comme afficher de l'information à l'écran, ou pour rassembler de l'information pouvant être utile au programme principal. Une fonction peut être appelée en tout temps de l'intérieur du programme principal.

Une fonction est définie, ou créée avec la classe function(), et vous pouvez passer des arguments à la fonction en les plaçant entre les parenthèses.

Variables: Les variables sont en fait de conteneurs. Une variable peut contenir une foule de données pouvant être utilisées par le programme.

Les variables peuvent être locale, en d'autres termes, elle n'existe que pour une tâche bien définie et ont une durée de vie généralement courte. Elles peuvent être globales, et l'information qu'elles contiennent peut être utilisée dans l'ensemble du programme principal.

Instruction conditionnelle: Une instruction conditionnelle est un petit bout de code posant une question, comme, si quelque chose se produit, que ce passe-il. L'instruction conditionnelle utilise les mots clés IF/THEN/ELSE.

if (ÉVENEMENT) then
RÉSULTATS
end

Boucles: Les boucles, comme le nom le suggère, crée une boucle d'information utilisant les mots clés FOR/DO.

À chaque fois qu'une boucle est complétée, un code est exécuté.

Un exemple pourrait compter de 1 à 10 et à chaque boucle afficher de l'information à l'écran et à la fin de la boucle le compteur est augmenté.

for i = COMPTEUR do
CODE
end

LUA

Niveaux de Lua: Comme je l'ai mentionné précédemment, la programmation se fait par le biais du langage Lua et il existe 3 niveaux, ou modules de programmation dans Anime Studio

Niveau LM: Il s'agit ici du niveau de base, ce niveau contient l'information telle que le contenu vectoriel, les couleurs, l'animation des points, etc.

Niveau LM.GUI: Ce module traite les commandes de l'interface, c’est à ce niveau que nous construisons les menus, ou nous créons les messages d'avertissement ou créons les outils nécessaires pour l'interactivité avec le logiciel.

Niveau MOHO: Le niveau ou l'action se passe. Il s'agit du module ou nous pouvons créer le contenu à l'intérieur d'Anime Studio, tels les points, les courbes, etc. Il s'agit du module le plus utilisé.

Pour programmer dans Anime Studio, nous devons utiliser ces modules en conjonction avec les différentes constantes, fonctions et classes disponibles.

Il existe 3 types différents de scripts dans Anime Studio.

Scripts de menu: Les scripts de menu sont les plus simples des 3 types de script. Vous pouvez accéder à ces scripts via le menu déroulant Scripts dans le haut de l'interface d'Anime Studio.

Ces scripts sont d'utilisation unique, vous les exécutés, ils exécutent leurs code, puis vous retourne à l'interface d'anime Studio. Vous devez les exécuter à nouveau si vous désirez les activer une autre fois.

Script d'outil: Vous pouvez accéder aux scripts d'outil par le biais de la barre d'outils à la gauche de l'interface de travail. Ces scripts sont classés sous Dessiner, Remplissage, Os, Calques, Caméra et La vue. De plus, vous pouvez ajouter d'autres outils qui seront affichés sous la palette d'outil.

Les scripts d'outil sont activés lorsque vous cliquez leurs icônes, et ils restent activés jusqu'a ce qu'un autre outil soit sélectionné.

Ces scripts sont plus complexes puisqu'ils permettent la création et l'utilisation de menu, et plus encore. Ces scripts se trouvent dans le répertoire Scripts/tool dans votre répertoire d'installation.

Note: Vouz pouvez éditer l'apparance de la palette d'outil en modifiant le fichier _tool_list.txt dans le répertoire Scripts/tool afin d'accomoder votre interface à votre méthode de travail.

Scripts intégrés: Vous pouvez ajouter un script intégré en ouvrant la page de propriété d'un calque et en sélectionnant la case Fichier de script intégré. Une fenêtre va apparaitre, vous demandant de naviguer jusqu'à l'emplacement du script puis de le sélectionner.

Les scripts intégrés sont évalués pour chaque trame de votre animation, et modifient celle-ci selon le code du script.

Vous pouvez placer les scripts intégrés dans n'importe quel répertoire de votre ordinateur.

Maintenant, passons à des choses plus intéressantes.

Jetons un oeil sur un script.

Il s'agit d'un simple script de menu n'ayant qu'une seule fonction. Il cré un cercle au milieu de l'espace de travail et lui assigne la forme courante.

Jetons-y un regard puis nous l'analyserons.

-- **************************************************
-- Provide Moho with the name of this script object
-- **************************************************

ScriptName = "gc_drawcircle"

-- **************************************************
-- General information about this script
-- **************************************************

gc_drawcircle = {}

function gc_drawcircle:Name()
     return "Draw Circle"
end

function gc_drawcircle:Version()
     return "6.0"
end

function gc_drawcircle:Description()
     return "Draws a circle on the workspace"
end

function gc_drawcircle:Creator()
     return "Gilles Charbonneau."
end

function gc_drawcircle:UILabel()
     return("Draw Circle")
end

-- **************************************************
-- The guts of this script
-- **************************************************

function gc_drawcircle:Run(moho)
     local mesh = moho:Mesh()

     if (mesh == nil) then
     LM.GUI.Alert(LM.GUI.ALERT_INFO, "This script only works on vector layers!")
          return
     end

     local v = LM.Vector2:new_local()
     mesh:SelectNone()

     v.x = -.25
     v.y = 0
     mesh:AddLonePoint(v, moho.layerFrame)
     v.x = 0
     v.y = 0.25
     mesh:AppendPoint(v, moho.layerFrame)
     v.x = 0.25
     v.y = 0
     mesh:AppendPoint(v, moho.layerFrame)
     v.x = 0
     v.y = -0.25
     mesh:AppendPoint(v, moho.layerFrame)
     v.x = -.25
     v.y = 0
     mesh:AppendPoint(v, moho.layerFrame)

     numpoints = mesh:CountPoints()
    
     mesh:WeldPoints(numpoints-1, numpoints-5, 0)
    
     mesh:Point(numpoints-5):SetCurvature(.4, 0)
     mesh:Point(numpoints-4):SetCurvature(.4, 0)
     mesh:Point(numpoints-3):SetCurvature(.4, 0)
     mesh:Point(numpoints-2):SetCurvature(.4, 0)
    
     mesh:SelectConnected()
    
     moho:CreateShape(true)

end

En premier lieu, toute ligne qui débute avec un "--", sont des lignes de commentaires et ne sont pas prise en compte par le script. Les caractères "*****" servent seulement à faire joli!

En fait, la première ligne de code est...

ScriptName = "gc_drawcircle"

Sur cette ligne nous inscrivons le nom de notre script, cela peut être ce que vous voulez.

Habituellement, le nom du script débute avec les initiales de la personne qui l'a créé, dans ce cas précis j'ai paraphé le nom du script avec gc, pour Gilles Charbonneau. De plus, cela aide à personnaliser les différents scripts et prévient les conflits potentiels avec d'autres scripts.

-- **************************************************
-- General information about this script
-- **************************************************

Cette ligne de commentaires nous indique que nous sommes dans la section information générale du script. Cette section contient les fonctions qui gèrent l'information générale du script.

Cette information est nécessaire pour tous les scripts d'Anime Studio. Vous devez insérer ces lignes dans tous vos scripts sans exception.

gc_drawcircle = {}

Sur cette ligne nous créons un array qui servira à gérer la plupart des fonctions de notre script. Cette classe se nomme une table dans le langage Lua.

Nous n'aurons pas un regard approfondi des tables dans ce tutoriel, mais vous pouvez en apprendre plus à ce sujet en lisant le manuel Lua référencé au bas de ce tutoriel, car les tables sont un concept très important du langage Lua.

function gc_drawcircle:Name()
return "Draw Circle"
end

Ici nous insérons le nom du script tel qu'il apparaitra dans le menu d'Anime Studio.

Comme vous pouvez le constater, nous utilisons l'array que nous avons créé en conjonction avec la classe Nom() pour enregistrer le nom du script.

De cette façon, Anime Studio peux avoir accès au nom du script en tout temps en utilisant la commande gc_drawcircle:Name(). Nous utiliserons une syntaxe similaire pour les autres champs de la section information générale.

function gc_drawcircle:Version()
return "1.0"
end

Ici nous insérons le numéro de la version de développement courante de notre script. Souvent, les programmeurs insèrent le numéro de la version minimum d'Anime Studio sur laquelle le script peut fonctionner.

function gc_drawcircle:Description()
return "Draws a circle on the workspace"
end

Ici nous insérons la description du script tel qu'il apparaitra dans la barre d'information apparaissant dans le haut de l'espace de travail d'Anime Studio.

function gc_drawcircle:Creator()
return "Gilles Charbonneau."
end

Dans cette fonction vous devez insérez le nom du programmeur créant le script, dans ce cas précis mon nom, Gilles Charbonneau.(je gonfle d'orgueil alors que j'insère mon nom.)

function gc_drawcircle:UILabel()
return("Draw Circle")
end

La dernière fonction de la section information générale. Nous saisissons le nom du script tel qu'il apparaitra soit dans le menu déroulant de la section Scripts ou lorsqu'un utilisateur passera sa souris sur l'icône du script dans Anime Studio.

-- **************************************************
-- The guts of this script
-- **************************************************

Ce commentaire indique le début de la section principal de notre script. C'est dans cette section que nous insérerons le code permettant au script de créer le cercle.

function gc_drawcircle:Run(moho)
local mesh = moho:Mesh()

Sur la première ligne de code, nous créons une fonction disant au module moho d'exécuter ce script.

Souvenez vous qu'il y a 3 modules principaux permettant de programmer dans Anime Studio et que moho est le plus utilisé.

Ce code est surtout utilisé pour les scripts de menu, puisque ceux-ci doivent être exécutés dès que le script est lancé. Habituellement, un script outil réagit à un événement de la souris après qu'il a été activé, alors que les scripts de menu sont généralement utilisés une seule fois.

Nous avons aussi créé une variable locale appelée mesh. Cette variable est créée avec la classe Mesh(), qui fait partie du module moho et nous sert à référencer un calque vectoriel.

La variable mesh est en toute fin pratique une référence pour le calque vectoriel actif sur lequel le script va travailler. La variable peut contenir des points, des courbes, des formes et des remplissages.

if (mesh == nil) then
LM.GUI.Alert(LM.GUI.ALERT_INFO, "This script only works on vector layers!")
return
end

Dans cette partie du script nous avons l'instruction conditionnelle IF/THEN

Sur la première ligne, IF pose la question, somme-nous sur un calque vectoriel en ce moment?

Il se fait en vérifiant si la variable mesh est vide(nil). Si mesh est vide, cela signifie qu'un calque vectoriel n'était pas sélectionné au moment ou le script a été lancé.

Si nous ne sommes pas sur un calque vectoriel, la seconde ligne de code est lancée, ce qui a pour effet d'afficher une fenêtre d'alerte nous indiquant que le script ne peut fonctionner que sur un calque vectoriel. Puis la troisième ligne de code est exécutée, terminant le script et nous retournant à l'interface de travail d'Anime Studio.

Si par contre le calque actif est un calque vectoriel, le script continu.

Notez l'utilisation de la classe Alert() du module LM.GUI pour l'affichage du message.

local v = LM.Vector2:new_local()

Sur cette ligne de code, nous créons la variable v, en utilisant la classe Vector2 du module LM qui cré une référence a un point ou un vecteur 2D.

En d'autres termes, v emmagasine toutes les informations du point ou du vecteur 2D actif et peut êtres utilisé afin d'accéder à n'importe quelle de leurs propriétés.

mesh:SelectNone()

Cette ligne de code déselect tout sur le calque actif.

v.x = -.25
v.y = 0
mesh:AddLonePoint(v, moho.layerFrame)

Dans cette partie du code, nous créons le premier point de notre cercle.

Pour commencer, nous assignons la valeur -.25 à la position x(horizontal) de la variable v, puis nous assignons 0 a la valeur y(vertical).

Ces valeurs représentent des coordonnées sur l'espace de travail d'Anime Studio.

Par la suite nous créons le premier point en utilisant la classe AddLonePoint() du module moho, puis nous passons la variable v qui contient les coordonnées du point, et ce sur la trame 0.

Ceci créé un point unique sur le calque actif et aux coordonnées spécifiées dans la variable v.

v.x = 0
v.y = 0.25
mesh:AppendPoint(v, moho.layerFrame)

v.x = 0.25
v.y = 0
mesh:AppendPoint(v, moho.layerFrame)

v.x = 0
v.y = -0.25
mesh:AppendPoint(v, moho.layerFrame)

v.x = -.25
v.y = 0
mesh:AppendPoint(v, moho.layerFrame)

Dans ce bloc de code, nous créons 4 points de plus, tous a des coordonnés différents.

La seule différence ici, est l'utilisation de la classe AppendPoint() plutôt que la classe AddLonePoint(), celle-ci est utilisée afin d'ajouter un point à la suite du dernier point créé.

En d'autres termes, le second point est ajouté au premier que nous avons créé avec la classe AddLonePoint(), puis un troisième point est ajouté au deuxième et ainsi de suite.

À ce point, nous avons créé 5 points, et le premier point se trouve exactement aux mêmes coordonnés que le dernier, nous devons maintenant souder ces 2 points qui se chevauchent.

numpoints = mesh:CountPoints()

Avec cette ligne de code, nous créons la variable numpoints et nous lui assignons le nombre de points dans le calque actif avec la classe CountPoints().

Nous utiliserons cette information lors des étapes suivantes.

mesh:WeldPoints(numpoints-1, numpoints-5, 0)

Ce code sert à souder les 2 points qui se chevauchent.

Nous utilisons la classe WeldPoints().

Ce qu'il faut comprendre ici est que chaque point créé dans Anime Studio se voit assigner un numéro d'identification et que les derniers points créés ont les numéros les plus élevés.

Donc, si le calque actif comporte déjà des formes, et que ces formes sont composées de 100 points en tout, la variable numpoints que nous avons créée devrait contenir le chiffre 105, soit les 100 points qui existait déjà, plus les 5 points que nous avons créés pour notre cercle.

Maintenant, pour souder les points qui se chevauchent, nous devons connaitre le numéro d'identification du premier et du dernier point de notre cercle, le calcul se fait comme suit.

Nous prenons le nombre 105, moins 1, pour le dernier point, et moins 5 pour le premier point que nous avons créé. (Les numéros d'identification débutent avec 0, et non pas 1)

Donc, dans notre exemple, en supposant que le calque courant comportait déjà 100 points avant la création de notre premier point, soit les points de 0 à 99, le premier point que nous avons créé s'est vu assigné le numéro d'identification 100, et le dernier point le numéro 104.

Dans ce cas de figure, la classe WeldPoint() soudera les points avec l'identifiant 100 et 104 à la trame 0.

WeldPoints(numpoints-1, numpoints-5, 0)

Si les points que nous voulons souder ne se trouvent pas exactement l'un par-dessus l'autre, le second point sera déplacé à l'emplacement du premier puis soudé.

Nous avons maintenant un cercle avec une courbe fermée.

Par contre, la courbure par défaut n'est pas assez prononcée pour créer un cercle parfait, le cercle créé est difforme.

mesh:Point(numpoints-5):SetCurvature(.4, 0)
mesh:Point(numpoints-4):SetCurvature(.4, 0)
mesh:Point(numpoints-3):SetCurvature(.4, 0)
mesh:Point(numpoints-2):SetCurvature(.4, 0)

Ces 4 lignes de code ajustent la courbure pour chacun des points que nous avons créés. Pour ce faire nous utilisons la classe SerCurvature() à laquelle nous passons les identifiant à l'aide de la variable numpoints-2 à numpoints-5. Nous leurs assignons la courbure .4 sur la trame 0.

Note: Le point avec l'identifiant numpoints-1 ayant été soudé au point avec l'identifiant numpoints-5, celui-ci n'existe plus.

Ceci nous donne un cercle parfait avec les points de départ et de fin proprement soudée.

mesh:SelectConnected()

Cette ligne de code sélectionne tous les points de notre cercle.

moho:CreateShape(true)

Cette ligne de code assigne une forme à notre cercle avec le style courant.

end

Ceci termine le script et nous retourne à l'espace de travail d'Anime Studio, affichant notre nouveau cercle au milieu de celui-ci.

COMMENT UTILISER LE SCRIPT

Notre script est un script de menu, donc, vous devez le copier dans le répertoire Scripts/menu sous votre répertoire d'installation d'Anime Studio.

Vous pouvez copier le script dans n'importe lequel des sous répertoires, ou vous pouvez en créer un nouveau.

Vous devez lancer le script à partir du menu Scripts dans le haut de l'interface d'Anime Studio.

Souvenez-vous que vous devez activer un calque vectoriel avant de lancer le script, sinon un message vous demandant de la faire apparaitra et le script ne fonctionnera pas.

CONCLUSION

Et voila, une introduction è la programmation en Lua pour un script Anime Studio.

Il est bien entendu qu'il existe une façon plus aisée de construire un cercle dans Anime Studio. J'ai fait le tour de l'arbre à quelques reprises afin de démontrer certaines des fonctions et classes disponibles pour la création de scripts dans Anime Studio

Tel que je l'ai mentionné plus tôt, il existe très peu de documentation sur la programmation dans Anime Studio, mais vous pouvez en trouver quelques-unes à ces adresses (anglais).

Interface de programmation pour Anime Studio 8. (Cliquez de droite et sauvegarder.)
http://www.lostmarble.com/downloads/pkg_moho.lua_pkg

Interface de programmation pour Anime Studio 6.1.
http://my.smithmicro.com/downloads/files/AnimeStudio6.1ScriptingInterfaces.zip

Documentation de programmation pour Anime Studio 5.
http://www.lostmarble.com/moho/extras/scripts/moho_scripting.zip

Dans ces documents vous trouverez de l'information sur les constantes, fonctions et classes nécessaire à la programmation de scripts pour Anime Studio.

Vous pouvez aussi accéder à un excellent manuel de programmation en Lua à cette adresse (anglais).

http://www.lua.org/pil

J'espère que ce tutoriel vous aura donné l'envie de programmer des scripts pour Anime Studio

Dès que vous aurez assimilé les fondements de la programmation pour Anime Studio, je vous suggère d'étudier et d'apprendre avec les scripts existants, puisqu'ils sont la meilleure source d'information pour développer vos compétences en programmation Lua

Si vous avez des questions, et biens, posez-les, et c'est avec plaisir que j'y répondrai!

Bonne programmation.

Gilles

3 comments:

  1. Merci Gilles.
    C'est tres bien. C'est une peut difficile pour moi, mais je suis tres content avec ton aide.
    Dust

    ReplyDelete
  2. Si tu as des questions ne te gène surtout pas!

    ReplyDelete
  3. Pareillement, même un an plus tard !!!

    ReplyDelete