Write a module

For Kneedeck 0.32.0 and later.

A module is a web page shown in a tab of the tablet, on the PC and on the phone. It is written in HTML, CSS and JavaScript.

Your first module accepted in the catalogue gets you the supporter licence, free. The catalogue takes modules that are really useful in game: test pages and copies of an example or of another module are refused.

1. The module's folder

kneedeck-module.json: its card, which says who it is and what it asks for.
index.html: its first page.
Its other files, in subfolders as it likes.

File types recognised: .html, .js, .mjs, .css, .json, .txt, .svg, .png, .jpg, .webp, .gif, .woff2, .woff, .mp3, .ogg, .wav. Any other file is passed as it is, as plain data the module's script may read.

At most 500 files and 20 MB.

2. The card: kneedeck-module.json

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

Field	What it holds
`id`	Its identifier for Kneedeck: lowercase letters, digits, dots and dashes, such as `dupont.fuel`. Names starting with `kneedeck.` are reserved. A module with the same `id` replaces the old one.
`name`	Its name, as one text or by language.
`description`	Optional. What it does, as one text or by language.
`version`	Its version, 20 characters at most.
`author`	Its author, 60 characters at most.
`entry`	Optional. Its first page, `index.html` when the field is not given.
`languages`	Optional. The languages of its texts, by code: `en`, `fr`, `pt-BR`.
`games`	Optional. The games it is made for.
`permissions.storage`	It keeps its data, for each profile (1 MB at most).
`permissions.internet`	The sites it contacts, by name, 10 at most. No other site answers it.
`permissions.gameData`	The games' data it reads: `starcitizen`, `elite`, `dcs`.

Kneedeck shows the player what the module asks for before installing it.

3. The page

The page loads Kneedeck's helper, which gives it the Kneedeck object:

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

The Kneedeck object	What it does
`Kneedeck.ready((k) => …)`	Called once the module is ready: `k.language`, `k.data` (its kept data), `k.preview` (true in the Tabs screen's preview).
`Kneedeck.text({ en: "Start", fr: "Démarrer" })`	The text in the player's language, or else in English.
`Kneedeck.save(data)`	Keeps a JSON value for the profile shown. Needs `storage`.
`Kneedeck.on("data", (data) => …)`	Its data changed in the other window, or the profile shown changed.
`Kneedeck.on("language", (code) => …)`	The player picked another language.
`Kneedeck.on("page", (step) => …)`	The player's "next page" (1) or "previous page" (-1) control.
`Kneedeck.games`, `Kneedeck.on("games", …)`	The games' data asked for in the card, and each change.
`Kneedeck.keyboard(true or false)`	Takes the keyboard from the game, or gives it back, while the tab shows. A text field takes it by itself when touched, and Escape gives it back.
`Kneedeck.now()`	The time in milliseconds, the PC's on every device: for a timer that must read the same on the PC and the phone.

The tablet's colours come as CSS variables: --kd-paper, --kd-ink, --kd-rule, --kd-under, --kd-accent.

4. The games' data

Kneedeck.games.starcitizen: found, running, environment, version, handle, shard, location (the game's code), place (the readable name, or null), contracts (with their 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 red, 2 blue), mission (name, map, date, briefings, weather), model (the mission's time), toldAt, messages. The player must have linked Kneedeck to DCS, in the Tabs screen.

5. What a module cannot do

See the PC's files, the other tabs or the rest of Kneedeck.
Run a script that is not in its folder: no script from the Internet, no eval, no script written in the page.
Contact a site that is not in its card.
Open another page in a frame, send a form or start a background task.

6. Trying it

In Kneedeck: Modules, then "Add a module from a folder…" or "… from a zip…". Then "Add as a tab". For a new version, add it again: it replaces the old one.

7. Examples to download

Hello: the smallest module, a greeting in the player's language and a kept counter.
Timer, Checklist and Star Citizen: the modules that come with Kneedeck, under another id.

8. Sharing it

Submit it to the modules catalogue: sign in to My account with your email address, then "Submit a module" with its zip, its languages, its games and up to 4 pictures.

The catalogue takes the recognised file types only, and readable code.
ASSODIO checks each module, and each new version, before putting them online. You get an email when it is accepted or refused.
Players with the supporter licence install it in one click from the catalogue, in Kneedeck, and rate it from 1 to 5 stars.
Your first module accepted gets you the supporter licence, free.

What gets a module accepted:

It is useful in game: it helps the player fly, drive, navigate or play, for example with the game's data, a checklist or a calculation.
It brings something no module of the catalogue does already, or does it clearly better.
It works, its texts are clear, and its pictures show what it really does.
What it asks for, sites and games' data, matches what it does.

When a module is refused, the email gives the reason. A refused module can be submitted again, improved.

You can also give its zip: the other player adds it from a zip.