# Ton premier script

Écris un court script Lua qui dessine un soleil, exécute-le, annule-le et enregistre-le.

_Les raccourcis sont écrits pour Windows et Linux. Sur Mac, utilise ⌘ Cmd là où il est écrit Ctrl, et ⌥ Option pour Alt._

Les scripts sont de petits programmes Lua qui dessinent et modifient ton sprite à ta place : tout ce
que tu peux faire avec les outils, un script peut le faire avec du code. Ce guide t'explique pas à pas
comment en écrire un qui dessine un soleil sur un nouveau calque. Il te faudra environ cinq minutes, et
tu n'as pas besoin d'avoir déjà programmé.

## Créer un script

Ouvre un sprite (un nouveau de 32×32 convient très bien) et choisis Scripts > Nouveau script.... Nomme le script « Soleil »
et appuie sur **Créer**.

Le panneau **Scripts** s'ouvre avec quelques lignes de commentaire (des lignes qui commencent par `--`, que Lua
ignore). Il comprend un éditeur de code, une barre d'outils en haut et une zone de sortie en bas. Dans
la disposition par défaut, il s'ancre à droite du canevas, ce qui te permet de voir les deux en même temps (tu peux le déplacer
comme n'importe quel panneau : voir [L'espace de travail](https://pxstud.io/fr/docs/manual/guides/workspace.md)).

![Le panneau Scripts affichant le code du script Soleil, avec les boutons Exécuter, Enregistrer le brouillon et Publier en haut et la ligne qu'il a affichée dans la zone de sortie en dessous](https://pxstud.io/scripting/images/first-script-panel.light.webp)

_Le panneau Scripts avec le script du soleil, après son exécution_

## L'écrire

Remplace les commentaires par ceci :

```lua
-- Draws a sun on a new layer.
local layer = app.addLayer("Sun")
local frame = app.getActiveFrameId()
local w, h = app.getCanvasWidth(), app.getCanvasHeight()
local cx, cy = w // 2, h // 2
local r = math.min(w, h) // 4

-- the rays: eight short lines around the middle
for i = 0, 7 do
  local a = i * math.pi / 4
  app.drawLine(layer, frame,
    cx + math.floor(math.cos(a) * (r + 2) + 0.5), cy + math.floor(math.sin(a) * (r + 2) + 0.5),
    cx + math.floor(math.cos(a) * (r + 5) + 0.5), cy + math.floor(math.sin(a) * (r + 5) + 0.5),
    { color = "#f4a52e" })
end

-- the disc
app.drawEllipse(layer, frame, cx - r, cy - r, cx + r, cy + r, { color = "#ffd34e", fill = "filled" })
print("Drew a sun " .. (r * 2 + 1) .. " pixels across.")
```

Ce qu'il fait :

- `app.addLayer` ajoute un calque nommé « Sun » et renvoie son identifiant ; `app.getActiveFrameId` donne
  l'image sur laquelle tu te trouves. Chaque commande de dessin prend un calque et une image, comme un outil peint sur le
  calque actif à l'image courante.
- `app.getCanvasWidth` et `app.getCanvasHeight` lisent la taille du sprite, pour que le soleil s'adapte à
  n'importe quel canevas. Les coordonnées sont en pixels, avec (0, 0) dans le coin supérieur gauche.
- `app.drawLine` et `app.drawEllipse` fonctionnent exactement comme les outils Ligne et Ellipse.
  Tout ce que tu ne précises pas (ici, le pinceau) vient des réglages de l'outil courant.
- `print` écrit une ligne dans la zone de sortie.

Pendant que tu tapes, l'éditeur te suggère des fonctions `app.` ; pointe-en une pour lire ce qu'elle fait.

## L'exécuter

Appuie sur **Exécuter** (le bouton de lecture) dans la barre d'outils du panneau. La zone de sortie affiche « Drew a sun 17
pixels across. », et la chronologie a un nouveau calque, « Sun », avec le soleil sur le canevas à côté du panneau.

Si quelque chose ne va pas, la zone de sortie affiche l'erreur et la ligne où elle s'est produite est mise en évidence.
Corrige-la et exécute de nouveau.

## L'annuler

Tout ce qu'une exécution modifie forme **une seule étape d'annulation** : appuie sur `Ctrl+Z` et le calque et le soleil disparaissent
ensemble. Change une couleur ou le `+ 5` qui définit la longueur des rayons, et exécute de nouveau.

## L'enregistrer

Appuie sur **Enregistrer le brouillon** (le bouton disquette). Le script est enregistré dans ce navigateur, comme tes sprites,
et un `*` après son nom dans le panneau signale des modifications non enregistrées. Pour le rouvrir plus tard, choisis
Scripts > Ouvrir mon script... ; les cinq derniers scripts ouverts sont aussi listés juste en dessous dans le
menu Scripts.

**Publier** partage un script dans la bibliothèque de scripts ; il faut pour cela un compte avec Sync (voir
[le guide des scripts](https://pxstud.io/fr/docs/scripting/guide.md#saving-and-publishing)).

## Pour aller plus loin

- [Le guide des scripts](https://pxstud.io/fr/docs/scripting/guide.md) couvre l'exécution, l'arrêt, les fenêtres de script, les commandes de script
  et les générateurs officiels.
- L'[API de script](https://pxstud.io/fr/docs/scripting.md) liste chaque fonction `app.`, regroupée par usage :
  [dessin](https://pxstud.io/fr/docs/scripting/drawing.md), [calques](https://pxstud.io/fr/docs/scripting/layers.md),
  [images](https://pxstud.io/fr/docs/scripting/frames.md), [calcul de couleurs](https://pxstud.io/fr/docs/scripting/color.md) et plus encore.