Zeus Lights & Shadows : Manuel d'utilisation

# Zeus Lights & Shadows : Manuel d'utilisation v1.3
=begin
  Description :
      Ce script permet d'afficher des effets de lumière et des ombres.
      Il existe déjà pleins de scripts pour ajouter des loupiotes, mais mon but
      avec celui ci est de faire quelque chose de différent.
      Ainsi les lumières éclairent la nuit, c'est à dire qu'on peut mettre
      le ton de l'écran tout noir à -255 les lumières feront comme des trous
      dans un masque et nous permettrons de voir la map de façon claire et nette.
      Les ombres quant à elles ne sont pas dynamiques, les lumières n'engendrent
      aucune ombre, les ombres doivent être placées manuellement, un peu comme
      sous VXace, y'a qu'à considérer que ce sont toutes des ombres du soleil.
      La nouveauté c'est que les ombres ne se superposent pas (ce qui est
      absurde) mais fusionnent.
      Les ombres ne sont pas au dessus de tout mais au dessous, on peut avoir la
      tête qui passe devant une ombre, les chara s'assombrissent que quand ils
      marchent dans l'ombre.
      L'opacité des ombres décline avec la luminosité de la map,
      c'est à dire pas d'ombre du soleil la nuit (waw).
      Les ombres auto de VX et celles de VXace sont gérées par ce script.
      Y'a aussi moyen de les désactiver au tout début du script.
      Les commandes suivantes s'utilisent toutes dans des insertions de scripts.

  Log Change :
    1.3 :
      - nouvelle option pour désactiver les lumières au tout début du script
      - nouvelle option pour désactiver les ombres au tout début du script
      - nouvelle option dans les events pour les empêcher d'être ombrés
      - nouvelle option dans les ombres pour définir si elles doivent ombrer
        les charas ou pas
      - nouvelle option qui permet de ne pas nommer les lumières/ombres
        un nom sera automatiquement attribué par rapport à l'event qui le crée
      - réparé bug d'affichage par rapport aux scripts qui modifient
        la taille de l'écran pendant le jeu même si c'est absurde
      - réparé bug d'affichage par rapport au tremblement de l'écran
    1.2 :
      - réparé bug sur XP
      - ajout d'un listing rapide des fonctions dans la doc
    1.1 :
      - réparé bug par rapport au régions sur VXace

  Conseils d'utilisation :
      1/ héros/véhicules vs event/map
          Le script nous offre la possibilité d'associer des lumières/ombres aux
          héros, vehicules, events ou directement à la map.
          Ce qu'il faut savoir c'est que les lumières/ombres associées aux
          héros/véhicules sont mémorisées d'une map à l'autre, on a besoin de
          les initialiser qu'une seule fois et elles resteront jusqu'à ce qu'on
          décide de les supprimer.
          Quant aux events/maps c'est l'inverse, les lumières/ombres sont
          supprimées à chaque fois qu'on change de map, il faut donc faire en
          sorte qu'elles soient initialisées à chaque fois qu'on entre dans la map.
      2/ initialisation
          J'ai créé une commande spéciale qui permet d'exécuter automatiquement
          des scripts au chargement des events, ça s'utilise comme ça :
            Commentaire: <setup>
            Script: ...scripts d'initialisation des lumières/ombres...
            Commentaire: </setup>
          Tout ce qui se trouve entre les balises <setup> sera exécuté
          automatiquement (et uniquement) lors du chargement de la page
          (même si censé être déclenché par la touche action).
          A vrai dire si on veut on peut mettre autre chose que des scripts entre
          ces deux balises, il faut juste éviter les commandes qui doivent
          attendre d'être effectuées/validées (genre des messages) sinon boom.
          Si on veut on peut initialiser toutes nos lumières/ombres à partir d'un
          seul event, cela dit si on décide de lier notre lumière à un event il
          sera peut être plus pratique d'avoir l'initialisation de sa lumière
          directement à l'intérieur de ses pages.
          Si un event a plusieurs pages seules les commandes de la page active
          seront exécutées.

  Liste rapide des fonctions :
    - light(key).setup(filename)
    - light(key).chara_id = n
    - light(key).clear
    - light(key).active
    - light(key).set_pos(x, y, duration)
    - light(key).set_origin(x, y, duration)
    - light(key).set_parallax(x, y, duration)
    - light(key).set_opacity(opacity, duration)
    - light(key).set_color(red, green, blue, alpha, duration)
    - light(key).set_zoom(zoom, duration)
    - light(key).set_flicker(variance, refresh_rate, duration)
    - light(key).set_angle(angle, duration)
    - light(key).set_wave(amp, length, speed, duration)
    - light(key).visible = true ou false
    - light(key).blend_type = 0 ou 1 ou 2
    - light(key).directions = n
    - light(key).patterns = n
    - light(key).anime_rate = n
    - shadow(key).setup(filename)
    - shadow(key).setup(width, height)
    - shadow(key).chara_id = n
    - shadow(key).clear
    - shadow(key).active
    - shadow(key).set_pos(x, y, duration)
    - shadow(key).set_origin(x, y, duration)
    - shadow(key).set_parallax(x, y, duration)
    - shadow(key).set_opacity(opacity, duration)
    - shadow(key).set_color(red, green, blue, alpha, duration)
    - shadow(key).set_zoom(zoom, duration)
    - shadow(key).visible = true ou false
    - shadow(key).directions = n
    - shadow(key).patterns = n
    - shadow(key).anime_rate = n
    - shadow(key).shadowable = true ou false
    - set_shadowable(value, chara_id)

  Lumières :
    - light(key).setup(filename)
            Initialise une nouvelle lumière.
        key = un identifiant pour notre lumière, chaque lumière doit avoir un
            nom qui lui est propre.
            On réutilise son identifiant à chaque fois qu'on veut modifier une
            lumière.
            On peut ne pas mettre d'identifiant le script en génèrera alors un
            automatiquement en prenant l'id de l'event qui exécute le script,
            par exemple "event5".
            Ca peut être intéressant si par exemple on met une lumière dans un
            event et qu'on a envie d'en faire des copier/coller, plutôt que de
            devoir modifier le nom dans chaque event on en met pas et on laisse
            faire le script.
        filename = le nom du fichier utilisé pour la lumière.
            L'extension n'est pas obligatoire.
            Le fichier doit se trouver dans le dossier Pictures, vous pouvez
            utiliser des sous dossiers si vous voulez avec des / comme séparateurs.
            La lumière doit être de couleur noire sur fond transparent,
            c'est important pour le fonctionnement interne du script.
            Pour donner une couleur à la lumière c'est expliqué plus bas.
        Exemple :
            light("lumière 1").setup("torch.png") # nouvelle lumière
            light.setup("torch.png") # nouvelle lumière sans identifiant

    - light(key).chara_id = n
            Permet de lier une lumière à un chara (event, héros, véhicule).
            Ça a plusieurs effets, la lumière suivra automatiquement son chara.
            La lumière synchronisera direction et animation si possible.
            Si la lumière est associée à un event elle disparaîtra si jamais
            l'event est transparent, si l'event est supprimé, ou encore si
            l'event n'a aucune page d'activée (aka si les conditions d'aucune de
            ses pages ne sont remplies).
        n = id du character sur lequel afficher la lumière.
            Si on met 0 la lumière ne suivra aucun chara, elle aura des
            coordonnées relatives à la map.
            Si on met un nombre > 0, la lumière suivra l'event correspondant.
            Si on met @event_id ça veut dire "cet event", celui qui exécute le script.
            Si on met -1 la lumière suivra le héros.
            Si on met -2, -3, -4, c'est pour les alliés. (VXace uniquement)
            Si on met -5, -6, -7, c'est pour les véhicules (VX & VXace uniquement)
            respectivement la barque, le bateau et le dirigeable.
            La valeur par défaut est 0.
        Exemple :
            light("lumière 1").chara_id = -1 # lie la lumière au héros

    - light(key).clear
            Supprime une lumière, tout simplement.
        Exemple :
            light("lumière 1").clear # supprime la lumière

    - light(key).active
            Retourne true ou false selon qu'une lumière existe ou pas.
            C'est fait pour être utilisé dans des conditions.
        Exemple :
            light("lumière 1").active == true # la lumière existe ?
            light("lumière 1").active == false # la lumière a été supprimée ?

    - light(key).set_pos(x, y, duration)
            S'il n'y a pas de chara_id les coordonnées de la lumière seront
            définies par rapport au  coin au gauche de la map.
            S'il y a un chara_id les coordonnées de la lumière seront
            automatiquement celles du chara sélectionné, cette fonction servira
            alors à définir un décalage.
        x = coordonnée x en pixels
        y = coordonnée y en pixels
        duration = la durée de transition en nombre de frames.
            Les coordonnées changeront entre leur valeur actuelle et celle voulu
            sur la durée donnée.
            Ça peut permettre de faire bouger une lumière.
            0 = pas de transition.
            On peut omettre cette argument, ce qui mettra sa valeur à 0.
            Ça sera la même chose partout donc je ne répéterai pas.
        Exemple :
            light("lumière 1").set_pos(128, 256, 60) # set_pos avec transition de 60 frames
            light("lumière 1").set_pos(128, 256) # set_pos sans transition

    - light(key).set_origin(x, y, duration)
            Change le point d'origine de l'image.
        x = coordonnée x du centre de l'image en pourcentage.
            0 = tout à gauche.
            100 = tout à droite.
            La valeur par défaut est 50.
        y = coordonnée y du centre de l'image en pourcentage.
            0 = tout en haut.
            100 = tout en bas.
            La valeur par défaut est 50.
        Exemple :
            light("lumière 1").set_origin(0, 0) # Origine au coin haut-gauche

    - light(key).set_parallax(x, y, duration)
            Cette option permet de gérer le niveau d'ancrage de la lumière sur
            la map, càd quand la map défile la lumière défilera à une vitesse
            différente, comme les panoramas quoi.
            Par défaut les valeurs sont à 1 ce qui veut dire que les lumières
            défilent à la même vitesse que la map.
            Si on met 2 les lumières défileront deux fois plus vite que la map.
            Si on met 0 les lumières ne défileront plus, comme si elles étaient
            ancrées à l'écran.
            On peut aussi mettre des nombres décimaux genre 0.5 pour défiler moins
            vite ou encore des nombres négatifs pour inverser le sens de défilement.
            Par contre c'est uniquement pour les lumières affiliés à la map,
            si la lumière suit un chara cette option ne marche pas.
        x = ancrage horizontal.
            La valeur par défaut est 1.
        y = ancrage vertical.
            La valeur par défaut est 1.
        Exemple :
            light("lumière 1").set_parallax(0, 0) # lumière ancrée à l'écran

    - light(key).set_opacity(opacity, duration)
            Change l'opacité de la lumière, ce qui aura pour effet de faire
            qu'elle brille moins le jour et éclaire moins la nuit aussi.
            Si on veut juste faire qu'elle brille moins le jour tout en éclairant
            bien la nuit il vaut mieux baisser la composante alpha de la couleur.
        opacity = pourcentage entre 0 et 100.
            La valeur par défaut est 100.
        Exemple :
            light("lumière 1").set_opacity(75, 60)

    - light(key).set_color(red, green, blue, alpha, duration)
            Colorise/Applique une couleur sur la lumière.
            On peut avoir une couleur nulle (avec tout à 0), la lumière sera
            invisible le jour, et ne fera qu'empêcher l'écran de noircir la nuit
            (pas de couleur).
            Pour avoir une lumière noire ou qui assombri l'écran il faudra
            modifier le blend_type (voir plus bas).
        red, green, blue = nombres entre 0 et 255.
            Ce sont les composantes de la couleur, rouge, vert, bleu.
            La valeur par défaut est 0.
        alpha = nombre entre 0 et 255.
            C'est la transparence de la couleur mais ici ça correspond plutôt
            à la luminosité de notre lumière.
            La valeur par défaut est 255 = 100%.
        Exemple :
            light("lumière 1").set_color(255, 0, 0, 255) # => lumière rouge

    - light(key).set_zoom(zoom, duration)
            Change le zoom de la lumière.
        zoom = un pourcentage.
            La valeur par défaut est 100.
        Exemples :
            light("lumière 1").set_zoom(200) # => zoom à 200% instantané
            light("lumière 1").set_zoom(200, 60) # => zoom à 200% sur 60 frames

    - light(key).set_flicker(variance, refresh_rate, duration)
            Fait scintiller la lumière, comme du feu.
            L'effet est réalisé en changeant le zoom de manière aléatoire.
        variance = amplitude du scintillement en pourcentage de zoom.
            Ce doit être un nombre supérieur à 0.
            Il vaut mieux mettre des petits nombres.
            La valeur par défaut est 0 = désactivé.
        refresh_rate = intervalle entre chaque changement en nombre de frames.
            En règle générale plus la variance est haute plus l’intervalle doit
            être grand pour éviter d'avoir quelque chose d'épileptique.
            La valeur par défaut est 4.
        Exemple :
            light("lumière 1").set_flicker(2, 4)

    - light(key).set_angle(angle, duration)
            Fait tourner la lumière...
            Ça marche mais que pour les lumières de jour.
        angle = nombre de degrés.
            On peut aussi mettre un nombre négatif.
            A noter que si on fait une rotation de 360° puis qu'on veut en
            refaire une autre une deuxième fois ça ne fera rien, vu qu'on est
            déjà à 360° il faut soit tourner à 720° soit remettre la valeur à 0
            avant d'essayer de la remettre à 360.
        Exemple :
            light("lumière 1").set_angle(360, 60) # => do a barrel roll

    - light(key).set_wave(amp, length, speed, duration)
            Fait onduler la lumière.
            Ça marche mais que pour les lumières de jour.
        amp = amplitude (horizontale) de l'ondulation en nombre de pixels.
            Ce doit être un nombre supérieur à 0.
            La valeur par défaut est 0 = désactivé.
        length = longueur (verticale) de l'onde en nombre de pixels.
            La valeur par défaut est 180.
        speed = vitesse de l'ondulation.
            La valeur par défaut est 360.
        Exemple :
            light("lumière 1").set_wave(4, 180, 360, 60)

    - light(key).visible = true ou false
            Permet de masquer une lumière sans perdre ses réglages, ça peut
            toujours servir.
            Par défaut la valeur est true.
        Exemple :
            light("lumière 1").visible = false

    - light(key).blend_type = 0 ou 1 ou 2
            Change le mode fusion (type de transparence) de la lumière.
            Si 0 => Normal
            Si 1 => Addition (éclairci)
            Si 2 => Soustraction (obscurci)
            Par défaut la valeur est 1.
        Exemple :
            light("lumière 1").blend_type = 2

    - light(key).directions = n
            Il est possible d'avoir des lumières directionnelles.
            C'est à dire que quand on met une lumière sur un chara, la lumière
            prendra la même direction que le chara.
            Pour faire des lampes de poche par exemple.
            Le script peut supporter des charas à 2, 4 ou 8 directions.
        n = le nombre de directions.
            Le fichier doit être prévu à cet effet, ça marche comme une planche de
            chara, il faut qu'il y ait toutes les directions dans le même fichier
            les unes au dessus des autres dans le même ordre que pour le chara.
            La valeur par défaut est 1.
        Exemple :
            light("lumière 1").directions = 4

    - light(key).patterns = n
            Comme pour les directions les lumières peuvent avoir des animations
            qui se synchronisent avec l'animation de leur chara.
            Le principe est le même.
        n = le nombre d'animations.
            Ici les animations doivent être alignées horizontalement dans le
            fichier comme pour les planches de chara.
            La valeur par défaut est 1.
        Exemple :
            light("lumière 1").patterns = 4

    - light(key).anime_rate = n
            Cette option permet d'animer automatiquement la lumière (Animer à
            l'arrêt en quelque sorte).
        n = intervalle entre chaque animation en nombre de frames.
            Plus c'est haut plus l'animation est lente.
            La valeur par défaut est 0 = désactivé.
        Exemple :
            light("lumière 1").anime_rate = 10

  Ombres :

    - shadow(key).setup(filename)
            Initialise une nouvelle ombre.
        key = un identifiant pour notre ombre.
            Fonctionne exactement de la même manière que pour les lumières.
        filename = le nom du fichier utilisé pour l'ombre.
            Ici contrairement aux lumières on peut coloriser l'ombre directement
            dans son fichier si besoin (même si en général les ombres sont noires).
            Les images d'ombres ne doivent pas être transparentes mais pleines,
            la transparence des ombres est gérée automatiquement par le script
            selon la luminosité ambiante de la map.
        Exemple :
            shadow("ombre 1").setup("shad.png") # nouvelle ombre
            shadow.setup("shad.png") # nouvelle ombre sans identifiant

    - shadow(key).setup(width, height)
            Initialise une nouvelle ombre sans image.
            Si vous avez besoin d'une simple ombre rectangulaire c'est plus
            simple et efficace de faire comme ça plutôt que de créer et utiliser
            des images.
        width = la largeur de l'ombre en pixels.
        height = la hauteur de l'ombre en pixels.
        Exemple :
            shadow("ombre 1").setup(32, 96) # nouvelle ombre de taille 32x96px

    - shadow(key).chara_id = n
            Permet de lier une ombre à un chara (event, héros, véhicule).
            Le principe est le même que pour les lumières.
            Cependant attention, les ombres de charas ne peuvent pas assombrir
            d'autres charas, si vous voulez des ombres sous lesquelles ont peut
            passer il faut qu'elles soient liées à la map.
        n = id du character sous lequel afficher l'ombre.
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").chara_id = -1 # lie l'ombre au héros

    - shadow(key).clear
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").clear # supprime l'ombre

    - shadow(key).active
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").active == true # l'ombre existe ?

    - shadow(key).set_pos(x, y, duration)
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").set_pos(128, 256, 60) # set_pos avec transition de 60 frames

    - shadow(key).set_origin(x, y, duration)
            Change le point d'origine de l'image.
            Par défaut l'origine est toujours au centre comme pour les lumières.
            Quand on place une ombre sur un chara c'est souvent mieux comme ça
            mais en général quand on veut en placer une sur la map on fait ça
            par rapport à son coin haut gauche, donc n'oubliez pas de changer ça !
        x = coordonnée x du centre de l'image en pourcentage.
        y = coordonnée y du centre de l'image en pourcentage.
        Exemple :
            shadow("ombre 1").set_origin(0, 0) # Origine au coin haut-gauche

    - shadow(key).set_parallax(x, y, duration)
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").set_parallax(0, 0) # ombre ancrée à l'écran

    - shadow(key).set_opacity(opacity, duration)
            Change l'opacité de l'ombre, l'opacité est déjà gérée automatiquement
            par le script donc ça sert pas à grand chose, mais si pour une raison
            y'a besoin de baisser l'opacité d'une ombre en particulier c'est
            possible.
            Cette option marche uniquement si vous utilisez une image pour votre
            ombre, sinon il faut voir avec le canal alpha de la couleur.
        opacity = pourcentage entre 0 et 100.
            La valeur par défaut est 100.
        Exemple :
            shadow("ombre 1").set_opacity(75, 60)

    - shadow(key).set_color(red, green, blue, alpha, duration)
            Définit la couleur de l'ombre pour quand on utilise pas d'image.
        red, green, blue = nombres entre 0 et 255.
            Ce sont les composantes de la couleur, rouge, vert, bleu.
            La valeur par défaut est 0 = noir.
        alpha = nombre entre 0 et 255.
            C'est l'opacité de notre ombre.
            La valeur par défaut est 255 = 100%.
        Exemple :
            shadow("ombre 1").set_color(0, 255, 0, 255) # => ombre verte

    - shadow(key).set_zoom(zoom, duration)
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").set_zoom(200) # => zoom à 200% instantané

    - shadow(key).visible = true ou false
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").visible = false

    - shadow(key).directions = n
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").directions = 4

    - shadow(key).patterns = n
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").patterns = 4

    - shadow(key).anime_rate = n
            Fonctionne exactement de la même manière que pour les lumières.
        Exemple :
            shadow("ombre 1").anime_rate = 10

    - shadow(key).shadowable = true ou false
            Définit si une ombre doit ombrer les charas ou pas.
            Pour les ombres associées à des charas il est important de faire
            qu'elles ne puissent pas ombrer, autrement le chara associé se
            retrouvera dans l'ombre en permanence.
            La valeur par défaut est true.
        Exemple :
            shadow("ombre 1").shadowable = false

    - set_shadowable(value, chara_id)
            Définit si un chara peut être ombré ou pas.
        value = true ou false
            La valeur par défaut est true.
        chara_id = id du character sur lequel modifier cette option.
            Si on ne met rien ça sera l'event qui exécute le script,
            comme si on mettait @event_id.
        Exemple :
            set_shadowable(false, -1) # empêche le héros d'être ombré
            set_shadowable(false) # empêche l'event qui exécute d'être ombré
=end