# Ludus — jeux d'enquête en ligne pour Dolibarr (PEREL) · v0.6.1

Fait jouer des escape games en ligne à partir de Dolibarr : codes d’activation, page de jeu publique, suivi des parties. La vente passe par le module Tessera.
Premier scénario fourni : **Opération Noël — Dossier 13**, cinq chapitres jouables de bout en bout, avec deux fins.

## Installation

1. Accueil → Configuration → Modules → onglet **Déployer/installer un module externe** → envoyer `module_ludus-0.6.1.zip`.
   Mise à jour depuis la 0.1 : déployer le nouveau zip, puis désactiver/réactiver le module (ajoute le réglage « Chapitre de départ de la démo »).
2. Activer **Ludus** dans la liste des modules (crée les tables `llx_ludus_*`).
3. Donner les droits aux utilisateurs concernés (voir les codes / générer les codes).

Dolibarr 18 ou plus, PHP 8.1 ou plus.

## Utilisation

- **Menu Ludus → Codes & parties** : générer des codes (quantité, scénario, réf. commande), voir leur statut (vendu, activé, remboursé), l'avancement de chaque partie et le tableau « Où les joueurs bloquent ».
- **Menu Ludus → Jouer (démo)** : ouvre la page publique. Le code de démonstration `DEMO-D13` crée une nouvelle partie à chaque saisie. Pensez à le vider avant la mise en vente.
- **Menu Ludus → Paramètres** : blocage après erreurs, durée de vie des parties, repères pointillés, préfixe des codes, code et scénario de démonstration, **chapitre de départ de la démo** (pour tester un chapitre sans rejouer les précédents).

Page à donner aux joueurs : `https://votre-dolibarr/custom/ludus/public/index.php`. Elle fonctionne sans compte Dolibarr.

## Nouveautés 0.5.1

- L'e-mail d'achat contient la confirmation de commande : quantité, prix payé, date, identité du vendeur (réglage « Identité du vendeur »), rappel de l'accord pour l'accès immédiat et de la renonciation au droit de rétractation, lien des CGV.
- Les traces anti-abus (adresses IP et e-mails hachés) sont effacées au bout de 24 h.

## Nouveautés 0.6.1

- **Retrait d'accès** (remboursement depuis Tessera ou icône « Rembourser » des codes) : le code est refusé et les parties déjà commencées avec ce code s'arrêtent.

## Nouveautés 0.6 — la vente passe par Tessera

- La boutique intégrée (page de vente, Stripe, webhook) est retirée de Ludus. La vente se fait avec le module **Tessera** : page d'achat reliée à votre site, commande, facture payée et livraison automatique.
- Ludus fournit à Tessera la livraison **« Enquête Ludus (codes + convocations) »** : un code par exemplaire acheté, rattaché au tiers, à la facture et à l'e-mail d'achat, avec la convocation PDF (destinataire imprimé si l'acheteur a rempli « Pour qui ? »). Elle n'apparaît dans Tessera que si Ludus est activé.
- Nouveau réglage **Lien « Offrir l'enquête »** (Paramètres → Codes) : lien affiché sous le champ de code de la page du jeu (votre page de site ou la page d'achat Tessera).
- Les anciennes adresses `shop.php`, `checkout.php`, `order.php`, `stripe_webhook.php` répondent « 410 » (`shop.php` redirige vers le lien d'achat s'il est renseigné). Si vous aviez déclaré le webhook de Ludus dans Stripe, supprimez-le.
- Récupération de code perdu et renvoi depuis le back-office inchangés.

## Nouveautés 0.4.1

- **Validité des codes** (Paramètres, en mois ; 0 = sans limite). Pendant la validité, l'enquête se joue, se reprend et se rejoue à volonté ; la date de fin est imprimée sur la convocation. Un code expiré est refusé à l'activation.
- **Destinataires** (facultatif) et **e-mail de l'acheteur** saisis à la génération, modifiables ensuite (icône crayon). Les destinataires s'impriment sur la convocation ; sinon une ligne reste à remplir à la main.
- **Code perdu ?** sur la page du jeu : le joueur saisit l'e-mail d'achat et reçoit ses codes valides avec les convocations en PDF. La réponse est toujours la même, qu'une adresse soit connue ou non.
- **Renvoyer au client** (icône enveloppe) depuis la liste des codes.
- **Limitation des essais** : 20 codes erronés par heure et par adresse IP ; 5 demandes « code perdu » par heure et par IP, 3 par jour et par adresse e-mail.
- Mise à jour depuis une version précédente : déployer le zip puis **désactiver / réactiver** le module (ajout des colonnes destinataires et e-mail).
- Les e-mails partent via la configuration e-mail de Dolibarr (expéditeur réglable dans Paramètres).

## Nouveautés 0.4

- **Convocation imprimable (carte-cadeau)** : une page A4 par code, avec le code, l'adresse du jeu et un QR code qui ouvre la page d'activation avec le code déjà saisi. Textes dans la clé `gift` du scénario.
- Dans **Codes & parties** : icône PDF sur chaque code, bouton « Convocations PDF de ces codes » juste après une génération, et cases à cocher pour imprimer une sélection (un PDF de plusieurs pages, pratique pour un lot CSE).

## Nouveautés 0.3

- **Convocation d'ouverture** avant le chapitre 1 (clé `prologue` du scénario) : le canal Octave démarre quand les joueurs acceptent la mission.
- **Bilan de fin d'enquête** (clé `epilogue`) : la fin obtenue, le récapitulatif des choix de chaque chapitre, la confiance d'Octave, le total des erreurs et des notes, et un bouton pour revenir à la décision finale et découvrir l'autre fin.
- **Sur téléphone**, le canal Octave devient un tiroir : bouton flottant avec le nombre de messages non lus, ouverture automatique quand Octave pose une question ou quand on transmet une réponse.

## Principes

- **Le serveur décide.** Le navigateur n'envoie que des intentions (positions des bandes, repère, choix). Les solutions, les déclencheurs et les notes non ouvertes ne quittent jamais le serveur.
- **Le scénario est une donnée** : `scenarios/<id>/scenario.json.php`. Un nouveau dossier = un nouveau sous-dossier. La première ligne PHP empêche toute lecture directe du fichier par le web : ne pas la retirer.
- **Une session = une équipe.** Le lien `?s=…` se partage ; tout le monde joue la même progression.

## Format du scénario (résumé)

| Clé du chapitre | Rôle |
|---|---|
| `documents` | Pièces ; `open: false` = scellée jusqu'à un `unlock`. |
| `notes` | Notes de Madeleine (indices), servies une par une. |
| `workbenches` | Établis du chapitre (type + affichage, jamais de solution). Un établi n'est envoyé au navigateur qu'à l'étape qui l'utilise. |
| `steps` | Étapes à valider dans l'ordre : `bench`, `check` (solution), `on_success`, `fail_lines` (avec `{right}`/`{total}`), `fail_rules` (échec spécifique). |
| `triggers` | `start`, `on:*` (déclenchables par le navigateur : `on:first_drag:B`, `on:doc_opened:3D`), les autres côté serveur uniquement. |
| `asks` | Choix narratifs : `add` / `set` sur les variables, puis `then`. |

Actions : `say`+`text`, `sys`, `sound` (clack, signal32, alarm, pulse), `unlock`, `wb` (lock, set, marks, reveal, show), `helpline`, `ask`, `add`, `set`, `if`/`then`/`else`, `goto`, `end` (+ `title`).
Vérifications : `tape_offsets`, `pin_time`, `fields` (correspondance champ par champ, compte les bonnes réponses), `text`, `number`.
Établis disponibles :

| Type | Usage dans Dossier 13 |
|---|---|
| `tape_align` | Bandes à caler sur une référence, repère à poser (ch. 1 et 3) |
| `sort_cards` | Cartes à classer en colonnes ou sur un plan (ch. 1 affirmations, ch. 2 plan de l'atelier) |
| `dial` | Cadran à N positions, phases photographiées (ch. 4, séquence 5–5–3) |
| `control_panel` | Pupitre : canal, mesures, séquenceur, procédure ordonnée (ch. 5) |

## Pour plus tard

`LudusStore::createCode()` est appelé par la livraison Tessera (`class/TesseraProviderLudus.class.php`, référence `tessera:<réf. de la vente>`, champs `fk_soc`, `fk_facture`, `email`).