Crée ton propre module

Il est possible de créer ses propres module Châtaigne afin d’ajouter des fonctionnalités ou bien supporter un système ou une machine spécifique.

Les Custom modules se situent dans le dossier <Documents>/Chataigne/modules

Pour créer un Custom module, allez dans le dossier modules de Chataigne, puis créez un nouveau dossier. Dans ce dossier, vous allez avoir besoin d’un ficher module.json qui contiendra les metadata, ainsi que les définitions de structure du module (values, parameters, commands, etc). Les définitions pour le fichier module.json à la suite de ce paragraphe.

La plupart du temps, vous allez vouloir ajouter un fichier de script au module. Ce fichier se chargera de toute la logique du module. Vous pouvez apprendre à écrire un script de module ici : Module Scripts​

Si vous appliquez des changements au fichier module.json, n’oubliez pas de faire la manipulation suivante File > Reload custom modules si Châtaigne est en cours d’exécution. Vous devrez aussi supprimer et relancer le module dans Châtaigne.

Il est aussi possible d’ajouter une de icône de 32x32 pixels nommé icon.png dans le dossier du module pour afficher une icône customisé.

Voici un exemple de Custom module: https://github.com/tommag/Sample-Chataigne-module . Vous pouvez vous en servir de base pour créer votre future module, et n’oubliez pas de le partager avec la communauté si vous pensez que ça peut être utile !

Il est également possible de créer un module spécifique à un projet, en plaçant le dossier du module dans un dossier "modules" dans le même dossier que le fichier noisette. Dans ce cas, le module ne sera visible que quand le fichier noisette sera chargé.

Définition du fichier module.json

Si vous n’avez jamais entendu parler du json, vous trouverez une courte explication en suivant ce lien : https://learnxinyminutes.com/docs/json/

Module metadata

Clef	Description	Exemple
name	Nom du Custom module	"name":"Mon Custom module"
type	Type du Custom module. Il indique quelle base de module vous voulez étoffer. Vous pouvez choisir n’importe quelle base de module.	"type":"WebSocket Client"
path	(Optionnel) Le chemin de menu du module. Choisissez un sous-menu existant, ou créez le votre.	"path":"Hardware"
version	(Optionnel) La version du module.	"version":"1.0.0"
description	(Optionnel) Description du module.	"description":"Description de mon module"
url	(Optionnel) Ou trouver des informations à propos de ce module.	"url":"https://github.com/tommag/Sample-Chataigne-module"
downloadURL	(Optionnel) Où télécharger ce module.	"downloadURL":"https://github.com/tommag/Sample-Chataigne-module/archive/master.zip"

Remplacer le module de base

Les clefs JSON suivantes vont vous permettre de décider ce que vous voulez garder du module de base. Vous pouvez trouver les « short name » des paramètres que vous voulez utiliser en survolant le paramètre avec la souris, et regarder la « control address ».

Clef	Description	Exemple
hasInput	(Optionnel) « false » si votre module ne reçoit pas de data. Cela désactivera les flux d'entrée (le cas échéant), masquera le moniteur d'activité d'entrée et masquera les valeurs du module. (sauf si alwaysShowValues est défini).	"hasInput":true
hasOutput	(Optionnel) « false » si votre module n'envoie pas de données. Cela désactivera les flux de sortie (le cas échéant) et masquera le moniteur d'activité de sortie.	"hasOutput":true
defaults	(Optionnel) Plusieurs valeurs à utiliser pour les paramètres du module de base	"defaults": { "autoAdd":false } (pour un module OSC)
hideDefaultParameters	(Optionnel) Un tableau des paramètres que vous souhaitez masquer dans l'inspecteur.	"hideDefaultParameters": [ "autoAdd", "oscInput/localPort"]
hideDefaultCommands	(Optionnel) Définissez-le sur « true » si vous souhaitez masquer les commandes du module de base (par exemple, dans un module OSC, masquez la commande "Custom Message").	"hideDefaultCommands":false
alwaysShowValues	(Optionnel) Défini à « true » si hasInput est défini à false et que vous n'avez pas de valeurs dans ce module, mais que vous voulez quand même pouvoir les ajouter manuellement plus tard.	"alwaysShowValues":true

Paramètres et valeurs personnalisées

Consultez la section Types de données pour en savoir plus sur les différents types de données et les options que vous pouvez utiliser.

Clef	Description	Example
parameters	Les paramètres que vous voulez ajouter au module.	"parameters": { "My parameter": { "type":"Integer" } }"
values	Les valeurs que vous voulez ajouter au module	"values": { "My value": { "type":"Float" } }

Commandes personnalisées

Vous pouvez également définir des commandes personnalisées. Chaque commande est liée à une "fonction de rappel" (callback function) dans le script du module.

Clef	Description	Exemple
commands	Les commandes que vous voulez ajouter au module	"commands": { "My special command": {COMMAND PARAMS}, "Another command": {COMMAND PARAMS} }"

Voici les paramètres de la commande :

Clef	Description	Exemple
menu	Le nom du menu dans lequel cette commande doit se trouver.	"menu":"Special commands"
callback	Le nom de la fonction de script à appeler lorsque cette commande est déclenchée.	"callback":"setParam"
setupCallback	Le nom de la fonction de script à appeler lorsque la commande est créée. Cela permet des constructions dynamique de commandes via le script.	"setupCallback":"setupCommand"
parameters	Les paramètres de la commande. La fonction de rappel du script doit avoir autant de paramètres que ce tableau. Consultez la section Types de données pour plus d'informations sur les types de données possibles.	"parameters": { "Value": { "type":"Integer" } }

Example:

"commands": { "Custom command": { "menu":"", "callback":"customCmd", "parameters": { "Value": { "type":"Integer", } } }

Scripts

Clef	Description	Exemple
scripts	Un tableau qui contient le nom du ou des scripts à ajouter aux modules.	"scripts": [ "moduleScript.js" ]

Vous pouvez trouver la documentation pour les scripts de module ici : Module Scripts​

Types de données

Chaque fois que vous devez spécifier comment traiter certaines données (c'est-à-dire pour les paramètres, les valeurs ou les paramètres de commande), vous disposez des options suivantes.

Clef	Description	Exemple
type	Les types de data. Les options possibles sont: Container, Boolean, Float, Integer, Enum, String, File, Point2D, Point3D, Target, Color.	"type":"Integer"
readOnly	(Optionnel) Définit si la variable peut être modifiée par l'utilisateur	"readOnly":true
shortName	(Optionnel) Définir un nom personnalisé	"shortName":"easyParamName"
description	(Optionnel) Description à afficher dans les infobulles	"description":"This is a cool variable"
min	(Optionnel) Le cas échéant, définissez la valeur minimale de cette variable.. Pour les types Point2D, Point3D, Vous pouvez spécifier un tableau.	"min":0 pour un Integer
max	(Optionnel) Le cas échéant, définissez la valeur maximale de cette variable.. Pour les types Point2D, Point3D, vous pouvez spécifier un tableau.	"max":0.8 pour un Float
default	(Optionnel) Le cas échéant, définissez la valeur par défaut de cette variable. Pour les types Point2D, Point3D, vous pouvez spécifier un tableau.	"default":[0.5, 8] pour un Point2D
dependency	(Optionnel) (Sauf pour un Container) Spécifier une action à effectuer en fonction de la valeur d'une autre variable. Consultez la rubrique Traitement avancé des données Pour plus d’informations.	​

Conteneurs

Les données déclarées avec Container n'ont pas de valeur mais sont utilisées pour regrouper d'autres variables. Elle possède également une propriété de type collapsed :

Clef	Description	Exemple
collapsed	S'il est défini comme vrai, le panneau de l'interface graphique (GUI) est par défaut réduit (les enfants ne sont pas visibles).	"collapsed":true

Example:

"System parameters": { "type":"Container", "collapsed":true, "First variable": { "type":"Float", "default":20, "description":"This is the first variable"}, "Second variable": { "type":"Float", "default":0} }

Enums

Le type Enum est utilisé pour permettre à l'utilisateur de choisir entre un ensemble de valeurs. Il possède une propriété options supplémentaire:

Clef	Description	Exemple
options	Une collection de valeurs possibles. Chaque valeur a une chaîne d'affichage et une donnée associée.	"options": { "Option 1":optl", "Option 2":"opt2"}

Example:

"Test Enum": { "type":"Enum", "options": { "All":"all", "Single":"single" } }

Les types Float UI

Lorsqu'on définit une variable de type Float, il existe une propriété ui property, supplémentaire, utilisée pour personnaliser l'interface graphique (GUI).

Clef	Description	Exemple
ui	Options possibles: stepper, slider, label, time	"ui":"slider"

Traitement avancé des données

Vous pouvez également modifier l'interface utilisateur (UI) en fonction des valeurs d'autres variables. Par exemple, vous pouvez vouloir afficher différentes options en fonction de la valeur d'une Enum.

Pour ce faire, vous devez ajouter la propriété dependency à la variable, puis ajouter les propriétés suivantes (toutes obligatoires) :

Clef	Description	Exemple
source	Le nom de la variable à laquelle vous voulez vous référer	"source":"testEnum"
value	A quelle valeur comparer la source	"value":"all"
check	Quel contrôle effectuer. Valeurs possibles: equals, notEquals	"check":"equals"
action	L'action à exécuter lorsque la vérification est réussie. Valeurs possibles: show, enable	"action":"show"

Exemple : Cet exemple alterne entre deux options différentes en fonction du choix de l'enum.

"parameters": { "My variable type": { "type":"Enum", "options": { "Float":"float", "Integer":"int" } }, "Variable (float)": { "type":"Float", "dependency": { "source":"myVariableType", "value":"float", "check":"equals", "action":"show" } }, "Variable (int)": { "type":"Integer", "dependency": { "source":"myVariableType", "value":"int", "check":"equals", "action":"show" } } }