Scripter des fonctions

Ceci est une référence avancée. La plupart des histoires Loreline n'ont pas besoin de fonctions personnalisées. Le Guide d'écriture couvre tout ce qu'il faut pour écrire de la fiction interactive. Cette page est là pour aller plus loin avec des valeurs calculées, de la logique complexe ou des utilitaires personnalisés.

Cette page est une référence pour la syntaxe de script utilisée dans les fonctions Loreline. Si vous débutez avec Loreline, commencez par le Guide d’écriture pour apprendre les beats, les choix et la gestion d’état.

Les fonctions en Loreline sont définies avec le mot-clé function, suivi d’un nom, de paramètres entre parenthèses et d’un corps indenté :

function saluer(nom, heure)
  if heure < 12
    return "Bonjour, $nom !"
  else
    return "Bon après-midi, $nom !"

Le corps utilise une syntaxe de script standard détaillée ci-dessous.

Valeurs et types

Loreline prend en charge les types de valeurs suivants :

// Nombres (entiers et décimaux)
var compteur = 42
var prix = 3.99
var decalage = -5

// Chaînes de caractères (guillemets doubles)
var salutation = "Bonjour"
var nom = "Alice"

// Booléens
var actif = true
var cache = false

// Null (représente « aucune valeur »)
var resultat = null

// Tableaux (listes ordonnées)
var elements = [1, 2, 3]
var vide = []

// Objets (paires clé-valeur)
var stats = { pv: 100, pm: 50 }
var blanc = {}

Conversion de type

Les valeurs sont automatiquement converties en contexte booléen :

• 0, "" (chaîne vide), [] (tableau vide), null et false sont falsy (faux)
• Tout le reste est truthy (vrai)

Lorsque vous utilisez + avec une chaîne de caractères, l'autre valeur est convertie en chaîne de caractères automatiquement :

var message = "Score : " + 42    // "Score : 42"

Utilisez les fonctions de conversion intégrées pour une conversion explicite :

• float(value) : convertir en nombre
• string(value) : convertir en chaîne de caractères
• bool(value) : convertir en booléen

Variables

Utilisez var pour déclarer des variables locales à l’intérieur d’une fonction :

function calculerTotal(prix, quantite)
  var sousTotal = prix * quantite
  var taxe = sousTotal * 0.1
  return sousTotal + taxe

Les variables déclarées avec var sont locales à la fonction. Si vous omettez var, vous lisez ou écrivez une variable d’état à la place :

state
  score: 0

function ajouterPoints(points)
  var bonus = points * 2  // variable locale
  score += bonus          // modifie la variable d'état

Un var sans valeur initiale vaut null par défaut :

var resultat    // resultat vaut null

Les variables locales masquent les variables d’état du même nom :

state
  x: 10

function exemple()
  var x = 99    // x local, n'affecte pas l'état
  return x      // renvoie 99

Opérateurs

Arithmétique

var a = 10 + 3    // 13, addition
var b = 10 - 3    // 7, soustraction
var c = 10 * 3    // 30, multiplication
var d = 10 / 3    // 3.333..., division
var e = 10 % 3    // 1, reste (modulo)

Comparaison

x == y    // égal
x != y    // différent
x < y     // inférieur à
x > y     // supérieur à
x <= y    // inférieur ou égal
x >= y    // supérieur ou égal

Logique

a && b     // vrai si les deux sont vrais
a || b     // vrai si l'un ou l'autre est vrai
!a         // vrai si a est faux

Vous pouvez aussi écrire and et or au lieu de && et || :

if ensoleille and chaud
  return "Temps parfait !"

if pluie or neige
  return "Restez à l'intérieur."

Affectation

x = 10      // affectation
x += 5      // ajouter et affecter (x vaut maintenant 15)
x -= 3      // soustraire et affecter
x *= 2      // multiplier et affecter
x /= 4      // diviser et affecter

Incrémentation et décrémentation

x++    // ajouter 1 à x (postfixe)
++x    // ajouter 1 à x (préfixe)
x--    // soustraire 1 de x
--x    // soustraire 1 de x

Concaténation de chaînes

L’opérateur + joint les chaînes. Les valeurs non-chaînes sont converties automatiquement :

var libelle = "Objet #" + 3        // "Objet #3"
var info = nom + " (" + age + ")"

Interpolation de chaînes

Dans les chaînes, $ insère la valeur d’une variable et ${} évalue une expression :

function formaterRecu(article, prix, qte)
  var total = prix * qte
  return "$qte x $article = $$${total}"

L’accès aux champs et les appels de fonctions fonctionnent directement après $ :

var ligne = "$perso.nom possède $array_length(inventaire) objets"

Pour toute expression plus complexe, utilisez ${} :

var resume = "Total : ${prix * quantite + taxe}"
var note = "Suivant : ${elements[indexCourant + 1]}"

Structures de contrôle

if / else

function decrire(temperature)
  if temperature > 30
    return "chaud"
  else if temperature > 20
    return "tiède"
  else if temperature > 10
    return "frais"
  else
    return "froid"

Les parenthèses autour de la condition sont facultatives :

if (x > 0 && y > 0)
  // les deux sont positifs

Boucles for

Les boucles par intervalle itèrent d’une valeur de départ jusqu’à (mais sans inclure) une valeur de fin :

function somme(n)
  var total = 0
  for i in 0...n
    total += i
  return total

0...5 produit les valeurs 0, 1, 2, 3, 4. Les variables fonctionnent aussi : debut...fin.

Les boucles sur tableau itèrent sur chaque élément :

function trouverElement(inventaire, cible)
  for element in inventaire
    if element == cible
      return true
  return false

Boucles while

function compteARebours(n)
  var resultat = ""
  while n > 0
    resultat += "$n... "
    n -= 1
  return resultat + "C'est parti !"

Boucles do-while

Le corps s’exécute au moins une fois, puis se répète tant que la condition est vérifiée :

function lancerJusquaSix()
  var tentatives = 0
  do
    var lancer = random(1, 6)
    tentatives += 1
  while lancer != 6
  return tentatives

break et continue

break sort immédiatement d’une boucle. continue passe à l’itération suivante :

function premierNegatif(nombres)
  for n in nombres
    if n >= 0
      continue
    return n
  return null

function sommeJusquaLimite(valeurs, limite)
  var total = 0
  for v in valeurs
    if total + v > limite
      break
    total += v
  return total

return

Sort de la fonction et renvoie éventuellement une valeur. Sans return explicite, la fonction renvoie null :

function estPair(n)
  return n % 2 == 0

function fairePas()
  if !pret
    return    // renvoie null, sort prématurément
  // ... reste de la fonction

switch / case

Comparer une valeur à plusieurs cas :

function prixBoisson(boisson)
  switch boisson
    case "espresso"
      return 3
    case "latte"
      return 5
    case "cappuccino"
      return 4
    default
      return 0

Manipuler les tableaux

Créer et accéder

var elements = ["épée", "bouclier", "potion"]
var premier = elements[0]        // "épée"
elements[2] = "élixir"           // remplace "potion" par "élixir"
var compteur = array_length(elements)  // 3

Appels en style méthode

Les fonctions de tableau peuvent être appelées avec la notation pointée. Ces écritures sont équivalentes :

array_add(elements, "arc")    // style fonction
elements.add("arc")           // style méthode

Opérations courantes :

elements.add("flèche")              // ajouter à la fin
elements.prepend("casque")          // insérer au début
var dernier = elements.pop()        // retirer et renvoyer le dernier
var premier = elements.shift()      // retirer et renvoyer le premier
elements.remove("bouclier")         // retirer la première occurrence
var trouve = elements.has("épée")   // true si présent
var pos = elements.index("épée")    // position, ou -1

Tri et jointure :

var trie = [3, 1, 2].sort()            // [1, 2, 3]
var texte = ["a", "b", "c"].join(", ")  // "a, b, c"
elements.reverse()                       // inverser sur place

Les appels peuvent être chaînés :

var resultat = [3, 1, 2].sort().join(", ")   // "1, 2, 3"

Consultez Fonctions intégrées : Array pour la liste complète.

Manipuler les objets

Créer et accéder

var perso = { nom: "Alex", pv: 100, niveau: 1 }
var nom = perso.nom          // notation pointée
var pv = perso["pv"]        // notation entre crochets
perso.niveau = 2             // modifier une propriété

La notation entre crochets est utile lorsque la clé est dynamique :

var cle = "pv"
var valeur = perso[cle]    // identique à perso.pv

Appels en style méthode

var cles = perso.keys()          // ["nom", "pv", "niveau"]
var existe = perso.has("pm")     // false
perso.set("pm", 50)             // ajouter une nouvelle clé
perso.remove("pm")              // supprimer une clé

Consultez Fonctions intégrées : Map pour la liste complète.

Récapitulatif

Voici un exemple complet qui combine plusieurs fonctionnalités : une fonction qui formate une liste d’inventaire avec les quantités et une valeur totale :

state
  inventaire: ["épée", "bouclier", "potion", "potion", "flèche", "flèche", "flèche"]
  prix: { "épée": 50, "bouclier": 35, potion: 10, "flèche": 2 }

function resumeInventaire()
  // Compter les occurrences de chaque objet
  var compteurs = {}
  for objet in inventaire
    if compteurs.has(objet)
      compteurs.set(objet, compteurs.get(objet) + 1)
    else
      compteurs.set(objet, 1)

  // Construire le résumé
  var lignes = []
  var total = 0
  for nom in compteurs.keys()
    var qte = compteurs.get(nom)
    var valeur = prix.get(nom) * qte
    total += valeur
    lignes.add("$qte x $nom ($$${valeur})")

  return lignes.join("\n") + "\nTotal : $$$total"

barista: Tu veux voir ce que tu transportes ?
$resumeInventaire()

Cela produit :

1 x épée (50$)
1 x bouclier (35$)
2 x potion (20$)
3 x flèche (6$)
Total : 111$