Difference between revisions of "Programming Guide/fr"

From Space Engineers Wiki
Jump to: navigation, search
m (Title correction)
Line 1: Line 1:
 
{{DISPLAYTITLE:Guide de Programmation}}
 
{{DISPLAYTITLE:Guide de Programmation}}
 +
La programmation dans Space Engineers se fait avec le [[Programmable Block/fr|Bloc programmable]] qui peut recevoir des scripts écrits en C# (prononcé C Sharp). Cela peut être utilisé pour fabriquer des drones miniers autonomes, des torpilles tueuses de joueurs à longue portée, des bras de soudage automatisés pour la construction de navires et bien plus encore.
 +
 
== Introduction ==
 
== Introduction ==
 +
=== Accéder à l'édition ===
 +
Un code ne peut être modifié que par un seul joueur à la fois. Si un joueur essaye d'ouvrir l'éditeur alors qu'un autre l'utilise, une notification lui indiquera que l'éditeur est en cours d'utilisation.
 +
 +
=== Méthode principale ===
 +
Lorsque l'éditeur est ouvert pour la première fois, la méthode void Main() s’affiche automatiquement.
 +
C'est le point d'entrée qui sera appelé lors de l'exécution du script.
 +
Si la méthode Main est supprimée ou renommée, le script ne s'exécutera pas et vous en serez averti dans la zone de détails du bloc programmable.
 +
Des méthodes et variables personnalisées peuvent être définies et utilisées, mais seule la méthode Main sera appelée sans référence.
 +
 +
=== Durée de vie et portée des variables ===
 +
Les variables peuvent être utilisées de deux façons différentes :
 +
;Locales (à l'intérieur des méthodes) : ces variables ne gardent leur valeur que pendant l'exécution de la méthode. La valeur est « perdue » dès que la méthode est terminée.
 +
;Globales (à l'extérieur des méthodes) : ces variables conservent leur valeur pendant la durée de vie du script. Par exemple, si la variable doit conserver sa valeur entre des exécutions distinctes du script, elle doit être définie en dehors des méthodes.
 +
 +
Après avoir validé vos modifications et confirmé l'enregistrement, le script précédent sera écrasé et toutes les variables globales seront perdues.
 +
 +
Toutes les variables, locales et globales, à l'exception de la variable de stockage intégrée ("Storage"), perdront leur valeur ou reviendront à leur valeur par défaut lors de la recompilation du code et entre les chargements de parties sauvegardées. La variable de stockage est la solution pour sauvegarder des données à la fin d’une session, afin de les récupérer au redémarrage de la partie ou après la recompilation du script ([[https://github.com/malware-dev/MDK-SE/wiki/The-Storage-String explications en anglais]]).
 +
 +
=== Compilation ===
 +
Le bouton <code>Vérifier le code</code> lance la compilation du code et le résultat de la compilation sera affiché. Le processus de compilation comporte deux étapes : tout d'abord, le code dans l'éditeur est compilé par le compilateur C# pour les erreurs de langage. S'il y a des erreurs lors de la compilation, une boîte de dialogue s'affiche, indiquant la position de l'erreur dans le code et une description de l'erreur.
 +
 +
Après la compilation, le code est vérifié pour l'utilisation d'espaces de noms et de types non autorisés. Si cette vérification échoue, une boîte de dialogue s'affiche : Dans ce cas, System.IO.Directory a été utilisé pour supprimer un répertoire. Ceci est interdit et une erreur s'affiche indiquant que « Not allowed type was used in script » (Trad: un type non autorisé a été utilisé dans le script).
 +
[''Manque l'image d'exemple...'']
 +
 +
Si la compilation et les vérifications réussissent, une boîte de dialogue s'affiche, confirmant les vérifications réussies. Vous pouvez sortir en cliquant sur <code>OK</code> et le code est alors enregistré.
 +
 +
=== Exécution des scripts ===
 +
Le script peut être déclenché par les moyens suivants :
 +
 +
1. En appuyant sur le bouton <code>Exécuter</code> dans les propriétés du terminal du bloc programmable.
 +
 +
2. En attribuant une action au terminal et en appuyant manuellement sur le bouton d'action (<code>1</code> à <code>9</code>) tout en contrôlant la grille à l'aide du cockpit ou d'un poste de contrôle.
 +
 +
3. En appuyant sur le bouton d'un tableau de commande, dont l'action assignée est "Exécuter".
 +
 +
4. Par une minuterie ([[Timer Block|Bloc temporisateur]]) avec l'action assignée "Exécuter".
 +
 +
5. Par un autre script dans un autre bloc programmable de la même grille.
 +
 +
6. Par antenne avec bloc programmable assigné, lors de la réception d'un message d'une autre antenne. (voir [[Antenna#Programming]]
  
  
 +
7. Par le script lui-même, en affectant une valeur à la variable Runtime.UpdateFrequency. Dans ce cas, '''aucun argument ne peut être spécifié'''. Cependant, vous pouvez utiliser la signature de méthode Main suivante :
 +
void Main(string argument, UpdateType updateSource)
 +
Vous pourrez ainsi accéder aux informations sur ce qui a exactement déclenché le script. Le script "connaîtra" comment il a été déclenché, par des événements Update1, Update10, Update100, ou manuellement, ou tout autre événement ayant provoqué l'exécution du déclencheur.
  
−
== Accéder à l'édition ==
+
Le script est exécuté uniquement sur le serveur même s'il est déclenché depuis le client. S'il y a une exception pendant l'exécution du script, tous les clients seront informés de l'échec dans la zone de détails du bloc programmable. En cas d'exception lors de l'exécution du script, le script ne sera pas exécuté à nouveau à moins que l'utilisateur n'ouvre l'éditeur et modifie le script.
−
Un code ne peut être modifié que par un seul joueur à la fois. Si un joueur essaye d'ouvrir l'éditeur alors qu'un autre l'utilise, une notification lui indiquera que l'éditeur est en cours d'utilisation.
+
 
 +
=== Comptage des instructions ===
 +
Chaque fois que le script est exécuté, chaque instruction du script est comptée. Si le script exécute plus d'instructions que la limite, l'exécution est arrêtée et l'utilisateur est averti que le script est trop complexe pour être exécuté. Cela empêche les scripts de "geler" le jeu.
 +
 
 +
=== Liste blanche ===
 +
Les types et classes autorisés dans les scripts sont restreints. Reportez-vous à la [[Scripting Whitelist|liste blanche de script]] pour voir ce que vous êtes autorisé à utiliser.
 +
 
 +
== Interfaces disponibles ==
 +
=== Actions possible ===
 +
Actuellement, seules les actions de terminal peuvent être déclenchées dans les scripts. L'utilisateur peut accéder au système de terminal pour la grille sur laquelle se trouve le bloc programmable et déclencher n'importe quelle action de terminal sur n'importe quel bloc de la grille.
 +
:* [[Programming_Guide/API_List|Liste des API]]
 +
 
 +
=== Classes des blocs (Liste des Actions) ===
 +
:* [[Programming_Guide/Action_List|Liste des actions des blocs]]
 +
 
 +
=== Même classe de bloc pour différents SubTypeID ===
 +
Certains blocs ont le même parent (par exemple <TypeId> dans cubeblocks.sbc) et ne diffèrent que par le sous-type (par exemple <SubtypeId>). Cela signifie qu'il n'y a pas de distinction entre ces blocs dans le code.
 +
 
 +
Le conteneur est un exemple de ces blocs : il existe 3 types de conteneurs de marchandises dans le jeu : petit, moyen et grand. Ces trois types ne diffèrent que par le sous-type et le type est le même pour eux. L'identifiant du grand conteneur est :
 +
 
 +
<Id>
 +
  <TypeId>CargoContainer</TypeId>
 +
  <SubtypeId>LargeBlockLargeContainer</SubtypeId>
 +
</Id>
 +
 
 +
Le moyen est:
 +
 
 +
<Id>
 +
  <TypeId>CargoContainer</TypeId>
 +
  <SubtypeId>SmallBlockMediumContainer</SubtypeId>
 +
</Id>
 +
 
 +
Et le petit est :
 +
 
 +
<Id>
 +
  <TypeId>CargoContainer</TypeId>
 +
  <SubtypeId>LargeBlockSmallContainer</SubtypeId>
 +
</Id>
 +
 
 +
Dans ce cas, il n'y a qu'une seule classe IMyCargoContainer pour tous les types de conteneurs.
 +
 
 +
== programmes d'exeples ==
 +
 
 +
=== Hello world ===
 +
Le programme standard Hello World dans Space Engineers peut être écrit comme tel :
 +
 
 +
public void Main()
 +
{
 +
    Echo ("Hello, world!");
 +
}
 +
 
 +
Si ce programme est entré dans un bloc programmable et exécuté, il se traduira par "Hello, world!" affiché dans l'interface du bloc programmable en bas à droite de l'écran.
 +
 
 +
=== Obtenir votre position ===
 +
Ce programme affichera les coordonnées GPS actuelles de la position de votre bloc de programmation dans le monde.
 +
 
 +
public void Main()
 +
{
 +
    var pos = Me.GetPosition();
 +
    Echo (pos.ToString());
 +
}
 +
 
 +
 
 +
=== Vérification d'un capteur ===
 +
Il est facile de faire en sorte qu'un capteur ouvre une porte ou déclenche une autre action même sans aucune programmation si vous placez simplement cette action dans la liste "Actions de configuration" du capteur. Cependant, déclencher une action lorsqu'un capteur ne détecte pas quelque chose est plus difficile et ne peut pas être fait avec des blocs de minuterie. Ce programme vérifiera automatiquement un capteur toutes les 10 ticks (soit environ 6 fois par seconde) et fermera une porte si le capteur ne détecte rien. Cela peut facilement être appliqué à d'autres fins, comme désactiver les foreuses lorsque les astéroïdes ne sont pas à portée du capteur.
 +
 
 +
List<MyDetectedEntityInfo> entity_list = new List<MyDetectedEntityInfo>();
 +
public Program()
 +
{
 +
    Runtime.UpdateFrequency = UpdateFrequency.Update10;
 +
    //Cela rend le programme exécuté automatiquement toutes les 10 ticks.
 +
}
 +
public void Main()
 +
{
 +
    var door_sensor = GridTerminalSystem.GetBlockWithName("Door Sensor 1") as IMySensorBlock;
 +
    door_sensor.DetectedEntities (entity_list);
 +
    if (entity_list.Count == 0)
 +
    {
 +
        var door = GridTerminalSystem.GetBlockWithName("Door 1") as IMyDoor;
 +
        door.ApplyAction ("Open_Off");
 +
    }
 +
}
 +
 
 +
Pour que ce script fonctionne, le capteur doit être nommé "Door Sensor 1" et la porte doit être nommée "Door 1". Si vous configurez le capteur pour ouvrir la porte, la porte s'ouvrira automatiquement lorsque le joueur entre dans la plage du capteur et se fermera lorsque le joueur quitte la plage du capteur.
  
 +
== Erreurs de compilation ==
 +
Il s'agit d'une liste (en cours) des erreurs de compilation connues et de leurs causes.
  
−
== Code source ==
+
* Method name expected (Nom de la méthode attendu) : le compilateur a trouvé des parenthèses alors qu'il ne les attendait pas. Vous pourriez avoir poublié un nom de méthode avant les parenthèses, ou vous pourriez utiliser de manière inappropriée des parenthèses au lieu de crochets ou d'accolades, selon ce que vous essayez de faire.
−
Lorsque l'éditeur est ouvert la première fois, la commande void Main() se trouvera par défaut dans le code. C'est le point de départ pour tous les scripts qui seront exécutés ici. Si cette commande source est renommée ou supprimée, le script ne fonctionnera plus. Par la suite, des codes et des variables peuvent être utilisés mais ne remplaceront jamais le code source.
 
  
−
== Les variables ==
+
== Voir également ==
−
Il y a deux types de variables :
+
* [[API:Sandbox.ModAPI.Ingame.MyGridTerminalSystem|MyGridTerminalSystem]] - Méthodes pour obtenir des références d'objets à vos divers composants de vaisseau.
 +
* [[Programming Guide/Action List]] - Actions que vous pouvez appliquer aux objets via la méthode Object.ApplyAction. Comprend également certaines des propriétés de l'objet.
  
−
Les variables '''locales''' - Ces variables ne gardent leurs valeurs que lorsque le code est exécuté. Dès que ce dernier n'est plus exécuté, les valeurs de la variable sont "perdues".
+
== Liens externes ==
 +
* [https://github.com/malware-dev/MDK-SE/wiki/Quick-Introduction-to-Space-Engineers-Ingame-Scripts Quick Introduction to Space Engineers Ingame Scripts · malware-dev/MDK-SE Wiki] - Liste d'API générée automatiquement, tutoriels, etc.
 +
* [https://forums.keenswh.com/threads/guide-programmable-block-c-101-for-space-engineers.7225150/ <nowiki>[Guide]</nowiki> Programmable Block - C# 101 For Space Engineers] - Introduction de base à la programmation C# pour Space Engineers.
 +
* [https://forum.keenswh.com/threads/guide-programmable-block-c-102-for-space-engineers-loops-strings-and-other-things.7229828/ <nowiki>[Guide]</nowiki> Programmable Block - C# 102 for Space Engineers: Loops, Strings, and Other Things] - Introduction de base à l'utilisation des boucles et des chaînes en C#
 +
* [https://forum.keenswh.com/threads/guide-programmable-block-c-103-for-space-engineers-math-class.7231429/ <nowiki>[Guide]</nowiki> Programmable Block - C# 103 for Space Engineers - Math Class] - Introduction de base à l'utilisation de la bibliothèque Math en C#
 +
* [https://forums.keenswh.com/threads/programmable-block-inter-grid-communication-guide.7392031/ Programmable Block Inter-Grid Communication Guide] - Utilisation d'antennes pour permettre aux blocs de programmation de communiquer à distance entre eux.
 +
* [https://github.com/malware-dev/MDK-SE/wiki/Continuous-Running-No-Timers-Needed Continuous Running No Timers Needed] - Configuration des blocs de programmation pour qu'ils s'exécutent automatiquement sans avoir besoin d'utiliser une minuterie.
 +
* [https://forum.keenswh.com/threads/tutorial-constructor-and-save.7382338/ Tutorial: Constructor And Save] - Sauvegarder et recharger les données
 +
* [https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/operators/ C# Operators] - Référence du langage C# pour tous les opérateurs (et, ou, supérieur à, inférieur à, etc).
 +
* [https://fresc81.github.io/SpaceEngineers/index.html Space Engineers API documentation]
 +
* [https://bloc97.github.io/SpaceEngineersModAPIDocs/html/b2d609dc-672a-3d90-cdc0-3753ce60d06f.htm Space Engineers ModAPI Documentation] - Comprend de nombreuses méthodes et propriétés API qui peuvent être utilisées par les blocs programmables.
  
−
Les variables '''globales''' - Ces variables vont garder leurs valeurs durant toute la durée de vie du script. Par exemple : si certaines variables ont besoin de garder leurs valeurs entre deux lignes de code, les variables auront besoin d'être définies en dehors du code. Après avoir cliquer sur "Enregistrer et quitter" ou juste "Enregistrer", toutes les variables globales seront supprimées.
+
[[Category:Game Mechanics]]

Revision as of 12:49, 19 August 2021

La programmation dans Space Engineers se fait avec le Bloc programmable qui peut recevoir des scripts écrits en C# (prononcé C Sharp). Cela peut être utilisé pour fabriquer des drones miniers autonomes, des torpilles tueuses de joueurs à longue portée, des bras de soudage automatisés pour la construction de navires et bien plus encore.

Introduction

Accéder à l'édition

Un code ne peut être modifié que par un seul joueur à la fois. Si un joueur essaye d'ouvrir l'éditeur alors qu'un autre l'utilise, une notification lui indiquera que l'éditeur est en cours d'utilisation.

Méthode principale

Lorsque l'éditeur est ouvert pour la première fois, la méthode void Main() s’affiche automatiquement. C'est le point d'entrée qui sera appelé lors de l'exécution du script. Si la méthode Main est supprimée ou renommée, le script ne s'exécutera pas et vous en serez averti dans la zone de détails du bloc programmable. Des méthodes et variables personnalisées peuvent être définies et utilisées, mais seule la méthode Main sera appelée sans référence.

Durée de vie et portée des variables

Les variables peuvent être utilisées de deux façons différentes :

Locales (à l'intérieur des méthodes) 
ces variables ne gardent leur valeur que pendant l'exécution de la méthode. La valeur est « perdue » dès que la méthode est terminée.
Globales (à l'extérieur des méthodes) 
ces variables conservent leur valeur pendant la durée de vie du script. Par exemple, si la variable doit conserver sa valeur entre des exécutions distinctes du script, elle doit être définie en dehors des méthodes.

Après avoir validé vos modifications et confirmé l'enregistrement, le script précédent sera écrasé et toutes les variables globales seront perdues.

Toutes les variables, locales et globales, à l'exception de la variable de stockage intégrée ("Storage"), perdront leur valeur ou reviendront à leur valeur par défaut lors de la recompilation du code et entre les chargements de parties sauvegardées. La variable de stockage est la solution pour sauvegarder des données à la fin d’une session, afin de les récupérer au redémarrage de la partie ou après la recompilation du script ([explications en anglais]).

Compilation

Le bouton Vérifier le code lance la compilation du code et le résultat de la compilation sera affiché. Le processus de compilation comporte deux étapes : tout d'abord, le code dans l'éditeur est compilé par le compilateur C# pour les erreurs de langage. S'il y a des erreurs lors de la compilation, une boîte de dialogue s'affiche, indiquant la position de l'erreur dans le code et une description de l'erreur.

Après la compilation, le code est vérifié pour l'utilisation d'espaces de noms et de types non autorisés. Si cette vérification échoue, une boîte de dialogue s'affiche : Dans ce cas, System.IO.Directory a été utilisé pour supprimer un répertoire. Ceci est interdit et une erreur s'affiche indiquant que « Not allowed type was used in script » (Trad: un type non autorisé a été utilisé dans le script). [Manque l'image d'exemple...]

Si la compilation et les vérifications réussissent, une boîte de dialogue s'affiche, confirmant les vérifications réussies. Vous pouvez sortir en cliquant sur OK et le code est alors enregistré.

Exécution des scripts

Le script peut être déclenché par les moyens suivants :

1. En appuyant sur le bouton Exécuter dans les propriétés du terminal du bloc programmable.

2. En attribuant une action au terminal et en appuyant manuellement sur le bouton d'action (1 à 9) tout en contrôlant la grille à l'aide du cockpit ou d'un poste de contrôle.

3. En appuyant sur le bouton d'un tableau de commande, dont l'action assignée est "Exécuter".

4. Par une minuterie (Bloc temporisateur) avec l'action assignée "Exécuter".

5. Par un autre script dans un autre bloc programmable de la même grille.

6. Par antenne avec bloc programmable assigné, lors de la réception d'un message d'une autre antenne. (voir Antenna#Programming


7. Par le script lui-même, en affectant une valeur à la variable Runtime.UpdateFrequency. Dans ce cas, aucun argument ne peut être spécifié. Cependant, vous pouvez utiliser la signature de méthode Main suivante : 

void Main(string argument, UpdateType updateSource)

Vous pourrez ainsi accéder aux informations sur ce qui a exactement déclenché le script. Le script "connaîtra" comment il a été déclenché, par des événements Update1, Update10, Update100, ou manuellement, ou tout autre événement ayant provoqué l'exécution du déclencheur.

Le script est exécuté uniquement sur le serveur même s'il est déclenché depuis le client. S'il y a une exception pendant l'exécution du script, tous les clients seront informés de l'échec dans la zone de détails du bloc programmable. En cas d'exception lors de l'exécution du script, le script ne sera pas exécuté à nouveau à moins que l'utilisateur n'ouvre l'éditeur et modifie le script.

Comptage des instructions

Chaque fois que le script est exécuté, chaque instruction du script est comptée. Si le script exécute plus d'instructions que la limite, l'exécution est arrêtée et l'utilisateur est averti que le script est trop complexe pour être exécuté. Cela empêche les scripts de "geler" le jeu.

Liste blanche

Les types et classes autorisés dans les scripts sont restreints. Reportez-vous à la liste blanche de script pour voir ce que vous êtes autorisé à utiliser.

Interfaces disponibles

Actions possible

Actuellement, seules les actions de terminal peuvent être déclenchées dans les scripts. L'utilisateur peut accéder au système de terminal pour la grille sur laquelle se trouve le bloc programmable et déclencher n'importe quelle action de terminal sur n'importe quel bloc de la grille.

Classes des blocs (Liste des Actions)

Même classe de bloc pour différents SubTypeID

Certains blocs ont le même parent (par exemple <TypeId> dans cubeblocks.sbc) et ne diffèrent que par le sous-type (par exemple <SubtypeId>). Cela signifie qu'il n'y a pas de distinction entre ces blocs dans le code.

Le conteneur est un exemple de ces blocs : il existe 3 types de conteneurs de marchandises dans le jeu : petit, moyen et grand. Ces trois types ne diffèrent que par le sous-type et le type est le même pour eux. L'identifiant du grand conteneur est : 

<Id>
  <TypeId>CargoContainer</TypeId>
  <SubtypeId>LargeBlockLargeContainer</SubtypeId>
</Id>

Le moyen est: 

<Id>
  <TypeId>CargoContainer</TypeId>
  <SubtypeId>SmallBlockMediumContainer</SubtypeId>
</Id>

Et le petit est : 

<Id>
  <TypeId>CargoContainer</TypeId>
  <SubtypeId>LargeBlockSmallContainer</SubtypeId>
</Id>

Dans ce cas, il n'y a qu'une seule classe IMyCargoContainer pour tous les types de conteneurs.

programmes d'exeples

Hello world

Le programme standard Hello World dans Space Engineers peut être écrit comme tel : 

public void Main()
{
   Echo ("Hello, world!");
}

Si ce programme est entré dans un bloc programmable et exécuté, il se traduira par "Hello, world!" affiché dans l'interface du bloc programmable en bas à droite de l'écran.

Obtenir votre position

Ce programme affichera les coordonnées GPS actuelles de la position de votre bloc de programmation dans le monde. 

public void Main()
{
    var pos = Me.GetPosition();
    Echo (pos.ToString());
}


Vérification d'un capteur

Il est facile de faire en sorte qu'un capteur ouvre une porte ou déclenche une autre action même sans aucune programmation si vous placez simplement cette action dans la liste "Actions de configuration" du capteur. Cependant, déclencher une action lorsqu'un capteur ne détecte pas quelque chose est plus difficile et ne peut pas être fait avec des blocs de minuterie. Ce programme vérifiera automatiquement un capteur toutes les 10 ticks (soit environ 6 fois par seconde) et fermera une porte si le capteur ne détecte rien. Cela peut facilement être appliqué à d'autres fins, comme désactiver les foreuses lorsque les astéroïdes ne sont pas à portée du capteur. 

List<MyDetectedEntityInfo> entity_list = new List<MyDetectedEntityInfo>(); 
public Program()
{
    Runtime.UpdateFrequency = UpdateFrequency.Update10;
    //Cela rend le programme exécuté automatiquement toutes les 10 ticks.
}
public void Main()
{
    var door_sensor = GridTerminalSystem.GetBlockWithName("Door Sensor 1") as IMySensorBlock;
    door_sensor.DetectedEntities (entity_list);
    if (entity_list.Count == 0)
    {
        var door = GridTerminalSystem.GetBlockWithName("Door 1") as IMyDoor;
        door.ApplyAction ("Open_Off");
    }
}

Pour que ce script fonctionne, le capteur doit être nommé "Door Sensor 1" et la porte doit être nommée "Door 1". Si vous configurez le capteur pour ouvrir la porte, la porte s'ouvrira automatiquement lorsque le joueur entre dans la plage du capteur et se fermera lorsque le joueur quitte la plage du capteur.

Erreurs de compilation

Il s'agit d'une liste (en cours) des erreurs de compilation connues et de leurs causes.

  • Method name expected (Nom de la méthode attendu) : le compilateur a trouvé des parenthèses alors qu'il ne les attendait pas. Vous pourriez avoir poublié un nom de méthode avant les parenthèses, ou vous pourriez utiliser de manière inappropriée des parenthèses au lieu de crochets ou d'accolades, selon ce que vous essayez de faire.

Voir également

  • MyGridTerminalSystem - Méthodes pour obtenir des références d'objets à vos divers composants de vaisseau.
  • Programming Guide/Action List - Actions que vous pouvez appliquer aux objets via la méthode Object.ApplyAction. Comprend également certaines des propriétés de l'objet.

Liens externes

Retrieved from "http://spaceengineerswiki.com/index.php?title=Programming_Guide/fr&oldid=29374"