ScriptedLight v1.1 Manual
Guide d'utilisation des lumières codées

Traduction de l'article de Lode Vandevenne qui ajoute une nouvelle classe d'effets lumineux aux multiples possibilités.

Matières

• Introduction
• Installation
• Ondes (Waves)
• Formules d'ondes
• Timing
• Utilisation
• Actions contrôlées par déclencheurs
• Evènements produits
• Clés
• KEY_Triggered
• KEY_Timed
• Remarques
• Liens
• Téléchargement du script, de la carte d'exemple et de ce texte en V.O.

Introduction

Les "ScriptedLight" permettent de modifier de façon dynamique les paramètres : LightBrightness,  LightHue, LightSaturation, LightRadius, VolumeBrightness, VolumeFog, VolumeRadius, DrawScale, LightType et LightEffect au cours du jeu. Ces changements son effectués par une fonction d'onde "Wave" (WAVE_Sinus, WAVE_DoubleSinus, WAVE_SawTooth, WAVE_Square, WAVE_SimpleSquare, WAVE_Random or WAVE_Constant) ou par des définitions d'états (jusqu'à 4 états pré-définis), tout ceci pouvant être commandé par des gâchettes ou une horloge.

On peut contrôler la vitesse, la transition, l'amplitude, la phase et bien d'autres paramètres des ondes (Waves). Avec les "ScriptedLight", on peut faire des lumières semblables au "TriggerLight", mais ici les halos peuvent être activés/désactivés également ! (ce qui n'est pas les cas pour les "TriggeredLights"). Un effet spécial est ajouté : "FX_TriggerFlickerOn", pour simuler un néon qui clignotte avant de s'allumer.

Installation

Mettre le fichier "ScriptedLight.u" dans le dossier "System" d'Unreal Tournament.

Ouvrir ensuite cette bibliothèque dans le catalogue de classes.  On peut maintenant sélectionner les "ScriptedLight" dans les "Light --> ScriptedLight", et les ajouter dans la carte qu'on prépare.

Pour distribuer cette carte, il faut incorporer le fichier "ScriptedLight.u", pour que les autres utilisateurs puissent la lire.

Ondes (Waves)

On peut sélectionner une onde dans les propriétés des " ScriptedLight --> Object --> InitialState".

Les ondes peuvent être considérées comme une propriété dérivée des "LightTypes" : certaines font la même chose que certains "LightType", mais permettent en plus de contrôler des paramètres comme la vitesse, etc.. de l'effet considéré.  Certaines ondes ont des propriétés spécifiques et nouvelles. Les ondes peuvent être appliquées à toutes les propriétés des lumières, tandis que les "LightTypes" conditionnent seulement la luminosité.  Voici une liste qui compare certains aspects des ondes par rapport aux "LightType".

• WAVE_Square : Ressemble à "LT_Strobe", mais avec "WAVE_Square" vous pouvez contrôler la vitesse de l'effet, et la luminosité lorsque l'effet est "off", on peut en outre le faire changer de couleur, et bien d'autres choses, ET on peut faire que le halo suive lui aussi l'effet stroboscopique, ce qui n'est pas le cas avec la fonction "LT_Strobe".
• WAVE_Sinus : ressemble à "LT_Pulse" et à "LT_SubtlePulse", mais là aussi on a bien plus de contrôle sur l'effet de pulsation, et on peut définir la teinte (hue), la saturation, le rayon, etc... de la pulsation lumineuse au lieu de la luminosité, ou les deux.
• WAVE_Random : ressemble à "LT_Blink" et "LT_Flicker", mais avec "WAVE_Random" on peut définir la probabilité pour la lumière d'être allumée ou éteinte, et bien d'autres choses.
• WAVE_Constant : ressemble à "LT_Steady", mais peut être utilisé comme une "TriggerLight" où le halo est contrôlé aussi bien !

Et voici une liste d'ondes qui ne peuvent être comparées aux "LightType" :

• WAVE_SawTooth (en dents de scie) : Ceci permet d'avoir une lumière qui croît progressivement, s'éteint ensuite soudainement, s'allume ensuite brusquement, etc... (ou encore faire que la saturation, le rayon, ... augmentent puis diminuent brusquement).  On peut aussi inverser l'effet avec des valeurs négatives.
• WAVE_DoubleSinus : c'est la somme de deux "WAVE_Sinus", et l'on peut définir chaque Sinus pour affecter des réglages différents de la lumière.
• WAVE_AdvancedSquare : ressemble à "WAVE_Square", mais on peut utiliser 8 délais différents "on" et "off".

Et on peut aussi combiner les ondes et les "LightTypes" :)

Wave Formulas

Chaque onde a sa propres formule et dans les propriétés des "ScriptedLight" on peut modifier certains paramètres.  ouvrir les Propriétés des "ScriptedLight" et aller dans "SLWave".

Là on peut modifier les variables A, B, C, D, E, F, G and H.  Toutes les ondes n'uilisent pas ces variables.  Voici une liste des formules des ondes.  Dans cette liste, t = Time (dans les sinuswaves, ça va de 0 à 2pi et ensuite de nouveau à 0, dans toutes les autres ondes et clés ça va de 0 à 1 et derechef à 0), A --> H sont les variables qu'on peut définir. Le résultat de cette formule est un nombre entre 0 et 1, qui est multiplié par 255.  Le résultat final devient LightBrightness, LightHue, LightRadius, ou tout état que la lumière pourra présenter à un moment donné.

WAVE_Sinus: 

Formule: 

• D + A * Sin(B*t + C)  

Usage :

• A modifie l'amplitude (luminosité, saturation, teinte, etc..).  Toute valeur entre 0 et 0.5 est correcte.
• B modofoe la vitesse de l'effet, la plupart du temps, une valeur de 1 donne de bons résultats.
• C modifie la phase, c'est à dire à quel moment l'effet va démarrer.
• D modifie la valeur de départ du paramètre choisi (luminosité, saturation, etc..) pour une lumière, 0.5 est une luminosité de 128, et durant l'onde la valeur de "A*Sin(Bt+C)" sera ajoutée puis soustraite à 128.

Précautions :

• Si on définit A plus grand que 0.5, la luminosité (ou d'autres paramètres, ce que vous avez maintenant compris :), va dépasser 255 ou devenir inférieure à 0, et par conséquent basculer à l'autre bout de l'espace de définition qui est de 0 à 255, entraînant un résultat désastreux.
• Ne pas définir D plus grand que 1, car 1 définit une luminosité de 255.  A 1, la luminosité est si forte qu'elle dépasse 255 quand l'onde est dans la partie de plus grande valeur du sinus.

WAVE_DoubleSinus: 

Formules :

• D + A * Sin(B*t + C) --> si cette formule est appliquée seule à un paramètre (1)  voir plus loin
• H + E * Sin(F*t + G) --> si cette formule est appliquée seule à un paramètre (2)
• (D + A * Sin(B*t + C)) + (H + E * Sin(F*t + G)) --> si les deux sont appliquées à un même paramètre.

Usage :

• Voir "WAVE_Sinus", avec A = E, B = F, C = G et D = H

Précautions :

• Si on veut appliquer les deux courbes au même paramètre, veiller à ce que la somme des deux sinus n'entraîne pas une valeur de la luminosité supérieure à 255 ou inférieure à 0.  Par exemple, si A de la première formule = 0.4, mettre E dans le seconde inférieur ou égal à 0.1 : 0.4 + 0.1 font 0.5, et toute valeur supérieure à 0.5 créerait un effet indésirable.

WAVE_Square

Formule:

•  If t < 0.5, la lumière est éteinte et si t > 0.5 la lumière est allumée.  

Usage :

• On peut définir les valeurs d'allumage ou d'extinction de la lumière avec "SquareOnValue" et "SquareOffvalue" : ce sont les valeurs pour lesquelles LightBrightness, LightHue, LightSaturation, etc...... seront "on" ou "off".

WAVE_AdvancedSquare

Formule :

• if t < A la lumière est allumée
• if t > A et t < B la lumière est éteinte
• if t > B et t < C la lumière est allumée
• if t > C et t < D la lumière est éteinte
• if t > D et t < E la lumière est allumée
• if t > E et t < F la lumière est éteinte
• if t > F la lumière est allumée

Usage :

• On peut définir les valeurs d'allumage ou d'extinction de la lumière avec "SquareOnValue" et "SquareOffvalue" : ce sont les valeurs pour lesquelles LightBrightness, LightHue, LightSaturation, etc...... seront "on" ou "off".
• Définir A - F avec des valeurs de 0 à 1, et définir A inférieur à B, B inférieur à C, etc...  
• Si C= D= E = F =1, ces valeurs sont ignorées.

WAVE_Sawtooth (Onde en dent de scie)

Formule :

• A*t + B

Usage :

• A définit la luminosité maximale ou toute autre propriété (= sommet de l'onde), les valeurs de 0 to 255 sont valides.
• B définit la phase.
• Utiliser une valeur négative de "ScriptedLightPeriod" pour inverser la forme d'onde.

WAVE_Random

Formule :

• Q est un nombre aléatoire entre 0 et 1 (change à chaque instant)
• si Q < A, la lumière est éteinte durant cet instant
• si Q >= A, la lumière est allumée durant cet instant

Usage :

• Utiliser A pour définir la probabilité pour que la lumière soit allumée ou éteinte : pour A entre 0 et 0.5, la lumière sera plus souvent allumée tandis qu'entre 0.5 et 1, elle sera plus souvent éteinte.  Pour la valeur de 0.5, la lumière aura des chances égales d'être allumée ou éteinte.  Les valeurs entre 0 et 1 sont donc valides.
• Vous pouvez définir les valeurs d'allumage ou d'extinction avec les paramètres "SquareOnValue" et "SquareOffvalue" : ce sont les valeurs pour lesquelle LightBrightness, LightHue, LightSaturation, etc...... seront activées ou désactivées.

WAVE_Constant

Pas de formule puisqu'il s'agit d'un effet constant :)

Utilisé comme une "TriggerLight" où l'effet de halo est contrôlé également.  Voir plus loin.

Timing

On peut aussi utiliser des périodes négatives.

Use

Dans les propriétés des "ScriptedLight", aller à "SLUse".

Ici on peut définir les valeurs qui seront utilisées par les formules d'ondes.  Pour une valeur =vrai (TRUE), la valeur utilisée sera calculée dynamiquement à partir de la formule d'onde et IGNORERA la valeur qu'on aura donnée dans les champs "Lighting" ou "LightColor".  Pour une valeur =faux (FALSE), c'est au contraire cette valeur définie dans "Lighting" ou "LightColor" qui sera prise en compte.

Si l'on veut utiliser "bUseRadius" ou "bUseVolumeRadius", il FAUT définir bNoDelete =FALSE dans les "advanced properties".  Dans tous les autres cas cette valeur doit être vraie =TRUE (sinon le résultat sera très moche ! ).

"bUseCorona" est utilisé seulement par "RandomWave", "SquareWave" et les "KEYS" (voir plus loin).

"bUseLightType" et "bUseLightEffect" sont utilisés seulement pas les "KEYS".

"DrawScaleStartPoint" est important si on définit "bUseDrawScale" = True.  Pour les "WAVES", il faut utiliser une valeur entre 0 et 1, et les "KEYS" une valeur entre 0 et 255.  Pour les "KEYS", la valeur de l'échelle d'affichage sera la valeur qu'on aura donnée divisée par 64.  La valeur "DrawScale" définie dans les paramètres de "Display" n'est JAMAIS utilisée.

LEs paramètres avec un "2" devant leur nom sont utilisés seulement dans la seconde partie de la "DoubleSinusWave".

"HueStartPoint" peut être utilisé comme un contrôle final du point de départ pour la teinte (hue), on aura rarement l'occasion de s'en servir.

Si on utilise un halo et le brouillard, définir bCorona=True / définir un "VolumeRadius" dans les paramètres "Lighting" , sinon l'éditeur ne calculera rien lors de la compilation.

"DrawScale" est utilisé pour changer la taille du halo de la lumière.

TriggerActions

Expand "SLTrigger".

On peut définir l'association des "ScriptedLight" à des gâchettes dont l'"Event" aura pour cible le "Tag" de la lumière. 

• TA_IgnoreTrigger: Aucune gâchette n'est prise en compte.
• TA_TriggerTurnsOn: le déclencheur va allumer la lumière, qui ne pourra plus être éteinte.  Il faut choisir "bInitiallyOff" ="True" .
• TA_TriggerTurnsOff: le déclencheur va entraîner l'extinction de la lumière, définitivement.  Il faut choisir "bInitiallyOff" ="False" .
• TA_TriggerToggle: chaque fois qu'on actionne la gâchette, la lumière basculera entre les états "On" et "Off".  Utiliser "bInitiallyOff" ="True" pour faire que la lumière soit éteinte au départ ou "= False", pour qu'elle soit au contraire allumée.
• TA_TriggerControlOn: la lumière n'est activée que tant qu'on se tient dans le rayon d'action de la gâchette, et elle est désactivée quand on est en dehors de ce rayon.  Il faut définir "bInitiallyOff"="True". si on le définit à 0 la lumière sera allumée au début et s'éteindra seulement quand on entrera dans le rayon du déclencheur et encore en sortant du rayon
• TA_TriggerControlOff: la lumière s'éteint lorsqu'on est dans le rayon d'action de la gâchette, et s'allume lorsqu'on est en dehors de ce rayon.  Il faut définir "bInitiallyOff" ="False" for this to work, si on le définit à 1 la lumière sera éteinte au début et s'allumera seulement quand on entrera dans le rayon du déclencheur et encore en sortant du rayon.

ATTENTION !! Si on utilise "TA_TriggerToggle", il FAUT définir "ReTriggerDelay" >= 0.5 dans les propriétés du "Trigger".  Sinon il peut arriver que lorsque le joueur actionne la gâchette, cette action soit détectée deux fois entraînant l'effet "on/off" quasi instantanément.  MAIS : si on utilise "TA_TriggerControlOn" ou "TA_TriggerControlOff", il FAUT définir "ReTriggerDelay" =0, pour que ça marche.

Si la lumière est activée, la fonction WAVE est utilisée.

Si la lumière est désactivée, la luminosité sera celle validée dans "TriggerOffValue", tandis que les autres effets seront toujours définis dans la fonction "WAVE".

"TriggerOnValue" ne joue pas un rôle important dans les fonctions d'onde, et est utilisée seulement pour "FX_TriggerFlickersOn" (voir plus loin).

Si vous définissez "bTriggerCoronaToo" ="True", le halo de la lumière sera activé:désactivé aussi bien.  Cette fonction n'est pas disponible dans les "TriggerLight" d'origine, donc les "ScriptedLight" vous ouvrent un nouveau monde :)  Ne pas utiliser ce paramètre si vos lumières n'ont pas de halo, car il pourrait en apparaître un de façon incongrue.

Events

Si on définit dans les "SLTrigger" "bUseEvent" ="True", la valeur qu'on met dans le champ "Events --> Event" sera rejeté si :

-la "ScriptedLight" a la propriété "TA_IgnoreTrigger"

-la "FX_TriggerFlickersOn" a fini de clignotter

On peut ainsi réaliser un néon cassé qui s'éteint après avoir fini de clignotter.

Keys

Il y a deux états initiaux avec le mot "KEY" dans leur nom : "KEY_Triggered" et "KEY_Timed".

Ils utilisent jusqu'à 4 "KEYS", et la lumière bascule entre ces états régulièrement ou chaque fois qu'on actionne une gâchette. Une "Key" est une combinaison de réglages (brightness, hue, LightEffect, corona, volumefog, etc...) qui est appliquée à la lumière lorsqu'elle est dans cet état.

Beaucoup de propriétés importantes pour les "Keys" sont dans la rubrique "SLKey" :

Dans tous les champs dont le nom commence par "Key" on peut définir les valeurs qui seront utilisées dans l'état correspondant, il faut seulement définir l'état dans "SLUse". Les autres valeurs ne sont pas utilisée dans les "Keys".

"KeyTime" seulement a une autre utilisation vue plus loin.

KEY_Trigger

Si on l'utilise, la "ScriptedLight" passe à l'état suivant chaque fois qu'on utilise une gâchette (ou via l'"event" d'un autre item).  La transition est immédiate.

TOUJOURS donner à la gâchette un délai de réactivation "ReTriggerDelay" >= 0.5 , sinon ça ne fonctionne pas.

Avec "NumKeys" on peut définir le nombre d'états à traverser e 2 à 4. Pour 3, les 3 premiers états seront utilisés et le 4ème ignoré.

Utiliser "StartKey" pour définir l'état de départ.  0 pour le premier, 1 pour le second, 2 pour le troisième et 4 pour le quatrième. Par exemple, le permier état , key0, utilise "KeyBrightness[0]", "KeyHue[0]", etc...

Maintenant, il y a un cinquième état caché !  Cet état utilise les paramètres standard définis dans "Lighting" et "LightColor".  On y arrive en définissant "StartKey" >=5 et ce cinquième état est utilisé AVANT qu'on actionne la gâchette. Après quoi cet état ne sera plus utilisé. On peut utiliser ceci pour que la lumière soit initialement éteinte par exemple.

Bien sûr, les actions définies par des gâchettes ne fonctionnent pas pour "KEY_Trigger", car la gâchette est utilisée pour le changement d'état.

KEY_Timed

Cette clé utilise les mêmes valeurs "ScriptedLightPeriod" que la fonction d'onde, donc ces réglages sont importants pour les paramètres "KEY_Timed" également.

On a aussi besoin des paramètres 4 "KeyTime" et des 4 "TransTime".

On peut considérer une table qui définit quel état est actif à un moment donné.  Garder à l'esprit que "t" va de 0 à 1 puis retourne à 0, avec une vitesse et un sens qui dépendent de la valeur de " ScriptedLightPeriod".

• Si t > KeyTime[0] et t <= TransTime[0], la lumière a la valeur de Key[0]
• SI t > TransTime[0] et t <= KeyTime[1], la lumière change graduellement de Key[0] à Key[1]
• SI t > KeyTime[1] et t <= TransTime[1], la lumière a la valeur de Key[1]
• SI t > TransTime[1] et t <= KeyTime[2], la lumière change graduellement de Key[1] à Key[2]
• Si t > KeyTime[2] et t <= TransTime[2], la lumière a la valeur de Key[2]
• Si t > TransTime[2] et t <= KeyTime[3], la lumière change graduellement de Key[2] à Key[3]
• Si t > KeyTime[3] et t <= TransTime[3], la lumière a la valeur de Key[3]
• Si t > TransTime[3] et t <= 1-KeyTime[0], la lumière change graduellement de Key[3] à Key[0]

Dit autrement : 

• Toujours définir KeyTime[q] <= KeyTime[q+1] 
• Même chose pour TransTimes
• Si l'on veut une transition brutale, définir toujours KeyTime[q] et TransTime[q+1] avec la même valeur.
• Si l'on veut qu'il y ait TOUJOURS une transition graduelle, mais rien de constant, définir KeyTime[q] et TransTime[q] avec la même valeur.
• Pour des transitions graduelles et constantes, utiliser différentes valeurs pour KeyTimes et TransTimes.
• Si l'on veut utiliser seulement 3 états, définir KeyTime[3] et TransTime[3] = 1
• Si l'on veut utiliser seulement 2 états, définir KeyTime[2], TransTime[2], KeyTime[3] and TransTime[3] = 1.
• Toujours définir KeyTime[0] = 0
• Les valeurs de KeyTime et TransTime doivent être entre 0 et 1, elles représentent une valeur du timer "t" qui va de 0 à 1 en boucle indéfinie.

Une transition graduelle signifie par exemple que la lumière va passer progressivement du rouge (la teinte dans un état) au jaune (la teinte dans l'état suivant), en passant par toutes les valeurs de l'orange entre les deux.  Ou encore la luminosité ira progressivement de 0 à 64.

Ne pas utiliser "bSwapDirection", qui devait changer le sens de la variation et qui n'est pas encore au point.

Pour KEY_Timed, on peut utiliser les mêmes modes de déclenchement que pour les ondes.  Alors les états ne seront utilisés que si la lumière est active.

FX_TriggerFlickersOn

C'est un état initial ajouté aux lumières. C'est une lumière comme les autres, mais lorsqu'elle est activée, elle clignotte un moment avant de s'allumer complètement, tout comme un néon.

Durant le clignottement, une fonction de type "WAVE_Random" est utilisée, donc on peut utiliser la valeur A pour déterminer la probabilité d'être allumée ou éteinte.

On peut déterminer la longueur de la phase de clignottement "FlickerTime" dans "SLWave", et il faut utiliser "ScriptedLightPeriod" pour la fréquence du clignottement.

"FX_TriggerFlickersOn" fonctionne avec toutes les types de gâchettes, sauf "TA_TriggerControlOn", "TA_TriggerControlOff" et "TA_TriggerRandom".

REMARQUES

Sur les ordinateurs relativement anciens et lents, des plantages sont possibles, à cause du grand nombre de variables en cause probablement, et il vaut mieux sauvegarder régulièrement au cours de la construction de la carte. 

Ne pas abuser de ces effets qui sinon distraient le joueur.

Il faut les utiliser de façon plus subtile, par exemple lorsqu'une torche s'allume (LE_FireWaver) , pour les halos qui doivent apparaître lorsqu'une lumière s'allume, pour activer un écran d'ordinateur dont l'éclat et les teintes doivent varier lorsqu'on l'allume, ou pour faire des lumières stroboscopiques lentes.

Les ScriptedLight maintenant sont calculées sur les PC clients et pas par le serveur, et donc n'entraînent pas de "lag". 

Bien que le langage de programmation d'Unreal soit répuité pour sa relative lenteur, il n'y a pas de baisse de performance notable qui résulte de l'utilisation des "ScriptedLights". (testé sur un PII 350Mhz)

Il y a une carte d'exemple, "SLDemo.unr", avec 9 salles présentant chacune un type particulier de SL.  Certaines ont une gâchette qu'il faut actionner par contact.

L'inconvénient des "ScriptedLight" est qu'on ne peut les voir dans l'éditeur ! Aussi faut-il les tester dans le jeu pour vérifier que l'effet produit est bien celui qu'on souhaitait obtenir..

Contact

Contacter lode@altern.org pour toute question ou suggestion.

Copyright © 2001, Lode Vandevenne.

Ne pas distribuer de scripts basé sur celui-ci sans la permission de l'auteur.

L'auteur de ce script n'est pas responsable des dommages éventuels causés par l'utilisation de ce script.

NDT

Si le texte peut paraître parfois un peu ardu, la carte d'exemples est très explicite. Pour ceux qui sont pressés de faire la lumière, voici une petite fiche sur ce qu'il faut faire pour avoir une lampe qui s'allume et s'éteigne avec son halo, ry un néon qui clignotte au moment où il s'allume :