Écrire un module

Pour Kneedeck 0.32.0 et suivants.

Un module est une page web qui s'affiche dans un onglet de la tablette, sur le PC et sur le smartphone. Il s'écrit en HTML, CSS et JavaScript.

Ton premier module accepté dans le catalogue t'offre la licence de soutien. Le catalogue accepte les modules qui servent vraiment en jeu : les pages d'essai et les copies d'un exemple ou d'un autre module sont refusées.

1. Le dossier du module

kneedeck-module.json : sa carte, qui dit qui il est et ce qu'il demande.
index.html : sa première page.
Ses autres fichiers, rangés comme il veut dans des sous-dossiers.

Types de fichiers reconnus : .html, .js, .mjs, .css, .json, .txt, .svg, .png, .jpg, .webp, .gif, .woff2, .woff, .mp3, .ogg, .wav. Un autre fichier est transmis tel quel, comme simples données que le script du module peut lire.

Au plus 500 fichiers et 20 Mo.

2. La carte : kneedeck-module.json

{
  "id": "dupont.carburant",
  "name": { "fr": "Carburant", "en": "Fuel" },
  "description": { "fr": "Le carburant à bord, d'après SimBrief.", "en": "The fuel on board, from SimBrief." },
  "version": "1.0.0",
  "author": "Dupont",
  "languages": ["fr", "en"],
  "games": ["DCS World"],
  "permissions": {
    "storage": true,
    "internet": ["www.simbrief.com"],
    "gameData": ["dcs"]
  }
}

Champ	Ce qu'il contient
`id`	Son identifiant pour Kneedeck : minuscules, chiffres, points et tirets, comme `dupont.carburant`. Les noms qui commencent par `kneedeck.` sont réservés. Un module de même `id` remplace l'ancien.
`name`	Son nom, en un texte ou par langue.
`description`	Facultatif. Ce qu'il fait, en un texte ou par langue.
`version`	Sa version, 20 caractères au plus.
`author`	Son auteur, 60 caractères au plus.
`entry`	Facultatif. Sa première page, `index.html` si le champ n'est pas renseigné.
`languages`	Facultatif. Les langues de ses textes, par code : `fr`, `en`, `pt-BR`.
`games`	Facultatif. Les jeux pour lesquels il est fait.
`permissions.storage`	Il garde ses données, pour chaque profil (1 Mo au plus).
`permissions.internet`	Les sites qu'il contacte, par leur nom, 10 au plus. Aucun autre site ne lui répond.
`permissions.gameData`	Les données de jeux qu'il lit : `starcitizen`, `elite`, `dcs`.

Kneedeck montre au joueur ce que le module demande avant de l'installer.

3. La page

La page charge l'aide de Kneedeck, qui lui donne l'objet Kneedeck :

<!doctype html>
<html>
<head>
<meta charset="utf-8">
<link rel="stylesheet" href="carburant.css">
<script src="../kneedeck-module.js"></script>
<script src="carburant.js" defer></script>
</head>
<body>…</body>
</html>

L'objet Kneedeck	Ce qu'il fait
`Kneedeck.ready((k) => …)`	Appelé quand le module est prêt : `k.language`, `k.data` (ses données gardées), `k.preview` (vrai dans l'aperçu de l'écran Onglets).
`Kneedeck.text({ fr: "Démarrer", en: "Start" })`	Le texte dans la langue du joueur, ou sinon en anglais.
`Kneedeck.save(données)`	Garde une valeur JSON pour le profil affiché. Demande `storage`.
`Kneedeck.on("data", (données) => …)`	Ses données ont changé dans l'autre fenêtre, ou le profil affiché a changé.
`Kneedeck.on("language", (code) => …)`	Le joueur a choisi une autre langue.
`Kneedeck.on("page", (pas) => …)`	La commande « page suivante » (1) ou « page précédente » (-1) du joueur.
`Kneedeck.games`, `Kneedeck.on("games", …)`	Les données des jeux demandées dans la carte, et chaque changement.
`Kneedeck.keyboard(vrai ou faux)`	Prend le clavier au jeu, ou le lui rend, pendant que l'onglet est affiché. Un champ de texte le prend tout seul quand on le touche, et Échap le rend.
`Kneedeck.now()`	L'heure en millisecondes, celle du PC sur tous les appareils : pour un minuteur qui doit lire la même chose sur le PC et le smartphone.

Les couleurs de la tablette arrivent en variables CSS : --kd-paper, --kd-ink, --kd-rule, --kd-under, --kd-accent.

4. Les données des jeux

Kneedeck.games.starcitizen : found, running, environment, version, handle, shard, location (le code du jeu), place (le nom lisible, ou null), contracts (avec leurs objectives), notifications.

Kneedeck.games.elite : found, running, commander, ship, shipName, shipIdent, system, body, station, docked, landed, fuel, fuelCapacity, cargo, cargoCapacity, cargoItems, credits, missions.

Kneedeck.games.dcs : flying, paused, aircraft, coalition (1 rouge, 2 bleu), mission (nom, carte, date, briefings, météo), model (l'heure de mission), toldAt, messages. Il faut que le joueur ait relié Kneedeck à DCS, dans l'écran Onglets.

5. Ce qu'un module ne peut pas faire

Voir les fichiers du PC, les autres onglets ou le reste de Kneedeck.
Exécuter un script qui n'est pas dans son dossier : pas de script venu d'Internet, pas de eval, pas de script écrit dans la page.
Contacter un site qui n'est pas dans sa carte.
Ouvrir une autre page dans un cadre, envoyer un formulaire ou lancer une tâche en arrière-plan.

6. L'essayer

Dans Kneedeck : Modules, puis « Ajouter un module depuis un dossier… » ou « … depuis un zip… ». Ensuite « Ajouter en onglet ». Pour une nouvelle version, ajoute-le de nouveau : il remplace l'ancien.

7. Exemples à télécharger

Bonjour : le plus petit module, un bonjour dans la langue du joueur et un compteur gardé.
Minuteur, Checklist et Star Citizen : les modules livrés avec Kneedeck, sous un autre id.

8. Le partager

Dépose-le dans le catalogue des modules : connecte-toi à Mon compte avec ton adresse mail, puis « Déposer un module » avec son zip, ses langues, ses jeux et jusqu'à 4 photos.

Le catalogue accepte les types de fichiers reconnus seulement, et un code lisible.
ASSODIO vérifie chaque module, et chaque nouvelle version, avant de les mettre en ligne. Tu reçois un mail quand il est accepté ou refusé.
Les joueurs qui ont la licence de soutien l'installent en un clic depuis le catalogue, dans Kneedeck, et le notent de 1 à 5 étoiles.
Ton premier module accepté t'offre la licence de soutien.

Ce qui fait accepter un module :

Il sert en jeu : il aide le joueur à voler, rouler, naviguer ou jouer, par exemple avec les données du jeu, une checklist ou un calcul.
Il apporte quelque chose qu'aucun module du catalogue ne fait déjà, ou le fait nettement mieux.
Il marche, ses textes sont clairs, et ses photos montrent ce qu'il fait vraiment.
Ce qu'il demande, sites et données des jeux, correspond à ce qu'il fait.

En cas de refus, le mail en donne la raison. Un module refusé peut être déposé de nouveau, amélioré.

Tu peux aussi donner son zip : l'autre joueur l'ajoute depuis un zip.