Manuel de vectra-sdk

Version 0.12.0 · moteur VECTRA 7.9.15 (contrat 1, mode provisoire) · TRUvector

vectra-sdk sert à créer des scènes, des applications et des jeux avec le moteur VECTRA, dans le navigateur. Ce manuel explique tout ce que le kit sait faire aujourd'hui, comment s'en servir, et ce qui n'est pas encore fait. La liste exhaustive des nœuds, matières, comportements et noms anglais est dans la Référence, produite à partir du code.

1. Prendre en main

1.1 Ce qu'il faut

• Node.js 20 ou plus (pour les outils et les tests ; le kit lui-même tourne dans le navigateur).
• Le moteur VECTRA, à côté : le dépôt truvector/vectra (7.9.15 ou plus récent). vectra-sdk ne contient aucune ligne du moteur ; il le lit dans le dossier moteur/.
• Un navigateur avec WebGPU (Chrome, Edge, Safari récent) ; à défaut, WebGL2 (voir 10.2).

1.2 Installer

git clone git@github.com:truvector/vectra-sdk.git
cd vectra-sdk
npm install
npm run lier-moteur -- ../vectra        # moteur/ devient un lien vers ton dépôt du moteur
npm run dev                             # http://127.0.0.1:8080/

Ouvre ensuite http://127.0.0.1:8080/exemples/01-premier-monde.html, ou la Forge en ligne : http://127.0.0.1:8080/packages/forge-web/.

1.3 Un premier monde

import { Vectra, sdf, mat } from "./vectra/vectra.js";

const monde = await Vectra.creer("#ecran", { ciel: "heure-bleue" });

monde.ajouter(sdf.terrain({ relief: 4 }), mat.pierre());
const phare = sdf.boite([4, 18, 4]).arrondir(0.3)
  .moins(sdf.cylindre(1.2, 20))
  .fondre(sdf.sphere(3).en([0, 10, 0]), 0.8);
monde.ajouter(phare, mat.metal({ teinte: "#00D4FF" })).en([0, 9, -30]);
monde.repeter(sdf.sphere(0.5), { case: 6, hasard: 0.8, sur: "sol" }, mat.verre());
monde.joueur({ marche: true });

Ces quelques lignes donnent un terrain de pierre, un phare de métal creusé d'un puits, mille galets de verre posés sur le sol (calculés, pas stockés) et un joueur qui marche (ZQSD ou WASD, souris, manette, tactile). C'est l'exemple exemples/01-premier-monde.html.

1.4 Les trois portes d'entrée

Et pour essayer sans rien installer : le terrain de jeu (docs/terrain.html, en ligne sur /docs/terrain.html) — du code à gauche, le monde à droite, des exemples, et un lien « Partager » qui contient le code.

Ce qu'on fait par une porte s'ouvre par les deux autres : la Forge enregistre des fichiers .vectra que le code charge avec monde.charger(), et un projet en code s'exporte avec monde.exporter().

2. Comprendre

2.1 Une scène décrite, pas écrite

Dans le moteur, chaque monde est un shader WGSL écrit à la main. Avec le SDK, tu décris ton monde : des formes, des opérations entre elles, des matières, des répétitions. Le SDK en tire, à chaque changement de structure :

1. le WGSL de la scène (le champ de distance, autour d'une « scène gabarit » qui respecte le contrat du moteur) ;
2. le GLSL ES 3.0 pour les appareils sans WebGPU (traduction par naga, embarqué dans vendor/naga-wasm/) ;
3. le même champ en JavaScript, pour le sol, les collisions et la visée.

Une seule description : le sol sur lequel on marche est exactement celui qu'on voit.

2.2 Structure et réglages

C'est la règle la plus utile à connaître :

• Un réglage (bouger, tourner, mettre à l'échelle, changer une taille, une teinte, une rugosité) passe par le bloc auteur, un tableau de paramètres envoyé au GPU à chaque image. Effet immédiat, rien à compiler.
• Un changement de structure (ajouter ou retirer une forme, changer d'opération, changer de matière, ajouter une rotation à un objet qui n'en avait pas) recompile la scène, en tâche de fond. L'image d'avant reste affichée jusqu'à ce que la nouvelle soit prête.

Conseil : si un objet va tourner plus tard, crée-le avec une rotation (.tourner(0) ou l'option { tourne: true } de ajouter). Les entités en ont toujours une.

2.3 Le bloc auteur et sa limite

Avec le moteur 7.9.15, le bloc auteur loge dans la fin du tampon de jeu du moteur, inutilisée : 132 vec4. Chaque matière en prend 2, chaque objet placé 1 (2 s'il tourne), chaque paramètre un quart ou un entier, et chaque groupe « lourd » 1 de plus pour sa sphère englobante. Les exemples en utilisent entre 9 et 112.

Quand le bloc est plein, le SDK ne casse rien : les derniers paramètres sont écrits en dur dans le shader, et les changer recompile. L'événement avertissement le signale. Le moteur 8.4 donnera une liaison à part de 256 vec4.

2.4 Le moteur, une dépendance

Le SDK ne parle au moteur que par un seul fichier, packages/sdk/src/moteur.js (l'adaptateur). Avec le moteur 7.9.15, qui n'a pas encore de porte publique, l'adaptateur fait lui-même ce que la V8 du moteur apportera : assembler les // #import (portage exact de la Forge, vérifié à l'octet sur 33 sorties), loger le bloc auteur, porter la scène gabarit. Ces contournements sont dans packages/sdk/src/provisoire/ et marqués PROVISOIRE : ils disparaîtront lot après lot. monde.infos.provisoire vaut true tant qu'ils servent.

3. L'API

L'API existe en français (vectra.js) et en anglais (vectra.en.js), à égalité : mêmes objets, mêmes méthodes. La correspondance complète est dans la Référence.

3.1 Vectra

Options de creer :

3.2 Construire : ajouter, repeter, entite

const tour = monde.ajouter(sdf.cylindre(1, 8), mat.pierre()).en([0, 4, 0]);
monde.repeter(sdf.cone(0.4, 1.2), { case: 4, densite: 0.6, sur: "sol", graine: "sapins" }, mat.bois());
const orbe = monde.entite({ forme: sdf.sphere(0.5), matiere: mat.lueur("#FF4FD8"), position: [2, 1, 0], avec: [comportements.flotter()] });

• ajouter(forme, matiere?, { tourne? }) → Objet. La matière est propre à l'objet : la régler ne touche pas les autres.
• repeter(forme, { case, densite, hasard, varier, graine, sur }, matiere?) : une forme par case, sans rien stocker. sur: "sol" pose chaque copie sur le premier terrain ou plan ajouté (ou sur un Objet de sol donné).
• entite({ forme, matiere, position, rotation, echelle, rayon, surLeSol, donnees, avec }) → Entite. entites(n, i => définition) en crée plusieurs.

3.3 Les formes : sdf et l'API chaînée

Formes : sdf.sphere, boite, cylindre, tore, capsule, cone, octaedre, plan, terrain, objet, wgsl, union. Pour une capture en gaussiennes 3D, voir monde.splats() (3.13).

Chaque forme se chaîne :

Une opération prend la forme sur laquelle elle est appelée comme premier enfant : a.moins(b) creuse b dans a.

3.4 Les matières : mat

mat.pierre(), bois(), platre(), metal(), verre(), gelee(), lueur(), tissu(), terre(), eau(), mat(), objet(). Options : teinte ("#rrggbb", ou mat.lueur("#F5C542") directement), rugosite, metal, emission, texture. La pierre, le bois, le plâtre, le métal, le tissu et la terre prennent les textures photographiées du moteur (CC0), teintées par la couleur choisie. Le verre, la gelée et l'eau ont leur propre éclairage.

3.5 Objet et Entite

3.6 Le joueur et la caméra

const joueur = monde.joueur({ marche: true, saut: 7.5, vitesse: 4.5, position: [0, 2, 10] });
joueur.position = monde.surLeSol([5, 1.7, 5]);

Le corps a deux sphères (pieds et tête), la gravité, le saut, la course (Maj). Dans une scène décrite, il est repoussé hors du champ de distance ; dans une scène livrée, il suit le sol et les collisions de la scène, comme dans le lecteur. marche: false : vol libre (R et F pour monter, descendre).

Caméra (monde.camera) :

monde.joueur({ lacet }) oriente le joueur au départ (radians ; Math.PI / 2 regarde vers +x).

3.7 Les actions

Les entrées sont ramenées à des actions nommées : avancer, reculer, gauche, droite, sauter, courir, interagir, lanterne, monter, descendre, pause. Les touches sont données par position : la touche W d'un clavier QWERTY est la touche Z d'un AZERTY, sans rien régler.

monde.actions.sur("interagir", () => porte.retirer());
monde.actions.lier("style", ["KeyV"]);          // une action à toi
monde.actions.etat("courir");                    // maintenue ?
monde.actions.capturerSouris();                  // pointeur verrouillé (jeux à la première personne)

Tactile : la moitié gauche de l'écran est un joystick, la droite le regard ; une tape est un clic. Manette : disposition standard.

3.8 Les règles et les événements

monde.quand(joueur).touche(cristaux, (cristal) => cristal.retirer({ effet: "eclat" }));
monde.quand(joueur).entre({ centre: [0, 1, -20], rayon: 3 }, () => monde.ui.message("Le seuil"));
monde.quand(porte).clic(() => porte.cacher());
monde.chaque(1, () => …); monde.apres(10, () => …);
monde.on("image", (dt) => …);

Contacts : touche, quitte ; zones : entre, sort ; clic ; regard : vise(objets, fn, { distance }) — le centre de la vue se pose sur l'un d'eux (une fois par regard) ; chaque(s, fn), apres(s, fn). Chaque règle renvoie de quoi la retirer ; monde.off(nom, fn) retire un écouteur posé par monde.on. Événements de on : pret, premiere-image, image, avant-image, clic (avec { point, distance, objet }), compile, qualite, lanterne, fin, erreur, avertissement, sequence-finie, porte, interrupteur, collecte, collecte-finie.

Une erreur dans ton code n'arrête jamais le monde : elle est attrapée, signalée par l'événement erreur (une ErreurVectra qui donne la ligne), et le reste continue. Une règle ou un comportement fautif trois fois est coupé (avec un avertissement).

3.9 Les comportements

comportements.tourner, flotter, patrouiller, orbiter, suivre, fuir, troupeau, pulser, minuterie, et pour les jeux :

const porte = monde.entite({ forme: sdf.boite([3, 3, 0.4]), matiere: mat.bois(), position: [0, 1.5, -10], avec: [comportements.porte()] });
monde.entite({ forme: sdf.cylindre(0.4, 0.3), matiere: mat.metal(), position: [3, 0.15, -6], avec: [comportements.interrupteur({ cible: porte })] });
monde.entites(5, (i) => ({ forme: sdf.octaedre(0.5), matiere: mat.lueur("#F5C542"), position: [i * 2 - 4, 1, -3], avec: [comportements.collecte({ compteur: "Cristaux", total: 5 })] }));
monde.on("collecte-finie", () => monde.fin("Bravo !"));

Signatures complètes dans la Référence. Un comportement est un objet { nom, attacher?(entite, monde), maj(entite, dt, monde, t) } : tu peux écrire les tiens. Trois jeux complets n'utilisent que cette API : exemples/02-jeu-collecte.html, 09-course.html (anneaux dans l'ordre, compte à rebours), 10-enigme.html (trois leviers, une porte, une clé).

3.10 L'interface de jeu

monde.ui.compteur(nom, valeur, max?), monde.ui.minuterie(nom, secondes, fin), monde.ui.message(texte, secondes), monde.fin(titre, { texte, rejouer }), monde.ui.effacer(). Du HTML par-dessus l'image, aux couleurs TRUvector, lisible par les lecteurs d'écran.

3.11 Styles, lumière, son, ancres

• await monde.style("manga", { transition: "onde", intensite, reglages }) ; "aucun" retire le style ; await monde.styles() liste les 22 styles du moteur.
• monde.heure(0.75, meteo) ou monde.heure(18) : le monde vivant du moteur (heure du jour en fraction ou en heures, météo) ; monde.heure(null) : figé.
• monde.lanterne() (touche L), monde.son(true, { musique }) : musique générée du moteur (après un geste de l'utilisateur).
• monde.ancrer(element, cible, { decalage }) : un élément HTML suit un objet ou un point.
• await monde.capture() : une image PNG (même en pause).
• monde.pause(), monde.reprendre(), monde.detruire() : arrêter le rendu, le relancer, tout libérer.

3.12 Les scènes livrées

Vectra.creer("#ecran", { scene: "plaine" }) monte une scène du moteur : organismes, cathedrale, abysse, aurore, atelier, genese, maison, plaine, ville. On y marche (monde.joueur()), on y change de style, on y pose des règles de zones et une interface. On ne peut pas y ajouter de formes avec le moteur 7.9.15 (leur shader est fermé) : pour un monde à toi, pars d'une scène décrite (un sdf.terrain, par exemple).

3.13 Les objets importés

const avocat = await monde.objet("avocat.vobj");             // livré avec le moteur
monde.ajouter(avocat, mat.objet()).echelle(1.6).en([0, 0.8, 0]);
const mien = await monde.objet(fichierGlb);                   // un .glb à toi, converti dans le navigateur

monde.objet() accepte un nom de web/objets/ du moteur (avocat.vobj, bouteille.vobj), un .vobj, ou un .glb (glTF 2.0 binaire) qu'il convertit en champ de distance dans un Worker (la page ne gèle pas). mat.objet() reprend les couleurs du modèle (texture comprise). Avec le moteur 7.9.15, un seul objet importé par scène.

Splats (gaussiennes 3D, lot 0.7) : const n = await monde.splats("flacon-splats.vspl", { en: [0, 1, -3], echelle: 1.5, rotation: 30, opacite: 1 }) pose un nuage de splats — un .vspl livré par le moteur, ou un .ply / .spz / .vspl à toi (File, ArrayBuffer) — dessiné par le rendu de splats du moteur après la scène, caché par ce qui est devant lui. Le résultat se déplace (n.en(p), n.tourner(deg), n.echelle(s), n.opacite(v)) et se retire (await n.retirer()). Un nuage par monde ; visuel seulement (pour des collisions, pose une forme simple à sa place).

Un objet importé voyage avec le projet : monde.exporter() range ses octets .vobj (en base64) dans projet.objets, et monde.charger() les relit ; un objet livré par le moteur se recharge simplement par son nom.

3.14 Les projets .vectra

monde.exporter({ nom, script, sequence }) renvoie un projet (format: "vectra-projet", version: 1) : graphe, ciel, style, caméra, joueur, script, langage ("js" ou "ts") et objets (les objets importés). await monde.charger(projet) le recharge, et exécute son script. Qui modifie monde.graphe à la main (comme la Forge) prévient le monde par monde.majGraphe({ structure }). await monde.executer(code) exécute un script d'auteur : il reçoit monde, sdf, mat, comportements, Vectra (et world, behaviours).

Scripts en TypeScript. monde.executer(code, nom, { typescript: true }) — ou un script dont la première ligne est // @ts, ou un nom en .ts — retire d'abord les types, comme le fait Node 22 : le JavaScript restant s'exécute tel quel, aux mêmes lignes (les erreurs pointent la bonne ligne). Sont retirés : annotations de variables, de paramètres (x?: T compris) et de retours, as T, satisfies T, x!, interface, type X = …, declare, génériques des fonctions déclarées, import type, modificateurs de classe (private, readonly…). Comme Node, enum, namespace, paramètres promus et décorateurs sont refusés avec un message clair. Il n'y a pas de vérification des types : pour cela, ton éditeur et les déclarations de npm run types.

// @ts
interface Score { points: number }
const s: Score = { points: 0 };
monde.quand(joueur).touche(cristal, (c: Entite) => { s.points++; c.retirer(); });

3.15 Le multijoueur

const salon = await monde.reseau.salon({ api: "https://vectra.truvector.net", salon: "PRJ-K7M2QX9A", nom: "Ana" });
salon.sur("arrivee", (j) => monde.ui.message(`${j.nom} arrive`));
salon.partager("porte", "ouverte"); salon.score(42); salon.evenement("tir", { x: 1 });

Chaque joueur envoie sa position dix fois par seconde ; les autres apparaissent comme des silhouettes lumineuses, lissées. Le salon (un Durable Object par nom) relaie aussi un état partagé, des événements et un classement. joueurs: 8 fixe la taille du salon (seize au plus) ; le suivant est refusé.

Entités partagées (lot 0.10) : salon.partagerEntite(entite, { cle }) — sa position et sa rotation partent vingt fois par seconde de chez son propriétaire, et les autres la suivent, lissée. Le salon fait autorité : le premier qui l'annonce la possède, les mises à jour des autres sont refusées ; salon.prendre(entite) la reprend (on la pousse), salon.lacher(entite) la libère, salon.possede(entite) le dit ; un joueur qui part libère les siennes. Une entité retirée (ramassée) l'est pour tous. Voir la balle de exemples/07-multijoueur.html.

3.16 Interroger le monde

monde.distance(p), monde.solSous(x, z), monde.surLeSol([x, y, z]), monde.viser(u, v) (rayon depuis la caméra), monde.hasard(graine) (.suivant(), .entre(a, b), .disque(r), .choisir(liste)), monde.infos.

monde.infos dit aussi où la traduction WebGL2 s'est faite (glsl: "worker" : dans un Worker, la page ne gèle pas). await monde.sonder([[x, y, z], …]) (anglais : probe) demande à la carte graphique la distance et la normale en 8 points au plus : [{ distance, normale }], une à deux images plus tard. Elle voit exactement ce que le rayon voit, nœud WGSL libre compris. Elle passe par la sonde cs_probe du moteur : WebGPU seulement (en WebGL2, ou dans une scène livrée, elle renvoie null).

4. Le graphe de scène

Le format graphe.v1 est ce que la Forge enregistre et ce que l'API chaînée écrit :

{
  "format": "vectra-graphe", "version": 1,
  "noeuds": {
    "n1": { "type": "terrain", "p": { "relief": 4 }, "matiere": "m1" },
    "n2": { "type": "sphere", "p": { "rayon": 3 }, "en": [0, 10, 0] },
    "n3": { "type": "fondre", "p": { "k": 0.8 }, "enfants": ["n4", "n2"] }
  },
  "racine": ["n1", "n3"],
  "matieres": { "m1": { "base": "pierre" } }
}

Règles : chaque nœud a au plus un parent ; les racines forment une union ; une matière s'hérite du parent ; un seul objet importé par graphe (moteur 7.9.15). npx vectra verifier fichier.vectra valide un fichier ; les erreurs nomment le nœud, en français et en anglais.

Le compilateur (packages/graphe/src/compiler.js) : valide, sépare la structure des paramètres (l'empreinte de la structure décide s'il faut recompiler), calcule les boîtes englobantes et les facteurs de sûreté des déformations, range les paramètres dans le bloc auteur (placements d'abord, puis sphères englobantes, puis paramètres de forme), puis émet le WGSL et l'évaluation JavaScript. Les enfants « lourds » d'une union sont élagués par leur sphère englobante : le rayon ne les calcule que s'il passe près. L'évaluation JavaScript élague exactement de la même façon : la sonde GPU et le JavaScript s'accordent à mieux que 1 mm (contrôlé sur 1 000 points près des surfaces, toutes sortes de nœuds).

Le nœud WGSL libre (sdf.wgsl(code, borne)) prend du code d'expert (il reçoit p et renvoie une distance). Une erreur dans ce code est ramenée au nœud et à la ligne de l'auteur (erreur wgsl-libre : « WGSL libre « Mon champ », ligne 2 : unresolved call target 'lenght' »), et l'image d'avant reste affichée. Il n'a pas d'équivalent JavaScript : pour les collisions du joueur, le SDK interroge alors la sonde GPU du moteur à chaque image (pieds, tête, sol juste dessous, un pas en avant) et corrige le champ JavaScript avec ce qu'elle voit. Le joueur attend que la sonde ait vu la scène compilée avant de tomber. WebGPU seulement : en WebGL2 le joueur traverse encore ces formes. Voir exemples/08-wgsl-libre.html.

5. La Forge en ligne

packages/forge-web/index.html. Elle est écrite avec le SDK et n'utilise que son API publique.

• Scène (à gauche) : l'arbre des nœuds. « Ajouter… » : une forme s'ajoute devant la caméra, posée sur le sol ; une opération, un modificateur ou une répétition enveloppe la sélection. La croix supprime. La jauge de coût estime ce que le rayon doit calculer (vert, orange, rouge, avec un conseil au survol).
• Vue (au centre) : glisser pour regarder, ZQSD/WASD pour bouger, R/F pour monter/descendre. Un clic sur un objet le choisit ; Maj+clic pose la sélection là où l'on clique. Le cadre pointillé montre la sélection.
• Poignées 3D : sur la sélection, trois flèches (X rose, Y or, Z cyan) et un disque. Glisser une flèche déplace l'objet le long de son axe ; glisser le disque le déplace sur le plan horizontal. Maj pendant le geste : pas de 50 cm. Rien n'est recompilé pendant le geste (bloc auteur), et le geste entier s'annule d'un seul Ctrl+Z.
• Inspecteur (à droite) : nom, placement, paramètres de la forme, matière (sorte, teinte, rugosité, métal, émission). Les réglages sont immédiats ; ce qui change la structure recompile.
• Code (en bas) : le script du projet dans CodeMirror 6 (coloration, complétion tirée de l'API : monde., sdf., mat., comportements.…), exécuté par Jouer ; la case TypeScript retire les types avant l'exécution. ＋ Bibliothèque… insère des morceaux prêts : comportements (porte et interrupteur, plaque de pression, objets à ramasser, troupeau…), règles (touche, entre, vise), interface, caméra, ambiance.
• Piste : la piste de temps de la caméra. « ＋ Clé » garde la vue actuelle à un instant ; on glisse les clés sur la frise, on leur donne une légende, « ▶ Lire » joue la mise en scène. « Au démarrage » : le projet exporté ou publié commence par elle, puis rend la main au joueur.
• Coût par nœud : une pastille verte, or ou rouge sur chaque nœud de l'arbre, et des conseils sous la jauge (« 6 sphères identiques : répète-les par case », WGSL libre sans borne, fondus à trop d'enfants, arbre trop profond…). Jouer met un joueur dans le monde ; Arrêter remet la scène telle qu'elle était. Journal : compilations, erreurs avec leur ligne.
• Fichier : Nouveau, Ouvrir, Enregistrer (.vectra). Sauvegarde automatique dans IndexedDB toutes les 10 secondes (et en quittant la page), objets importés compris ; repli sur localStorage. Annuler / Refaire : 100 niveaux (Ctrl+Z, Ctrl+Maj+Z).
• ＋ Objet .glb (importer un objet) : un .glb (ou .vobj), converti dans le navigateur (un Worker, la page ne gèle pas ; progression affichée), posé devant la caméra avec mat.objet(). Un seul objet importé par scène (moteur 7.9.15) : un deuxième remplace le premier. L'objet est enregistré dans le .vectra.
• Exporter .zip : un dossier de projet complet, prêt à devenir un dépôt GitHub privé — index.html, jeu.js (qui ouvre projet.vectra), projet.vectra, vectra.json, README.md, .gitignore, le SDK dans vectra/, et .github/workflows/deployer.yml (Cloudflare Pages). Le moteur n'y est pas : le déploiement le récupère à la version testée. C'est exactement ce que donne vectra nouveau mon-jeu --depuis monde.vectra. Le README du dossier donne les trois commandes (git init, gh repo create --private, secrets).
• GitHub ▸ : crée un dépôt sur ton compte GitHub (privé par défaut) et y pousse le projet complet en un commit — le même dossier que l'export .zip, déploiement Cloudflare compris. Connexion par « Se connecter avec GitHub » (le Worker, droits repo et workflow) ou par un jeton personnel collé dans la boîte ; le jeton ne quitte le navigateur que vers api.github.com, et n'est gardé que pour l'onglet.
• Publier : crée un compte anonyme (jeton gardé sur l'appareil), envoie le projet au service, et donne un lien public et une balise <vectra-monde>.

6. La balise <vectra-monde>

<script type="module" src="https://vectra.truvector.net/sdk/0/element.js"></script>
<vectra-monde scene="plaine" data-style="manga" joueur></vectra-monde>
<vectra-monde projet="https://p.truvector.net/p/PRJ-K7M2QX9A.vectra" joueur></vectra-monde>

Attributs : scene, projet, ciel, data-style (style est déjà un attribut HTML), graine, qualite, joueur, orbite, rendu, langue, moteur. Événements DOM : vectra-pret (avec le monde), vectra-erreur.

7. L'outil en ligne de commande

Noms anglais : new, check, build, publish, engine, help.

Les gabarits

Chaque gabarit porte .github/workflows/deployer.yml : à chaque poussée sur main, il récupère le moteur (dépôt privé, jeton MOTEUR_LECTURE) à la version de vectra.json, et déploie sur Cloudflare Pages.

8. Le nuage : Cloudflare

Le Worker vectra-projets (api/) est séparé de vectra-api du moteur, qui ne change pas. Tout tient dans l'offre gratuite.

Garde-fous : projets de 8 Mo au plus (objets importés compris ; TAILLE_MAX), noms et contenu des objets embarqués vérifiés, 60 envois par heure et par compte, état des salons assaini (nombres, textes courts), ménage quotidien. Les projets publiés vivent sur une adresse à part (p.truvector.net) : le code d'un auteur ne tourne jamais là où les gens se connectent à la Forge. Le site et l'API partagent vectra.truvector.net (le Worker y prend /api/*).

Mettre en route :

cd api
npx wrangler d1 create vectra-projets          # recopier l'identifiant dans wrangler.toml
npx wrangler d1 execute vectra-projets --file=schema.sql
npx wrangler r2 bucket create vectra-projets
npx wrangler deploy

En local : npx wrangler d1 execute vectra-projets --local --file=schema.sql puis npx wrangler dev --local.

Le CDN (vectra.truvector.net) reçoit npm run construire : dist/sdk/<version>/ (figé, avec le moteur exact testé) et dist/sdk/<majeure>/ (la dernière). Une page publiée ne change jamais d'elle-même.

8.1 Mettre en production : le dossier web/

npm run web produit web/, un dossier autonome à pousser tel quel dans un dépôt GitHub privé (par exemple truvector/vectra-web). Rien n'y est compilé : tout est déjà construit et contrôlé ici.

Un seul domaine pour le site et l'API (vectra.…), donc la Forge publie sur /api sans réglage ; les projets publiés restent sur leur adresse séparée (p.…). Ce dépôt n'a pas besoin du jeton du moteur (MOTEUR_LECTURE) : le moteur testé est déjà dans site/. C'est aussi pourquoi il doit rester privé.

Autres adresses : npm run web -- --domaine mondomaine.fr --sous-domaine vectra --publication p --projet-pages vectra-web. Mettre à jour : npm run web, puis recopier web/ dans le dépôt de production (en gardant son .git/) et pousser. npm run test:navigateur contrôle aussi web/site (accueil et ses liens, manuel, exemple, Forge, /sdk/<majeure>/element.js dans une page tierce).

9. GitHub et la mise à jour du moteur

Les deux dépôts sont privés, et rien ne passe par npm (décision TRUvector).

Secrets : MOTEUR_LECTURE (lecture seule de truvector/vectra), CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID. Le dépôt du moteur doit porter une étiquette par version (v7.9.15) et, quand il publiera (lot 8.8), envoyer un repository_dispatch « moteur-publie » à vectra-sdk.

Ce qui se passe quand le moteur change : un correctif ou un ajout (style, scène, lumière) arrive sans rien toucher ; un nouvel export s'utilise quand on veut ; un changement de contrat (majeure) est refusé par la plage ^8 jusqu'à adaptation. Au démarrage, l'adaptateur vérifie le numéro de contrat du moteur et refuse, avec un message clair, un moteur incompatible.

10. Dans le détail

10.1 Performances

Dans un moteur à champs de distance, chaque forme coûte à chaque pas de chaque rayon. Ce qui aide : répéter (repeter, grille, anneau : une copie coûte comme une forme) plutôt que dupliquer ; regrouper des formes proches sous une union (elle est élaguée par sa sphère englobante) ; éviter les grandes fondre à beaucoup d'enfants. La jauge de la Forge guide ; la qualité automatique et la résolution dynamique du moteur font le reste.

10.2 Sans WebGPU

Le SDK assemble la scène en variante WebGL2 du moteur et la traduit en GLSL ES 3.0 avec naga-wasm 30.2.0 (copie embarquée dans vendor/naga-wasm/ ; à défaut, le CDN jsDelivr, version épinglée). La sortie est identique, à l'octet, à celle de naga-cli avec les mêmes options (--keep-coordinate-space --profile es300) ; la Forge du moteur ajoute --compact, que naga-wasm ne sait pas faire : son GLSL est 5 à 10 % plus court, le nôtre garde quelques fonctions inutilisées, sans effet sur l'image. La traduction se fait dans un Worker (la page ne gèle pas pendant une recompilation), avec repli sur la page si le Worker ne démarre pas. Le moteur 8.3 apportera son propre naga en WebAssembly ; l'adaptateur s'en servira à la place.

10.3 Les erreurs

Toutes les erreurs du SDK sont des ErreurVectra : code, message (dans la langue choisie), fr, en, details. Codes : contrat, bibliotheque, shader, wgsl-libre (avec details.noeud, nom, ligne), glsl, webgl2-graphe, rendu, scene, cible, style, capacite, script, detruit, rv.

10.4 Les tests

npm test                    # contrôles unitaires (graphe, WGSL, assembleur, lexique, contrat, API, actifs, TypeScript, export, GitHub)
npm run construire          # dist/, nécessaire au contrôle du CDN
npm run test:navigateur     # exemples, gabarits, Forge, CDN, web/, API du monde, documentation, nuage, salon à 8 (≈ 45 min en logiciel)

Les contrôles de la chaîne (tests/unites/contrat.test.js) refusent tout import du moteur hors de l'adaptateur, toute méthode publique sans alias anglais ou sans place dans ce manuel, et un cœur du SDK de plus de 150 Ko compressés. tests/navigateur/docs.mjs exécute chaque exemple du terrain de jeu et chaque bloc de code JavaScript / TypeScript de ce manuel.

Les contrôles navigateur utilisent Chromium sans carte graphique (SwiftShader) : lent mais fidèle. CHROMIUM=<chemin> choisit l'exécutable ; CAPTURES=<dossier> garde des images. Le contrôle du nuage demande le Worker en local (VECTRA_API, par défaut http://127.0.0.1:8787) et s'ignore sinon.

11. La feuille de route, lot par lot

Dit franchement. « Fait » veut dire écrit et contrôlé dans la chaîne ; « moteur 8 » : attend un lot du moteur (le contournement provisoire est en place quand il existe) ; « à mesurer » : demande du vrai matériel ou de vraies personnes.

Et toujours : réalité virtuelle depuis le SDK non (monde.rv.entrer() lève une erreur claire ; noyau séparé du moteur, 8.6) ; formes dans une scène livrée non ; un seul objet importé et un seul nuage de splats par scène (liaisons du moteur 7.9.15) ; textures glTF sous Node : couleur de base seule.

12. Compatibilité

La même table est publiée avec le site (/version.json, champ compatibilite). Promesse visée pour la 1.0 : rien ne casse dans la 1.x, et toute 1.x marche avec tout moteur 8.x.

13. Glossaire

• Champ de distance : fonction qui donne, pour tout point, la distance à la surface la plus proche. VECTRA dessine en marchant le long des rayons avec elle.
• Graphe : la description d'une scène (nœuds, matières, racines).
• Bloc auteur : le tableau de paramètres de la scène, envoyé au GPU à chaque image.
• Empreinte : résumé de la structure du graphe ; si elle ne change pas, le shader non plus.
• Contrat : ce que le moteur promet au SDK (porte publique, liaisons, formats). Numéro actuel : 1.
• Adaptateur : packages/sdk/src/moteur.js, le seul fichier qui parle au moteur.
• Scène livrée : une scène du moteur (la Plaine, la Ville…), écrite à la main.
• Scène décrite : une scène faite avec le SDK.

Référence

Produite par node outils/doc-reference.mjs à partir du code : elle suit l'API exactement.

Les nœuds du graphe

Chaque nœud a un type, des paramètres (p), des enfants (enfants), et peut avoir un placement (en, rot en degrés, echelle), une matiere et un nom. Un paramètre marqué structure recompile le shader quand il change ; les autres se règlent sans recompiler.

Formes

Opérations

Modificateurs

Répétitions

Constructeurs de l'API chaînée : sdf.sphere(rayon), sdf.boite(taille, arrondi), sdf.cylindre(rayon, hauteur), sdf.tore(rayon, epaisseur), sdf.capsule(rayon, hauteur), sdf.cone(rayon, hauteur), sdf.octaedre(rayon), sdf.plan(hauteur), sdf.terrain({ taille, relief, echelle, graine }), sdf.wgsl(code, borne), sdf.objet(fichier), sdf.union(...formes).

En anglais : sdf.sphere, sdf.box, sdf.cylinder, sdf.torus, sdf.capsule, sdf.cone, sdf.octahedron, sdf.plane, sdf.terrain, sdf.wgsl, sdf.object.

Les matières

mat.<sorte>(options) : teinte (couleur CSS « #rrggbb » ; en anglais tint), rugosite (roughness), metal, emission, texture (vrai/faux : texture photographiée du moteur).

Les comportements

Les ciels

Alias anglais : day, blue-hour, dawn, night.

Les scènes livrées montables par le SDK (moteur 7.9.15)

organismes, cathedrale, abysse, aurore, atelier, genese, maison, plaine, ville. Les Arches (briques en flux) et la photo en relief demandent des données que le SDK ne fournit pas encore.

Les actions et leurs touches par défaut

Touches données par position (KeyboardEvent.code) : KeyW est Z sur un clavier AZERTY.

Lexique : méthodes françaises → anglaises

Monde

Camera

Objet

Entite

InterfaceJeu

Forme

Lexique : options anglaises → françaises