Ce qu'un script peut atteindre

Tout ce qui suit est disponible dans les hooks, sans rien importer. Rien d’autre ne l’est : voir La barrière.

log

La seule façon pour un script d’écrire quelque part. Les lignes arrivent dans la console du navigateur, préfixées par la cue qui les a produites ([script] 12 Musique d'intro).

function onStart() {
    log.info('démarrage');
    log.warning('la salle est bruyante');
    log.error("ça n'aurait pas dû arriver");
}

Chacune accepte autant d’arguments que vous voulez, comme console.log.

startTime et time

Deux variables ordinaires que le moteur rafraîchit avant chaque hook et chaque callback de timer :

function onTick() {
    if (time > 5) log.info('cinq secondes');
}

Leur affecter une valeur ne sert à rien : l’appel suivant l’écrase. Un script qui déclare son propre time ou startTime ne compile pas (« Identifier ‘time’ has already been declared »), ce qui est la façon la plus claire d’apprendre que le nom est pris.

after(durée, callback)

Exécuter quelque chose une fois, dans durée secondes.

function onStart() {
    after(2, function () {
        this.level.set(0.2);
    });
}

every(intervalle, callback)

Exécuter quelque chose en boucle. Le premier argument est soit l’intervalle en secondes, soit un objet : interval est l’écart, delay le temps d’attente avant la première exécution (par défaut, un intervalle complet). Le callback reçoit son numéro de tour, à partir de 0.

function onStart() {
    // Forme courte : toutes les deux secondes.
    every(2, function (index) {
        log.info('tour', index);
    });
}

function onStart() {
    // Tout de suite, puis toutes les demi-secondes.
    every({ interval: 0.5, delay: 0 }, function (index) {
        this.textColor.set(index % 2 === 0 ? '#ff0000' : '#ffffff');
    });
}

Les deux timers tournent sur les frames du moteur, pas sur setTimeout :

• Ils appartiennent à la cue. Ils ne peuvent pas se déclencher avant qu’elle ne joue, et ils disparaissent dès qu’elle se termine — rien ne continue après.
• Une frame en retard fait rattraper une répétition au lieu de la laisser dériver, et les index restent consécutifs.
• Un callback qui lève une erreur est signalé une fois puis abandonné ; les hooks continuent.
• Un timer posé depuis un callback attend la frame suivante.
• Un intervalle qui n’est pas un nombre positif, ou un callback qui n’est pas une fonction, ne programme rien du tout.

random

Des nombres, des points et des couleurs tirés au hasard. Les bornes sont converties et remises dans l’ordre : random.int(10, 1) vaut random.int(1, 10), et une borne qui n’est pas un nombre retombe sur la valeur par défaut plutôt que de mettre NaN sur scène.

random.color prend une teinte, une saturation et une valeur. Chacune est soit un nombre fixe, soit un intervalle [min, max] dans lequel tirer. La teinte est en degrés (0–360) et s’enroule, donc [300, 420] balaie le rouge ; la saturation et la valeur sont entre 0 et 1 et sont bornées. Omises, la teinte est libre et les deux autres valent 1.

random.color(); // n'importe quelle couleur vive
random.color({ saturation: [0.5, 1], value: 1 }); // vif, jamais délavé
random.color({ hue: [200, 260], value: [0.4, 1] }); // des bleus
random.color({ saturation: 0, value: [0, 1] }); // un gris

random.element tire un élément d’un tableau, et renvoie undefined pour un tableau vide plutôt que de lever une erreur — une liste vide ne doit pas arrêter un spectacle.

const SALUTS = ['BONJOUR', 'HELLO', 'HOLA'];

function onStart() {
    every(0.5, function () {
        this.text.set(random.element(SALUTS));
        this.textColor.set(random.color({ saturation: [0.6, 1] }));
        this.offsetX.set(random.float(-0.1, 0.1));
    });
}

this

Les propriétés de la cue elle-même, chacune un objet avec get() et — quand la propriété est modifiable — set() :

function onStart() {
    log.info('niveau', this.level.get());
    this.level.set(0.5);

    // Une propriété sans setter est en lecture seule : testez avant.
    if (this.brightness && this.brightness.set) {
        this.brightness.set(1.4);
    }
}

Les propriétés disponibles dépendent du type de cue — voir properties.md. this fonctionne dans onStart, onTick, onEnd et dans les callbacks de timer, tant que le callback est une function et non une flèche (() => {} n’a pas de this propre).

Ce qu’un script écrit est vivant uniquement : cela change ce qui joue, jamais le spectacle enregistré. Modifier le même champ dans l’inspecteur pendant que la cue joue écrase ce que le script avait posé.

L’éditeur

• Ctrl/Cmd+S compile.
• Ctrl+Espace — ou simplement la frappe — propose les hooks, l’API, this.<nom> pour la cue sélectionnée, et les variables déclarées par le script. Entrée ou Tab accepte, Échap ferme.
• Tab indente quand aucune proposition n’est ouverte ; Ctrl/Cmd+Z annule.