JSD files : structure et ouverture

Les fichiers JSD désignent en réalité trois formats distincts qui n'ont presque rien en commun, sinon leur extension. Que vous travailliez sur le jeu Jagged Alliance 2, sur du contrôle industriel via EtherCAT, ou sur la validation de schémas JavaScript, le terme JSD cache des structures techniques radicalement différentes. Voici comment démêler tout ça.

Décoder la structure interne des fichiers JSD

Le format JSD historiquement le plus documenté vient du jeu Jagged Alliance 2, développé avec le support de Freedom Scientific lors des premières versions de JAWS. Ces fichiers stockent les propriétés physiques des objets du jeu : leur forme, leur solidité, leurs points de vie, et leur comportement face aux projectiles.

Chaque fichier commence par un en-tête de 16 bytes (la structure STRUCTUREFILEHEADER), identifiable grâce à la signature "J2SD" sur les 4 premiers octets. Les bytes 5 à 6 indiquent le nombre de structures ou d'images associées à l'objet. Les bytes 7 et 8 précisent le nombre de structures décrites. Le byte 11, lui, contient les flags de type de fichier : c'est lui qui vous dira immédiatement à quel variant vous avez affaire.

Il existe trois types de fichiers JSD :

1. Type 1 (valeur 00000001) : contient uniquement des informations auxiliaires, sans données structurelles.
2. Type 2 (valeur 00000010) : contient exclusivement des données structurelles, sans informations auxiliaires.
3. Type 3 (valeur 00000011) : combine les deux, avec les données auxiliaires en premier, puis les données structurelles.

Les données auxiliaires (AuxObjectData) occupent elles aussi 16 bytes. On y trouve l'orientation du mur sur 1 byte (valeurs 1 à 4 pour les directions NE, NW, SW, SE, ou 0 pour aucune orientation), le nombre de tuiles, et des flags comme AUXANIMATEDTILE ou AUXINTERACTIVETILE qui définissent le comportement dynamique de l'objet.

Du côté structurel, la structure DBSTRUCTURE fait également 16 bytes et encode des paramètres physiques précis. L'armure prend des valeurs de 0 à 26 (index dans un tableau de réservation), la densité va de 0 à 100 et influe directement sur la probabilité qu'une balle traverse l'objet. Pour les détails de forme, chaque tuile de structure (DBSTRUCTURE_TILE) pèse 32 bytes, dont 25 bytes décrivent la forme en grille 5x5, avec 16 façons de remplissage possibles (valeurs 0 à 15, chaque valeur représentant des cubes remplis selon un encodage bit à bit).

Pour les fichiers de type 1, les frames de description utilisent 16 bytes seulement au lieu des 32 bytes standard. Le premier byte encode la direction, le septième le nombre d'images dans la séquence d'animation, et le neuvième byte est fixé à 02 pour les fichiers JSD animés. Un détail qui compte quand vous écrivez un parseur.

La bibliothèque JSD pour l'automatisation industrielle

Complètement distinct du format de jeu vidéo, la bibliothèque JSD développée par la NASA JPL cible le contrôle d'appareils EtherCAT via SOEM (Simple Open EtherCAT Master). C'est une bibliothèque C destinée aux environnements Linux industriels, testée sur Ubuntu 16.04, 18.04, 20.04, 22.04, 24.04 et sur Raspberry Pi.

Pour compiler, il faut au minimum CMake 3.11, les threads POSIX, et SOEM. L'installation de libreadline-dev reste optionnelle mais nécessaire pour certains outils de test. La compilation se fait classiquement : mkdir build, cd build, cmake .., puis make.

Les appareils supportés sont classés en trois niveaux de priorité. Voici un aperçu des principaux :

Parmi les outils embarqués, jsdslaveinfo permet l'introspection des appareils esclaves avec l'option -map pour lister les mappages PDO actifs. Pour les contributions, le projet impose un formatage via clang-format avec le style Google par défaut, exécuté via make format. Tous les enums, structs et fonctions doivent porter le préfixe jsd. La gestion des versions suit le versionnage sémantique : majeure pour les changements d'API incompatibles, mineure pour les nouvelles fonctionnalités, patch pour les corrections de bugs.

Valider du JavaScript avec un schéma JSD

Troisième usage, radicalement différent : JSD comme validateur de schéma JavaScript. Le principe ressemble à ce que XSD fait pour XML. Le projet JSDValidator, créé par Mark Homans et hébergé sur GitHub (dépôt markhomans/JSDValidator), permet de définir un schéma avec des attributs possédant les propriétés Name, Type et optionnellement Values pour restreindre les valeurs autorisées.

La façon Validate() teste la conformité d'un objet JavaScript au schéma défini. C'est simple, direct, utile. Le projet est publié sous licence FreeBSD avec copyright 2013 de Build-Software. Pour intégrer JSD à un projet d'isolation performante, sachez que le même souci de rigueur s'applique : l'efficacité thermique du triple vitrage repose aussi sur des spécifications précises qu'il vaut mieux vérifier en amont.

Franchement, si vous cherchez à manipuler des fichiers JSD, commencez toujours par identifier le contexte : jeu vidéo, robotique ou JavaScript. Ce sont trois formats sans lien entre eux, et confondre leur structure vous fera perdre un temps considérable.