Wiki

01 · Fonctionnement global

Comment ShowManager est organisé

ShowManager fonctionne comme un pont entre le site web, les fichiers du serveur Minecraft et les commandes exécutées pendant un spectacle. Le site sert à préparer les données, le plugin les charge, puis le moteur de lecture garde la synchronisation en temps réel pendant l’exécution.

1. SiteÉdition et preview

Les shows, drones, pistes, groupes, timelines, couleurs, fichiers audio et exports sont préparés depuis l’interface web.

2. APICommunication contrôlée

Le site discute avec le serveur via une clé API. Les liens temporaires ne transportent qu’un code, puis le serveur renvoie les données autorisées.

3. PluginLecture Minecraft

Le plugin lit les fichiers, précharge ce qui doit l’être, exécute les commandes et nettoie les entités à la fin.

Shows classiques

Une timeline composée d’événements, pistes, groupes, commandes, audio et statuts web.

Fixtures

Beams, spotlights, fontaines, groupes [GR], rotations, couleurs et transitions envoyées à Minecraft.

Drones

Séquences 3D séparées, positions relatives au centre de lancement, rendu Display ou Particule et nettoyage automatique.

Performers

Enregistrements de mouvements joueurs, NPC Citizens, skins locales, commandes et emotes synchronisées.

Network

États web_status, codes temporaires, API locale et synchronisation avec la régie.

Configuration

Les options sont séparées par module pour garder des fichiers lisibles et rechargeables par partie.

Règle de sécurité : un show chargé depuis un code temporaire ne remplace jamais automatiquement une version locale sans confirmation.
Règle de synchronisation : le moteur compare les ticks Minecraft avec le temps réel écoulé pour limiter les décalages en cas de lag.
Règle de nettoyage : drones, tasks et entités temporaires doivent être supprimés sur stop, reload, redémarrage et désactivation.
Règle de compatibilité : les anciens fichiers et commandes utiles restent lisibles, mais la documentation met en avant le format propre actuel.

02 · Démarrage

Installation serveur

ShowManager est un plugin Paper/Spigot pensé pour Minecraft 1.20+, compilé en Java 17. Citizens est utilisé pour les performers/NPC et ItemsAdder peut être utilisé pour les emotes.

1. Installer

Place le fichier jar dans plugins/, démarre le serveur puis laisse ShowManager générer ses dossiers.

2. Configurer

Renseigne le monde par défaut, l’URL du site, le port local et la clé API dans les fichiers de configuration.

3. Recharger

Utilise /sm reload all après modification, ou recharge seulement le module concerné.

Vérifie que Citizens est chargé avant d’utiliser les performers, sinon les NPC ne pourront pas être créés.
Garde la même version Java entre ton serveur de test et ton serveur live pour éviter les comportements différents au démarrage.
Après la première génération, configure les fichiers YAML avant de lancer un show public.
Teste les commandes sur un monde de test avec console-output: Debug, puis repasse en ALL ou none selon le besoin.

Alias principal

/showmanager et /sm pointent vers les mêmes commandes.

03 · Site web

Workflow site ↔ serveur

Le site sert à créer les shows, organiser les tableaux de bord, éditer les mouvements de scène, préparer les drones et envoyer les données au plugin.

SiteÉdition visuelle

Shows classiques, timeline, audio, preview, drones, mouvements de scène et mode régie.

CodeLien temporaire

Le plugin envoie un code temporaire dans l’URL, pas tout le show. Le site charge ensuite les données depuis le serveur.

ServeurImport / export

Si la clé API correspond, le site peut récupérer ou remplacer un show côté serveur avec confirmation.

Import complet du serveur

Charge un show présent côté Minecraft vers le site pour l’éditer sans passer par un fichier manuel.

Code temporaire

Ouvre un show envoyé par le plugin avec une URL courte contenant seulement le code.

Export complet vers serveur

Remplace le show serveur après validation de la clé API et confirmation si un show existe déjà.

Le menu Serveur des shows contient l’import complet, le chargement par code temporaire et l’export complet vers serveur.
Le menu Archive sert aux imports/exports JSON et ZIP locaux.
Un show temporaire chargé depuis un lien ne doit pas écraser automatiquement un show local existant.
Le site affiche une alerte si le serveur sélectionné ne correspond pas aux informations du show chargé.
La sauvegarde locale crée un nom temporaire numéroté si un show du même nom existe déjà.

04 · Shows classiques

Créer, prévisualiser et lancer un show

Un show classique est composé de pistes, groupes, événements, commandes Minecraft, audio et états de pistes. Le moteur garde la synchronisation en se basant sur le temps réel, ce qui limite les décalages lorsque le serveur lag.

Timeline

Chaque événement possède un temps de départ. Le moteur saute les retards éventuels sans perdre les actions prévues.

Pistes et groupes

Les pistes peuvent être activées ou désactivées pour répéter une partie du show sans rejouer tout le spectacle.

Audio

Le site sert à prévisualiser la musique et caler les événements. Le plugin garde la logique de lecture côté Minecraft.

/sm start <showName>Lance le show.

/sm stop <showName>Arrête le show en cours.

/sm loop <showName>Lance ou configure le show en boucle.

/sm reset <showName>Arrête le show et exécute les resets de fixtures disponibles.

/sm edit <showName>Ouvre l’éditeur web avec un code temporaire.

/sm edit <showName> piste listAffiche l’état des pistes et groupes.

/sm edit <showName> piste <piste|groupe|all> <true|false>Active ou désactive une piste, un groupe ou tout le show.

/sm web-editor <showName>Prépare un lien temporaire vers le site.

Utilise /sm edit <showName> pour ouvrir le show dans l’éditeur web avec le bon code temporaire.
Garde les resets dans le show ou dans la commande /sm reset pour nettoyer les fixtures avant un nouveau lancement.
Pour un show long, préfère des groupes de pistes nommés clairement : lumière, mapping, audio, performers, drones.

05 · Spotlights, beams et fontaines

Contrôler les fixtures

Les fixtures sont pilotées par nom d’entité ou par groupe avec le préfixe [GR]. Les groupes sont définis dans config-spotlight.yml.

Nom direct

La commande cible une seule entité, par exemple un ItemDisplay de beam ou une fontaine.

Groupe

Le préfixe [GR] applique la commande à toutes les entités déclarées dans le groupe.

Durations

duration contrôle la transition visuelle et teleport_duration contrôle l’interpolation de mouvement.

/sm beam angle <type> <name|[GR]group> <color> <scaleX> <scaleY> <scaleZ> <duration> <teleport_duration> <angle1> <angle2>

Compatibilité propre pour l’ancien /zbeam.

/sm beam pos <type> <name|[GR]group> <color> <scaleX> <scaleY> <scaleZ> <duration> <teleport_duration> <targetX> <targetY> <targetZ>

Compatibilité propre pour l’ancien /zbeam1.

/zbeam ...Ancienne commande conservée pour les rotations par angles.

/zbeam1 ...Ancienne commande conservée pour viser une position.

/fountain <name|[GR]group> <startMotionX> <startMotionY> <startMotionZ> <startColorRGB> <endMotionX> <endMotionY> <endMotionZ> <endColorRGB> <time> <spreadStart[,spreadEnd]>

Crée un jet de particules depuis une entité ou un groupe.

/fountain <name|[GR]group> debug <rotationY>Affiche un debug de rotation pour régler une fontaine.

constant : vitesse angulaire stable quaternion : SLERP expérimental legacy : ancienne interpolation

Le mode constant est conseillé pour éviter les accélérations ou les détours inutiles pendant une rotation.
Le mode legacy reste utile si tu veux retrouver exactement l’ancien comportement.
Les valeurs de couleur peuvent venir du site ou être envoyées en RGB entier selon la commande utilisée.

06 · Shows drones

Éditeur 3D et lecture Minecraft

L’éditeur drone permet de créer des groupes et sous-groupes, déplacer une formation, définir des keyframes de position, rotation, visibilité et couleur, importer des formes, modèles 3D ou photos, puis exporter une séquence JSON séparée compatible plugin.

Display

Utilise des ItemDisplay, l’interpolation Minecraft, la luminosité 15 et un CustomModelData optionnel.

Particule

Mode léger pour limiter les FPS/TPS, avec particules configurables dans config-drone.yml.

Preview

Le site permet de régler le centre, la rotation, la timeline, l’audio et les points de preview avant l’export.

/sm drone preload <show> <x> <y> <z> <rotation> <Display|Particule> [customModelData]Précharge les entités au centre donné pour réduire le délai au lancement.

/sm drone play <show> <x> <y> <z> <rotation> <Display|Particule> [customModelData]Lance le show drone. Si rien n’est préchargé, le lancement classique reste disponible.

/sm drone stop <show>Stoppe un show drone et nettoie ses entités.

/sm drone stop allStoppe tous les shows drones actifs.

/sm drone web-editor <show>Ouvre l’éditeur drone web avec un code temporaire.

Les positions du JSON sont relatives au centre fourni dans la commande.
Les entités utilisent un identifiant prévisible du type showmanager_drone_<show>_<id>.
Le nettoyage s’effectue sur stop, reload, redémarrage et désactivation du plugin.
Le CustomModelData est disponible uniquement en mode Display.
Le préchargement prépare les entités au bon centre avant le lancement pour éviter un décalage au top départ.
Les drones invisibles doivent être réellement masqués côté plugin, pas seulement ignorés par la preview.

07 · Performers / NPC

Enregistrer et rejouer des acteurs

Le module performers enregistre les déplacements de joueurs, crée des NPC via Citizens, applique les skins locales et peut synchroniser des commandes ou emotes ItemsAdder sur la timeline.

Record

Stocke les positions, rotations et informations de performer dans un fichier réutilisable.

NPC

Citizens sert à afficher les performers pendant la lecture, avec un identifiant propre au record.

Skins

Les skins locales évitent de dépendre uniquement du profil joueur pendant un show.

/sm performers start <record> players:Alexis,Lucas [prefix:danseur]Démarre un enregistrement multi-performer.

/sm performers addnpc <record> <npcId> player:Alexis [skin:local:robot]Ajoute un performer/NPC dans un record existant.

/sm performers play <record> [performer:npcId]Rejoue tout le record ou un performer précis.

/sm performers stopplay|pause|resume <record>Contrôle le replay.

/sm performers loop <record> <true|false>Active ou désactive la boucle.

/sm performers skin import <skin> [force]Génère ou met à jour une skin locale depuis un PNG.

/sm performers skin importall [force]Importe toutes les skins locales.

/sm performers command add|list|remove ...Gère les commandes synchronisées.

Dossiers historiques

Les données performers restent dans perfomers/records/ et perfomers/skins/ pour garder la compatibilité avec l’existant.

Avant de rejouer une copie de record, le plugin doit nettoyer les NPC déjà présents pour éviter les doublons Citizens.
Si une skin ne s’applique pas, réimporte-la puis relance le record après vérification de Citizens.
Les commandes et emotes synchronisées suivent la timeline du record, pas seulement le moment où tu lances la commande.

08 · Commandes utiles

Commandes par module

Les commandes principales passent par /showmanager ou /sm. Les modules spécialisés gardent aussi leurs commandes dédiées quand elles sont nécessaires pour la compatibilité ou pour un usage rapide en jeu.

Administration

Reload, console-output, API, serveur web local et commandes de diagnostic.

Show

Lancement, arrêt, reset, boucle, ouverture de l’éditeur web et activation des pistes.

Modules visuels

Drones, beams, fontaines, mapping, screens, fireworks et commandes custom.

/sm config console-output <ALL|Debug|none>Règle les retours console, y compris les messages Fountain.

/sm api giveAffiche la clé API actuelle avec copie rapide.

/sm api set <clé>Met à jour la clé API utilisée par le serveur local.

/sm web_status set <show> <id> <true|false|temp|custom> [text]Met à jour un état web synchronisé.

/sm web_status info <show> <id>Affiche l’état d’une entrée web_status.

/sm web_status sync <show>Synchronise les états web_status d’un show.

/sm restart-proxyRedémarre le serveur web local du plugin.

/mapping play|stop|preview ...Pilote un mapping ItemDisplay et CustomModelData.

/fireworks <x> <y> <z> <dirX> <dirY> <dirZ> <explodeTick> <type> [<#hex,...>]Lance un feu d’artifice custom.

/dtm <distance>Convertit les valeurs de damage en CustomModelData sur les ItemDisplay proches.

/cmd reload|search|menu ...Ouvre et administre le menu de give custom.

Utilise /sm reload messages après modification de config-Message.yml pour tester les textes sans recharger tout le plugin.
Utilise /sm reload drone après modification de config-drone.yml ou après nettoyage d’une séquence drone.
Le mode console-output none est utile en live pour éviter une console trop lourde pendant les commandes de show.
Le mode Debug est à garder pour les phases de test : preload, lancement, export serveur, fontaines et diagnostics.

09 · Configuration

Fichiers importants

La configuration est volontairement séparée par module. L’objectif est de pouvoir relire rapidement un fichier, recharger une petite partie du plugin et éviter un gros config.yml impossible à maintenir.

`config.yml` · base du plugin

Ce fichier contient les options communes que presque tous les modules utilisent. C’est ici que tu règles l’identité du serveur, la connexion au site, le comportement console et les valeurs globales qui ne dépendent pas d’un module précis.

server.nameNom lisible du serveur. Le site s’en sert pour vérifier qu’un show temporaire appartient au bon serveur avant de l’importer.

web.urlAdresse publique du site ShowManager, par exemple https://show-manager-mc.vercel.app/. Les commandes web-editor construisent leurs liens avec cette base.

api.keyClé privée utilisée pour autoriser l’import/export serveur. Elle doit correspondre côté site et côté plugin.

local-server.portPort du serveur local/proxy utilisé pour recevoir les requêtes du site, les codes temporaires et les données exportées.

default-worldMonde utilisé quand une commande ou un fichier ne précise pas explicitement le monde cible.

console-outputALL affiche tout, Debug garde les infos utiles de test, none coupe les retours de commandes ShowManager.

À modifier quand tu changes d’URL de site, de serveur Minecraft, de clé API ou de politique console.
Recharge conseillé : /sm reload global, ou /sm reload all après un changement API/serveur local.

`network/` · échanges site serveur

Le dossier network garde les états synchronisés entre le site, la régie et le plugin. Il sert surtout aux codes temporaires, aux web_status et aux données liées aux shows ouverts depuis le web.

network/web_status/États consultables par le site : valeurs temporaires, booléens, textes personnalisés et statuts liés à un show.

temporary-codesCodes générés par /sm edit, /sm web-editor et /sm drone web-editor. Le lien ne doit contenir que ce code.

server-checkVérifie que le show chargé correspond au serveur sélectionné dans le site avant d’autoriser l’édition.

export-policyContrôle le remplacement serveur : confirmation côté site, validation API côté plugin, puis remplacement du show ciblé.

À vérifier si un lien temporaire ne charge pas, si le site affiche le mauvais serveur ou si un export serveur est refusé.
Recharge conseillé : /sm reload network.

`config-performers.yml` · NPC et enregistrements

Ce fichier contrôle tout ce qui touche aux performers : Citizens, les records, les skins locales, les commandes synchronisées et les emotes ItemsAdder.

citizens.enabledActive l’intégration Citizens. Si Citizens n’est pas présent ou pas chargé, les NPC ne peuvent pas être rejoués correctement.

recording.sample-rateFréquence d’échantillonnage des positions pendant l’enregistrement. Plus c’est précis, plus les fichiers sont lourds.

playback.cleanup-before-playSupprime les NPC existants du même record avant une lecture pour éviter les doublons, notamment sur les copies de records.

skins.local-folderDossier des PNG et fichiers générés pour les skins locales.

commands.allowedListe ou politique des commandes autorisées pendant un replay performer.

itemsadder.emotesActive ou ajuste les emotes synchronisées si ItemsAdder est utilisé sur le serveur.

À modifier si tu as des soucis de skin, de NPC créés en double, d’emotes ou de fluidité des records.
Recharge conseillé : /sm reload performers.

`config-spotlight.yml` · beams, fixtures et fontaines

Ce fichier décrit les groupes de fixtures, les types de beams, les valeurs par défaut et la méthode de rotation utilisée pendant les transitions.

beamgroupDéclare les groupes utilisés avec le préfixe [GR]. Un groupe doit contenir les noms exacts des entités à piloter.

rotation.modeChoix du mode de rotation : constant pour une vitesse stable, quaternion pour SLERP expérimental, legacy pour l’ancien comportement.

duration-defaultsValeurs par défaut de transition si une commande ne fournit pas toute l’information.

fountain.groupsDéfinit les groupes compatibles Fountain et leurs réglages par défaut.

debug.enabledActive des retours plus précis pour comprendre les rotations, les groupes non trouvés ou les commandes mal formées.

À modifier quand un groupe ne répond pas, quand une rotation semble bizarre ou quand les durées envoyées ne correspondent pas au rendu attendu.
Recharge conseillé : /sm reload spotlight.

`config-drone.yml` · shows drones

Ce fichier est critique pour les performances. Il règle le rendu, la distance d’affichage des ItemDisplay, la fréquence de mise à jour, le préchargement et le nettoyage des entités.

display.item-view-rangeDistance de rendu des ItemDisplay. Plus elle est haute, plus les clients peuvent recevoir d’entités.

display.interpolationUtilise l’interpolation Minecraft pour éviter de téléporter les drones à chaque tick.

playback.frequency-ticksFréquence des mises à jour plugin. Une valeur trop basse est fluide mais plus coûteuse, une valeur trop haute peut rendre le mouvement moins précis.

preload.enabledPrépare les entités avant le lancement pour éviter le décalage au démarrage du show.

particles.modeOptions du rendu Particule, plus léger que les ItemDisplay pour les grosses formations.

cleanup.on-stop-reload-disableNettoie les entités sur stop, reload, redémarrage et désactivation du plugin.

À modifier si tu as beaucoup de drones, des FPS bas, des entités restantes ou un délai au lancement.
Recharge conseillé : /sm reload drone.

`config-Message.yml` · messages configurables

Ce fichier doit contenir les textes envoyés aux joueurs et à l’équipe technique. L’objectif est que les usages, erreurs, confirmations et statuts soient modifiables sans toucher au code.

prefixPréfixe global des messages ShowManager.

errors.*Messages d’erreur : permission refusée, show introuvable, config invalide, API refusée, serveur incorrect.

usage.*Textes d’aide pour les commandes /sm, drones, performers, beams, fontaines, reload et API.

success.*Confirmations : show lancé, export reçu, preload prêt, reload terminé, skin importée, entités nettoyées.

debug.*Messages visibles seulement lorsque console-output est en mode Debug.

À modifier pour traduire, raccourcir ou clarifier tous les retours joueurs/console.
Recharge conseillé : /sm reload messages.

Migration, sauvegarde et reload ciblé

Quand le plugin détecte une ancienne configuration, il doit la sauvegarder, générer la nouvelle structure propre, puis replacer les valeurs connues dans les bons fichiers.

backup/config-migration/Dossier de sauvegarde automatique avant transformation des anciennes configs.

/sm reload allRecharge tout le plugin après une migration ou une grosse modification.

/sm reload globalRecharge les options communes et la connexion site/API.

/sm reload networkRecharge les états réseau et web_status.

/sm reload performers|spotlight|drone|messagesRecharge uniquement le module ciblé pour éviter de perturber tout le serveur.

Après migration, garde la sauvegarde tant que tu n’as pas testé un show, un drone, un performer et un export serveur.
Ne supprime pas une clé inconnue sans vérifier si elle vient d’une ancienne version encore utilisée par un module.

Les anciennes configurations sont migrées automatiquement au démarrage, avec sauvegarde avant nettoyage.

Après migration, vérifie les fichiers générés avant de supprimer les sauvegardes.
Pour un changement live, privilégie un reload ciblé : /sm reload messages, /sm reload drone, /sm reload spotlight.
Garde la clé API privée : le site doit seulement l’utiliser pour autoriser les imports/exports serveur.

10 · Fichiers et données

Où vivent les données

ShowManager sépare les données éditables, les états réseau et les fichiers de show pour faciliter les sauvegardes et éviter les écrasements involontaires.

shows/

Shows classiques exportés par le site et lus par le plugin.

drone-shows/

Séquences drones séparées, relatives au centre fourni dans la commande de lecture.

perfomers/records/

Enregistrements performers/NPC conservés dans le dossier historique.

perfomers/skins/

Images PNG et fichiers YML de skins locales générés ou importés.

network/web_status/

États synchronisés avec l’interface web et la régie.

backup/config-migration/

Sauvegarde automatique avant migration des anciennes configs.

Les fichiers shows/ et drone-shows/ peuvent être sauvegardés séparément pour préparer un rollback rapide.
Les données network/ sont des états de fonctionnement : elles peuvent changer souvent pendant l’édition ou le live.
Les imports ZIP doivent garder les dossiers attendus pour que le site et le plugin retrouvent les fichiers au bon endroit.
Un export serveur doit remplacer le show demandé uniquement après validation et ne doit pas créer une copie fantôme.

11 · Permissions

Accès administrateur

Les permissions sont prévues pour garder les commandes sensibles côté opérateurs ou équipe technique.

showmanager.adminAccès complet à ShowManager, aux drones, à l’API, aux beams et à la plupart des commandes d’administration.

showmanager.reloadAutorise le rechargement avec /sm reload.

showmanager.fireworksAutorise /fireworks.

showmanager.performers.adminAccès complet au module performers.

showmanager.performers.recordEnregistrement performers.

showmanager.performers.playLecture, pause, reprise et arrêt des records performers.

showmanager.performers.skinGestion des skins locales ou joueur.

showmanager.performers.commandGestion des commandes synchronisées.

showmanager.performers.emoteGestion des emotes ItemsAdder.

zilver.adminCompatibilité avec les commandes fixtures historiques.

Exemple LuckPerms

/lp group admin permission set showmanager.admin true donne l’accès complet. Pour un rôle régie, préfère donner seulement les permissions nécessaires au show.

Ne donne pas l’accès API ou reload à un rôle public.
Prépare un groupe opérateur pour les lancements live et un groupe technique pour la configuration.
Teste les permissions depuis un compte non-op avant une représentation.

12 · Dépannage

Réflexes quand quelque chose bloque

1. Identifier

Repère le module concerné : site, API, show, drone, performers, spotlight, fountain ou config.

2. Isoler

Recharge seulement la partie concernée et relance une commande simple pour confirmer le problème.

3. Nettoyer

Stoppe les tâches et entités temporaires avant de relancer un show ou une preview.

Le site ne charge pas un show temporaire : vérifie le serveur sélectionné, la clé API, le port local et l’expiration du code.
Un export serveur refuse de partir : compare la clé API du site avec celle de config.yml, puis teste /sm api give.
Les drones semblent lourds : teste le mode Particule, baisse frequency-ticks, ajuste item-view-range et utilise /sm drone preload.
Des drones restent en jeu : lance /sm drone stop all, puis /sm reload drone si besoin.
Une skin performer ne s’applique pas : place le PNG dans le dossier skins, lance /sm performers skin import <skin> ou importall, puis vérifie Citizens.
Une fixture de groupe ne répond pas : vérifie le nom [GR]groupe, le contenu de beamgroup et les noms exacts des ItemDisplay.
Les durées spotlight semblent inversées : contrôle la commande envoyée, puis compare duration et teleport_duration avec les valeurs JSON du site.
La console est trop remplie : passe temporairement en /sm config console-output none, puis reviens en Debug pour analyser.

Documentation ShowManager claire, complète et rangée par sujet.