Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Lumières et Ombres 2D

Introduction

Par défaut, les scènes 2D dans Godot sont non ombragées, sans lumières et ombres visibles. Bien que c'est rapide à rendre, les scènes non ombragées peuvent paraître fades. Godot fournit la capacité d'utiliser l'éclairage 2D en temps réel et les ombres, qui peuvent grandement améliorer le sens de profondeur dans votre projet.

Pas de lumières ou d'ombres 2D, la scène n'est pas ombragée

Nœuds

Il y a plusieurs nœuds impliqués dans une installation d'éclairage 2D complète :

CanvasModulate (pour assombrir le reste de la scène)
PointLight2D (pour des projecteurs ou des lumières omnidirectionnelles)
DirectionalLight2D (pour la lumière du soleil ou de la lune)
LightOccluder2D (for light shadow casters)
Other 2D nodes that receive lighting, such as Sprite2D or TileMapLayer.

CanvasModulate est utilisé pour obscurcir la scène en spécifiant une couleur qui agira comme une couleur "ambiante" de base. C'est la couleur d'éclairage finale dans les zones qui sont non atteints par n'importe quelle lumière 2D. Sans un nœud CanvasModulate, la scène finale aurait l'air trop brillante car les lumières 2D ne feraient qu'éclairer l'apparence existante sans ombrage (qui semble entièrement éclairée).

Les Sprite2D sont utilisés pour afficher les textures des globes de lumière, de l’arrière-plan et des projecteurs d'ombre.

Les nœuds PointLight2Ds sont utilisés pour éclairer la scène. La manière dont fonctionne une lumière consiste généralement à ajouter une texture sélectionnée sur le reste de la scène pour simuler l'éclairage.

LightOccluder2Ds are used to tell the shader which parts of the scene cast shadows. These occluders can be placed as independent nodes or can be part of a TileMapLayer node.

Les ombres n'apparaissent que dans les zones couvertes par la PointLight2D et leur direction est basée sur le centre de la Light.

Note

La couleur d'arrière-plan ne reçoit pas d'éclairage. Si vous voulez que la lumière s'applique sur le fond, vous devez ajouter une représentation visuelle pour l'arrière-plan, comme un Sprite2D.

Les propriétés Région du Sprite2D peuvent être utiles pour créer rapidement une texture d'arrière plan répétitive, mais n'oubliez pas de définir également Texture > Répéter sur Activé dans les propriétés du Sprite2D.

Lumières ponctuelles

Les lumières ponctuelles (aussi appellées lumières positionnelles) sont l'élément le plus courant dans l'éclairage 2D. Les lumières point peuvent être utilisées pour représenter la lumière d'une torche, d'un feu, d'un projectile, etc.

PointLight2D offre les propriétés suivantes à ajuster dans l'inspecteur :

Texture: La texture à utiliser comme source lumineuse. La taille de la texture détermine la taille de la lumière. La texture peut avoir un canal alpha, qui est utile lors de l'utilisation du mode de fondu Mix des Light2D, mais n'est pas requis lors de l'utilisation des modes de fondu Ajouter (par défaut) ou Soustraire.
Offset: Le décalage pour la texture de la lumière. Contrairement au déplacement du nœud lumière, la modification du décalage ne fait pas bouger les ombres.
Texture Scale: Le multiplicateur pour la taille de la lumière. Des valeurs plus élevées feront s'étendre la lumière plus loin. Les lumières plus grandes ont un coût de performance plus élevé car elles affectent plus de pixels à l'écran, alors pensez-y avant d'augmenter la taille d'une lumière.
Height: La hauteur virtuelle de la lumière en prenant en compte le mappage normal. Par défaut, la lumière est très proche des surfaces recevant la lumière. Cela rendra l'éclairage à peine visible si le mappage normal est utilisé, donc pensez à augmenter cette valeur. La modification de la hauteur de la lumière ne fait une différence visible que sur les surfaces qui utilisent le mappage normal.

Si vous n'avez pas de texture prédéfinie à utiliser dans une lumière, vous pouvez utiliser cette texture "neutre" de lumière ponctuelle (clic-droit > Enregistrer l'image sous...) :

Si vous avez besoin d'une atténuation différente, vous pouvez créer procéduralement une texture en assignant un Nouveau GradientTexture2D à la propriété Texture de la lumière. Après avoir créé la ressource, étendez sa section Fill et définissez le mode de remplissage sur Radial. Vous devrez ensuite ajuster le dégradé lui-même pour qu'il aille d'un blanc opaque à un blanc transparent, et bouger sa position de départ pour qu'elle soit en son centre.

Directional light

Une nouveauté de Godot 4.0 est la possibilité d'avoir un éclairage directionnel en 2D. L'éclairage directionnel est utilisé pour représenter la lumière du soleil ou de la lune. Les rayons lumineux sont émis parallèles les uns aux autres, comme si le soleil ou la lune étaient infiniment loin de la surface qui reçoit la lumière.

DirectionalLight2D offre les propriétés suivantes :

Height: La hauteur virtuelle de la lumière en prenant en compte le mappage normal (0.0 = parallèle aux surfaces, 1.0 = perpendiculaire aux surfaces). Par défaut, la lumière est parallèle aux surfaces qu'elle affecte. Cela rendra l'éclairage à peine visible si le mappage normal est utilisé, donc pensez à augmenter cette valeur. La modification de la hauteur de la lumière ne fait une différence visible que sur les surfaces qui utilisent le mappage normal. La Height n'affecte pas l'apparence des ombres.
Max Distance : La distance maximale (en pixels) par rapport au centre de la caméra à laquelle les objets peuvent être avant que leurs ombres ne soient supprimées. Diminuer cette valeur peut empêcher les objets situés en dehors de la vue de la caméra de projeter des ombres (tout en améliorant la performance). Le zoom Camera2D n'est pas pris en compte par Max Distance, ce qui veut dire qu'à des valeurs de zoom plus élevées, les ombres sembleront s'estomper plus tôt lors du zoom sur un point donné.

Note

Les ombres directionnelles sembleront toujours être infiniment longues, peu importe la valeur de la propriété Height. C'est une limitation de la méthode de rendu d'ombre utilisée pour les lumières 2D dans Godot.

Pour avoir des ombres directionnelles qui ne sont pas infiniment longues, vous devrez désactiver les ombres dans le DirectionalLight2D et utiliser un shader personnalisé qui lit le champ de distance signé 2D à la place. Ce champ de distance est généré automatiquement à partir des noeuds LightOccluder2D présents dans la scène.

Propriétés communes des lumières

PointLight2D et DirectionalLight2D offrent des propriétés communes, qui font partie de la classe parente Light2D :

Enabled: Permet de basculer la visibilité de la lumière. Contrairement au masquage du noeud lumière, désactiver cette propriété ne masquera pas les enfants de la lumière.
Editor Only: Si cette option est activée, la lumière n'est visible que dans l'éditeur. Elle sera automatiquement désactivée lors de l'exécution du projet.
Couleur : la couleur de la lumière.
Energy : Le multiplicateur d'intensité de la lumière. Des valeurs plus élevées donnent une lumière plus brillante.
Blend Mode : La formule de fondu utilisée pour les calculs de lumière. La valeur par défaut Add est suffisante pour la plupart des cas d'utilisation. Subtract peut être utilisée pour les lumières négatives, qui ne sont pas physiquement vraisemblables mais peuvent être utilisées pour des effets spéciaux. Le mode de fondu Mix mélange la valeur des pixels correspondant à la texture de la lumière avec les valeurs des pixels situés en dessous par interpolation linéaire.
Range > Z Min: L'indice Z le plus faible affecté par la lumière.
Range > Z Max: L'indice Z le plus élevé affecté par la lumière.
Range > Layer Min: La couche visuelle la plus basse affectée par la lumière.
Range > Layer Max: La couche visuelle la plus haute affectée par la lumière.
Range > Item Cull Mask : Contrôle quels noeuds reçoivent la lumière émise par ce noeud, en fonction des couches visuelles Occluder Light Mask activées des autres noeuds. Cela peut être utilisé pour empêcher certains objets de recevoir de la lumière.

Mise en place des ombres

Après avoir activé la propriété Shadow > Enabled sur un noeud PointLight2D ou DirectionalLight2D, vous ne verrez initialement pas de différence visuelle. Cela est dû au fait qu'aucun noeud dans votre scène ne possède d'occulteurs, qui sont utilisés comme base pour la projection d'ombres.

Pour que des ombres apparaissent dans la scène, des noeuds LightOccluder2D doivent être ajoutés à la scène. Ces noeuds doivent aussi avoir des polygones d'occlusion conçus pour correspondre au contour du sprite.

En plus de leur ressource polygone (qui doit être définie pour avoir un effet visuel), les nœuds LightOccluder2D ont deux propriétés :

SDF Collision: Si ce paramètre est activé, l'occulteur fera partie d'un champ de distance signé généré en temps réel qui peut être utilisé dans les shaders personnalisés. Lorsque vous n'utilisez pas de shaders personnalisés qui lisent ce SDF, activer ce paramètre ne fait aucune différence visuelle et n'a aucun coût de performance, donc ce paramètre est activé par défaut pour plus de commodité.
Occluder Light Mask: Ce paramètre est utilisé en tandem avec la propriété Shadow > Item Cull Mask des PointLight2D et DirectionalLight2D pour contrôler quels objets projettent des ombres pour chaque lumière. Cela peut être utilisé pour empêcher certains objets de projetter des ombres.

There are two ways to create light occluders:

Automatically generating a light occluder

Les occulteurs peuvent être créés automatiquement à partir des nœuds Sprite2D en sélectionnant le nœud, en cliquant sur le menu Sprite2D en haut de l'éditeur 2D, puis en choisissant Create LightOccluder2D Sibling.

Dans la boîte de dialogue qui s'affiche, un contour entourera votre sprite. Si le contour correspond bien aux bords du sprite, vous pouvez cliquer sur OK. Si le contour est trop éloigné des bords du sprite (ou "empiète" sur les bords du sprite), ajustez les paramètres Grow (pixels) et Shrink (pixels), puis cliquez sur Update Preview. Répétez cette opération autant que de besoin.

Dessiner manuellement un obturateur de lumière

Créez un nœud LightOccluder2D, puis sélectionnez le et cliquez sur le bouton "+" en haut de l'éditeur 2D. Lorsque l'on vous demande de créer une ressource de polygone, répondez Yes. Vous pouvez ensuite commencer à dessiner un polygone occultant en cliquant pour créer de nouveaux points. Vous pouvez supprimer des points existants avec un clic droit, et créer de nouveaux points à partir de la ligne existante en cliquant sur la ligne, puis en la faisant glisser.

Les propriétés suivantes peuvent être ajustées sur des lumières 2D qui ont les ombres activées :

Color: La couleur des zones ombragées. Par défaut, les zones ombragées sont entièrement noires, mais cela peut être modifié à des fins artistiques. Le canal alpha de la couleur contrôle dans quelle mesure l'ombre est teintée par la couleur spécifiée.
Filter: Le mode de filtrage à utiliser pour les ombres. Le mode par défaut None a une rendu plus rapide convenant bien aux jeux avec une esthétique pixel art (en raison de son aspect "pixélisé"). Si vous souhaitez une ombre douce, utilisez PCF5. PCF13 est encore plus doux, mais c'est le plus exigeant en termes de rendu. PCF13 ne devrait être utilisé que pour un petit nombre de lumières simultanément en raison de son coût élevé en rendu.
Filter Smooth: Contrôle la quantité de flou appliquée aux ombres lorsque Filter est défini sur PCF5 ou PCF13. Des valeurs plus élevées produisent une ombre plus douce, mais peuvent entraîner l'apparition d'artéfacts (en particulier avec PCF5).
Item Cull Mask : Contrôle quels nœuds LightOccluder2D projettent des ombres, en fonction de leurs propriétés respectives Occluder Light Mask.

Ombres douces (PCF13, Lissage de filtre 1.5)

Des ombres douces avec des artefacts de traînées en raison de **Filter Smooth** trop élevé (PCF5, **Filter Smooth** à 4)

Ordre de dessin des occludeurs

Les LightOccluder2D suivent l'ordre de dessin 2D habituel. Cela est important pour l'éclairage 2D, car c'est ainsi que vous contrôlez si le LightOccluder2D doit occulter le sprite lui-même ou non.

Si le nœud LightOccluder2D est un frère du sprite, le LightOccluder2D occultera le sprite lui-même si celui-ci est placé en dessous du sprite dans l'arborescence de la scène.

Si le nœud LightOccluder2D est un enfant du sprite, le LightOccluder2D occultera le sprite lui-même si Show Behind Parent est désactivé sur le nœud LightOccluder2D (ce qui est le comportement par défaut).

Cartes de normal et spéculaire

Les cartes normales et les cartes spéculaires peuvent considérablement améliorer la sensation de profondeur de votre éclairage 2D. De manière similaire à leur fonctionnement en rendu 3D, les cartes normales permettent de rendre l'éclairage moins plat en variant son intensité en fonction de la direction de la surface recevant la lumière (pixel par pixel). Les cartes spéculaires améliorent encore les visuels en faisant réfléchir une partie de la lumière vers le spectateur.

Les PointLight2D et DirectionalLight2D prennent en charge les cartes normales et les cartes spéculaires. Depuis Godot 4.0, les cartes normales et spéculaires peuvent être assignées à n'importe quel élément 2D, y compris les nœuds qui héritent de Node2D ou Control.

Une carte normale représente la direction vers laquelle chaque pixel est "orienté". Cette information est ensuite utilisée par le moteur pour appliquer correctement l'éclairage sur les surfaces 2D de manière physiquement plausible. Les cartes normales sont généralement créées à partir de cartes de hauteur faites à la main, mais elles peuvent également être générées automatiquement à partir d'autres textures.

Une carte spéculaire définit la quantité de lumière que chaque pixel doit réfléchir (et quelle couleur, si la carte spéculaire contient de la couleur). Des valeurs plus lumineuses entraîneront une réflexion plus intense à cet endroit précis de la texture. Les cartes spéculaires sont généralement créées manuellement, en utilisant la texture diffuse comme base.

Astuce

Si vous n'avez pas de cartes normales ou spéculaires pour vos sprites, vous pouvez les générer en utilisant l'outil gratuit et open source Laigter <https://azagaya.itch.io/laigter>.

Pour configurer des cartes normales et/ou des cartes spéculaires sur un nœud 2D, créez une nouvelle ressource CanvasTexture pour la propriété qui dessine la texture du nœud. Par exemple, sur un Sprite2D :

Créer une ressource **CanvasTexture** pour un nœud **Sprite2D**

Développez la ressource nouvellement créée. Vous y trouverez plusieurs propriétés que vous devrez ajuster :

Diffuse > Texture : La texture de couleur de base. Dans cette propriété, chargez la texture que vous utilisez pour le sprite lui-même.
Normal Map > Texture : La texture de la carte normale. Dans cette propriété, chargez une texture de carte normale que vous avez générée à partir d'une carte de hauteur (voir l'astuce ci-dessus).
Specular > Texture : La texture de la carte spéculaire, qui contrôle l'intensité spéculaire de chaque pixel sur la texture diffuse. La carte spéculaire est généralement en niveaux de gris, mais elle peut également contenir de la couleur pour multiplier la couleur des réflexions en conséquence. Dans cette propriété, chargez une texture de carte spéculaire que vous avez créée (voir l'astuce ci-dessus).
Specular > Color: Le multiplicateur de couleur pour les réflexions spéculaires.
Specular > Shininess : L'exposant spéculaire à utiliser pour les réflexions. Des valeurs plus faibles augmenteront la brillance des réflexions et les rendront plus diffuses, tandis que des valeurs plus élevées rendront les réflexions plus localisées. Des valeurs élevées conviennent mieux aux surfaces ayant un aspect mouillé.
Texture > Filter : Peut être défini pour remplacer le mode de filtrage de la texture, indépendamment de la valeur définie dans la propriété du nœud (ou du paramètre de projet Rendering > Textures > Canvas Textures > Default Texture Filter).
Texture > Repeat : Peut être défini pour remplacer le mode de répétition de la texture, indépendamment de la valeur définie dans la propriété du nœud (ou du paramètre de projet Rendering > Textures > Canvas Textures > Default Texture Repeat).

Après avoir activé le normal mapping, vous remarquerez peut-être que vos lumières semblent plus faibles. Pour résoudre ce problème, augmentez la propriété Height sur vos nœuds PointLight2D et DirectionalLight2D. Vous pouvez également vouloir augmenter légèrement la propriété Energy des lumières pour revenir à l'intensité de l'éclairage avant d'activer le normal mapping.

Utiliser les sprites additifs comme alternative plus rapide aux lumières 2D

Si vous rencontrez des problèmes de performance lors de l'utilisation de lumières 2D, il peut être utile de remplacer certaines d'entre elles par des nœuds Sprite2D qui utilisent le mélange additif. Ceci est particulièrement adapté aux effets dynamiques à courte durée, comme les balles ou les explosions.

Les sprites additifs sont beaucoup plus rapides à rendre, car ils n'ont pas besoin de passer par une pipeline de rendu séparée. De plus, il est possible d'utiliser cette approche avec AnimatedSprite2D (ou Sprite2D + AnimationPlayer), ce qui permet de créer des « lumières » animées 2D.

Cependant, les sprites additifs ont quelques désavantages par rapport aux lumières 2D :

La formule de mélange est inexacte par rapport à l'éclairage 2D "réel". Ce n'est généralement pas un problème dans des zones suffisamment éclairées, mais cela empêche les sprites additifs d'éclairer correctement les zones qui sont complètement sombres.
Les sprites additifs ne peuvent pas projeter des ombres, car ils ne sont pas des lumières.
Additive sprites ignore normal and specular maps used on other sprites.

Pour afficher un sprite avec du mélange additif, créez un nœud Sprite2D et assignez lui une texture. Dans l'inspecteur, faites défiler jusqu'à la section CanvasItem > Matériau, dépliez-la et cliquez sur le menu déroulant à côté de la propriété Matériau. Choisissez Nouveau CanvasItemMaterial, cliquez sur le matériau nouvellement créé pour le modifier, puis définissez Mode de mélange à Addition.