Présentation du Squelette

Cette section décrit la structure fondamentale d’une intégration LightScript, couvrant les exigences techniques clés, des exemples concrets, les conventions de nommage et les conseils d’efficacité. Elle parcourt la boucle de mise à jour, le comportement des compteurs, la logique de déclenchement des effets, et met en évidence les pièges courants. Que vous déboguiez, construisiez de zéro ou mainteniez le code de quelqu’un d’autre, ce guide met l’accent sur la clarté, la stabilité et les performances comme normes fondamentales des intégrations de haute qualité.

Structure de Base

Cette section donne un aperçu rapide de la mise en place d’un LightScript du point de vue de la maintenance, en se concentrant sur les endroits où les problèmes surviennent généralement et comment repérer et corriger les bugs. Nous commencerons par une brève présentation d’une structure LightScript idéale pour vous familiariser avec le code, puis nous couvrirons le dépannage, et terminerons par une FAQ.

Le squelette de base nécessite un <head>, un <body> et un <script>. Toutes les déclarations de compteurs et de contrôles utilisateur vont à l’intérieur du <head>. Toutes les déclarations de canvas appartiennent au <body>. Tout le reste doit être placé dans la section <script>.

<head>

Le <head> est l’une des parties les plus critiques et complexes de tout LightScript. Un contrôle utilisateur ou un compteur défectueux ici peut provoquer des boucles de plantage ou se désactiver lui-même ainsi que tous les compteurs déclarés après lui.

Lors de la création de compteurs, vous devez vous assurer de :

Une syntaxe parfaite (pour éviter les plantages et les compteurs cassés)
Aucun nom de compteur dupliqué (les doublons sont écrasés)
Aucun compteur dépassant les limites de l’écran (provoque des plantages et des erreurs)
Aucune option manquante ou supplémentaire dans les compteurs (entraîne des plantages)
Tous les compteurs incluent des ajustements de résolution (assure un comportement cohérent)

En ce qui concerne les résolutions, les rapports d’aspect les plus courants sont :

16:9 (3840x2160, 2560x1440, 1920x1080, 1600x900, 1366x768, 1360x768, 1280x720)
16:10 (2560x1600, 1920x1200, 1680x1050, 1440x900, 1280x800)
21:9 (5120x2160, 3440x1440)

Par défaut, nous utilisons la résolution 2560x1440.

Tous les LightScripts doivent prendre en charge les rapports d’aspect 16:9, 16:10 et 21:9. Bien que le 4:3 ne représente pas une part significative de notre base d’utilisateurs, il devrait quand même être pris en compte pour la compatibilité future.

Voici un exemple de la structure pour un compteur avec plusieurs paramètres de résolution :

L’emplacement et la taille par défaut de vos compteurs s’appliquent à toutes les autres résolutions du même rapport d’aspect. Par exemple, si vous ajustez initialement vos compteurs pour fonctionner avec 1600x900, ce compteur devrait fonctionner correctement dans toutes les autres résolutions 16:9. Cependant, il y a des exceptions. Fortnite a plusieurs positions de compteurs différentes même dans le même rapport d’aspect, et certains rapports d’aspect eux-mêmes peuvent être trompeurs. Par exemple, 1366x768, une résolution courante dans le monde, est souvent répertoriée comme 16:9 mais n’est pas réellement un vrai ratio 16:9, ce qui n’est pas inhabituel. De même, les ratios ultra-larges comme 21:9 correspondent rarement à leurs dimensions nominales. Dans mon expérience en tant que développeur d’intégration, je n’ai jamais rencontré de résolution 21:9 exacte malgré leur étiquetage comme tel. Pour cette raison, chaque résolution ultra-large doit être créée, testée et configurée individuellement.

Tous les ajustements doivent être placés entre les balises d’ouverture <meta> et de fermeture </meta> ; sinon, ils ne fonctionneront pas. Si votre compteur par défaut est basé sur 16:9 et se comporte de façon cohérente dans ces résolutions, vous n’avez pas besoin d’ajouter des ajustements pour d’autres résolutions 16:9. Cependant, vous devez ajouter des entrées pour chaque résolution dans d’autres rapports d’aspect (tels que 16:10 et 21:9), même si le ratio est cohérent.

Enfin, chaque compteur sauf nos compteurs OCR nécessite une plage HSL pour se déclencher. Ces plages peuvent être compliquées par des facteurs tels que :

Éléments d’interface transparents
Dégradés dans les zones de couleur
Effets de déformation de l’écran
Ouvertures de menus en jeu
Ajustements de l’interface par résolution
Utilisation de manette vs clavier
Enregistrement vidéo, qui peut introduire des erreurs de pixels liées à la compression

Les instructions de base sur HSL et les coordonnées normalisées sont couvertes dans nos docs développeur et ne seront pas répétées ici. Les tests de ces compteurs seront abordés dans la section “Identifier les Problèmes”, mais il est important de souligner ceci : la quantité de tests nécessaires pour vérifier tous les compteurs parfaitement est calculée comme (nombre de compteurs) × (nombre d’ajustements de résolution) × (nombre de modes de jeu) × (nombre de personnages jouables) × (durée d’une partie moyenne). Cela peut facilement s’additionner à des heures de vérification par jeu, surtout si des modes d’entraînement ou d’autres solutions ne sont pas disponibles.

GARDEZ VOS COMPTEURS EFFICACES, notre standard est la perfection.

<body>

La balise <body> est l’endroit où l’élément canvas réel est déclaré. Il devrait toujours ressembler plus ou moins à l’exemple suivant. L’id réel du canvas peut être modifié si vous le souhaitez, mais assurez-vous de le récupérer correctement dans le script.

Gagnez du temps et copiez-collez ceci.

<script>

Quatre choses doivent se passer à l’intérieur de cette balise dans chaque intégration :

Le canvas est récupéré et utilisé pour créer notre contexte 2D.
La boucle de mise à jour initiale définit les valeurs des compteurs, puis se rappelle indéfiniment pour les maintenir.
La boucle de mise à jour garde les variables de contrôle utilisateur à jour.
Les compteurs exécutent leurs fonctions de callback lorsqu’ils sont stables.

Procédure Générale

Nous avons déjà mis en place le squelette de code de base. L’étape suivante consiste à parcourir la boucle d’exécution qui déclenche les effets du début à la fin.

L’interface utilisateur du jeu vidéo affiche des informations sous forme de barres colorées, boutons, zones de texte, etc. SignalRGB capture ces données plusieurs fois par seconde, mais le taux de capture réel dépend fortement de l’efficacité de votre code. Pour être clair, une seule boucle ou variable non déclarée peut briser tout votre script, et même faire planter SignalRGB. Pire encore, il est facile d’écrire du code qui fonctionne techniquement, mais qui est si inefficace qu’il ne capture les informations qu’à 1-2 FPS.
Chaque compteur déclaré dans le <head> doit être aussi petit et efficace que possible pour réduire la surcharge. Effectuez vos calculs tôt et souvent ; un compteur qui occupe 25% de l’écran n’est jamais efficace. Avec les compteurs OCR, capturez des lettres individuelles plutôt que des mots entiers. Pour les barres de vie et de mana, ne surveillez que les segments essentiels. GARDEZ VOS COMPTEURS AUSSI PETITS QUE POSSIBLE.
Les compteurs capturent des informations qui se rafraîchissent à chaque boucle.
Plus tôt, nous avons couvert la définition de la classe Meter, qui stocke les données du compteur et déclenche un callback lorsque le tableau d’informations devient stable. En haut de votre script, déclarez tous les Meters en un seul bloc. Vous pouvez les organiser ou les alphabétiser ; ne les enfouissez simplement pas sur des milliers de lignes. Vous devrez éventuellement ajuster les valeurs de stabilité, et c’est une perte de temps d’essayer de se rappeler où vous les avez placés.
À l’intérieur de la fonction update, ces compteurs recevront des valeurs de la logique de lecture d’écran à chaque boucle. Leur logique interne évalue la stabilité et, lorsqu’elle est stable, déclenche leur fonction de callback associée.
Ces fonctions de callback doivent être déclarées dans votre script mais en dehors de la fonction update. À l’intérieur, vérifiez l’état de vos valeurs Meter (value, decreased, increased, diff) et utilisez-les pour déterminer si l’on doit jouer une animation d’effet. Structurer votre code de cette façon, plutôt que de tout mettre directement dans la boucle update, nous permet de construire des intégrations évolutives.

Exemple Concret

Maintenant que vous avez l’idée générale, je vais parcourir rapidement un exemple de boucle concrète.

Je joue au jeu League of Legends, qui entoure les compétences disponibles d’une mise en évidence jaune vif.
À chaque boucle, le compteur de compétence spécifique capte cette couleur comme une valeur de “1” car elle passe complètement la plage HSL du compteur.
Ce “1” est transmis à l’instance Meter attachée au compteur de lecture d’écran et inséré dans le tableau d’informations de ce Meter.
Si chaque valeur dans ce tableau est un “1”, il est considéré stable, et activera la fonction de callback d’effet attachée. Cette fonction de callback serait également activée si chaque valeur était un “0”, ou “.1” par exemple ; tout ce que le Meter vérifie est la stabilité. Une note importante ici est que la fonction de callback ne sera pas continuellement activée si le Meter est constamment stable à la même valeur - seule la stabilité avec une NOUVELLE valeur activera le callback.
Une fois la fonction de callback exécutée, nous arrivons à quelques vérifications conditionnelles - dans ce cas, tout ce que nous avons à faire est de vérifier si la Meter.value est “0”, indiquant qu’une compétence a été utilisée.
Puisque la valeur du Meter est “1”, nous échouons cette vérification et ne jouerons pas l’effet de compétence.
Plusieurs secondes plus tard, j’active la compétence et la mise en évidence jaune autour du bouton disparaît.
La nouvelle valeur du compteur est 0, qui est transmise à sa classe Meter.
Une fois la stabilité atteinte, le callback s’active et notre conditionnel est passé, jouant l’effet de compétence. La latence dépend entièrement de la longueur du tableau Meter, que vous définissez à sa déclaration. Plus la longueur est grande, plus la latence est grande et moins les faux déclenchements se produisent, alors assurez-vous de tester jusqu’à trouver un bon équilibre.

Conventions de Nommage

Les compteurs de lecture d’écran doivent avoir des noms simples, clairs et descriptifs, commençant toujours par une lettre minuscule. Nommer un compteur de barre de vie “healthBar” est excellent. Nommer deux compteurs “healthBarRed” et “healthBarGreen” quand ils suivent des couleurs différentes dans la même zone est également bien. Mais nommer un petit compteur qui n’apparaît que pendant l’effet ultime d’un héros quelque chose comme “hrO21_yes” n’apportera que douleur et souffrance à quiconque essaie de corriger votre code. Comprendre ce qu’un compteur mal nommé et minuscule suit peut littéralement prendre une heure de regard sur des pixels individuels si vous n’avez pas de chance, alors ne faites pas ça.

Les instances de classe Meter doivent être en majuscules et se terminer par le mot Meter. Des exemples comme “Q_Meter”, “TookDamageMeter” et “TowerDestroyedMeter” sont tous parfaitement acceptables. Ceux-ci doivent être clairement distinguables des compteurs déclarés dans la section <head>.

Les fonctions d’effets doivent également être nommées aussi simplement et descripttivement que possible. Certains jeux ont des centaines de ces fonctions ; d’autres pourraient en avoir moins de dix. Si plusieurs héros ont des compétences uniques, incluez le nom du héros comme préfixe, comme “SonaQ”, “ChamberE” ou “AshUlt”. Dans League of Legends, par exemple, il y a des fonctions comme “DragonEffect”, “TowerEffect” et “Q_Effects”, qui contiennent plusieurs conditionnels et sont utilisées par plusieurs compteurs. Ce type de nommage aide donc également à optimiser pour l’échelle.

Ne faites pas de fautes d’orthographe. Si vous n’êtes pas sûr de comment écrire quelque chose, cherchez-le. Les noms doivent être clairs et lisibles, quel que soit celui qui travaille sur le code ou le temps écoulé. Organiser les noms alphabétiquement aide à la recherche rapide, surtout si vous allez souvent modifier cette section. Bien que ce niveau d’organisation ne soit pas nécessaire pour que le code s’exécute, cela fait une grande différence pour nos développeurs de maintenance.