ali-ali18/agent-skills

Développement Roblox avec Rojo (Luau)

Vous construisez des expériences Roblox sous forme de fichiers plats dans la VM, les compilez en un fichier de lieu avec Rojo et, uniquement lorsque demandé, téléchargez ce fichier vers un lieu de TEST via Roblox Open Cloud. Répondez à l'utilisateur dans sa langue (pt-BR par défaut).

0. Règles de base

• N'imprimez, n'affichez, ne journalisez et n'écrivez jamais une clé API. Utilisez uniquement le marqueur de coffre {{secret:<nom>}} dans un appel shell ; l'exécution échange la valeur et la masque dans la sortie.
• Publiez UNIQUEMENT vers le lieu de test que l'utilisateur vous a donné (universeId + placeId). Ne devinez jamais les identifiants et ne réutilisez jamais d'identifiants d'une autre conversation. Si l'utilisateur donne un lieu en direct/de production, arrêtez-vous et confirmez l'intention.
• Par défaut, versionType est Saved (une nouvelle version dans l'historique des versions, pas en direct). Utilisez Published uniquement lorsque l'utilisateur demande explicitement de passer en direct.
• UniverseId, placeId ou nom de secret manquants ? Demandez avec propose_questionnaire (un formulaire court). Secret totalement manquant ? Appelez secret_request (nom suggéré : ROBLOX_API_KEY). Ne demandez jamais la clé dans le chat.

1. Installer Rojo (une fois par VM)

Version épinglée : Rojo 7.7.1 (vérifiez https://github.com/rojo-rbx/rojo/releases pour les versions 7.x plus récentes et informez l'utilisateur avant de changer l'épingle). Installez le binaire Linux x86_64 précompilé dans le dossier personnel, pas besoin de root :

mkdir -p "$HOME/.local/bin" && cd "$(mktemp -d)"
curl -fsSL -o rojo.zip https://github.com/rojo-rbx/rojo/releases/download/v7.7.1/rojo-7.7.1-linux-x86_64.zip
unzip -o rojo.zip && install -m 0755 rojo "$HOME/.local/bin/rojo"
export PATH="$HOME/.local/bin:$PATH"
rojo --version   # attendu : rojo 7.7.1

Vérifiez d'abord avec command -v rojo ; ignorez l'installation si elle affiche déjà 7.x. Sur une VM ARM, utilisez la ressource linux-aarch64. Alternative lorsqu'un gestionnaire de chaîne d'outils est déjà présent : rokit add rojo-rbx/rojo && rokit install. N'exécutez pas d'installateurs depuis d'autres URL.

2. Structure du projet

mon-jeu/
  default.project.json
  src/
    server/     -> ServerScriptService.Server   (code serveur uniquement)
    client/     -> StarterPlayer.StarterPlayerScripts.Client
    shared/     -> ReplicatedStorage.Shared      (modules requis par les deux côtés)

default.project.json :

{
  "name": "mon-jeu",
  "tree": {
    "$className": "DataModel",
    "ServerScriptService": { "Server": { "$path": "src/server" } },
    "ReplicatedStorage": { "Shared": { "$path": "src/shared" } },
    "StarterPlayer": {
      "$className": "StarterPlayer",
      "StarterPlayerScripts": { "Client": { "$path": "src/client" } }
    }
  }
}

Nommage de fichiers compris par Rojo : init.server.luau (un Script pour le dossier), *.server.luau (Script), *.client.luau (LocalScript), *.luau simple (ModuleScript), init.luau (le dossier devient un ModuleScript). Ajoutez un .gitignore avec *.rbxl, *.rbxlx, Packages/. Créez le projet uniquement lorsque le dossier n'a pas de default.project.json ; ne remplacez jamais une structure existante, adaptez-vous-y.

3. Conventions de codage

• Luau avec --!strict en haut de chaque fichier. Typez les signatures de fonctions et les tables exportées.
• Une responsabilité par ModuleScript, retournant une table. Pas de variables globales, pas de _G, pas de shared. Utilisez require avec des références directes (script.Parent.Module ou ReplicatedStorage.Shared.Module).
• Gardez les points d'entrée petits : un init.server.luau et un point d'entrée client qui require les services/contrôleurs et les démarre dans l'ordre.
• Récupérez les services en haut : local Players = game:GetService("Players"). Préférez task.wait, task.spawn, task.delay à wait/spawn/delay. Déconnectez les connexions par joueur sur Players.PlayerRemoving.
• Ne faites jamais confiance au client. Le serveur possède l'état du jeu (monnaie, inventaire, dégâts, téléportations, progression). Le client envoie uniquement l'intention et affiche les résultats.

Checklist de sécurité des remotes

• Créez des instances RemoteEvent/RemoteFunction sous ReplicatedStorage depuis le serveur avec un nom fixe ; ne les créez jamais depuis le client.
• Sur chaque OnServerEvent/OnServerInvoke : validez le nombre et les types d'arguments (typeof), limitez les plages, rejetez NaN/inf, limitez la longueur des chaînes, vérifiez que le joueur est autorisé (temps de recharge, propriété, distance, vivant).
• Limitez le débit par joueur (seau à jetons ou horodatage du dernier appel). Une remote ne doit jamais transporter un prix, un montant de dégâts ou une valeur que le client pourrait choisir à son avantage.
• RemoteFunction : n'utilisez jamais InvokeClient (un client malveillant peut bloquer le thread du serveur).
• DataStore : enveloppez dans pcall, réessayez avec backoff, sauvegardez sur PlayerRemoving et game:BindToClose ; verrouillez les données précieuses par session.
• Les secrets et les boutons de réglage se trouvent uniquement dans ServerScriptService/ServerStorage, jamais dans ReplicatedStorage.

4. Construction

rojo build default.project.json -o place.rbxl
ls -l place.rbxl

Corrigez d'abord les erreurs de construction ($path manquant, JSON mal formé, noms en double). Ne committez pas place.rbxl. selene / stylua --check sont facultatifs ; ne les installez pas sauf demande. Un lieu construit à partir de fichiers uniquement est un squelette de script : les assets, le terrain et l'interface utilisateur créés dans Studio vivent dans le lieu existant, donc le téléchargement REMPLACE le contenu de la version cible. C'est exactement pourquoi la cible doit être un lieu de test.

5. Publication via Open Cloud (lieu de test)

Point de terminaison (Roblox Open Cloud Place Publishing, univers v1) :

POST https://apis.roblox.com/universes/v1/{universeId}/places/{placeId}/versions?versionType=Saved|Published

• En-tête x-api-key: <clé> ; Content-Type: application/octet-stream pour .rbxl (binaire), application/xml pour .rbxlx.
• Corps : le fichier de lieu brut. Réponse de succès : { "versionNumber": 7 }.
• La clé API nécessite la permission universe-places avec Écriture sur l'expérience cible (créée dans le Tableau de bord du créateur).
• HTTPS uniquement. L'API ne met pas à jour certains types d'instances (EditableImage, EditableMesh, PartOperation, SurfaceAppearance, BaseWrap) : dites à l'utilisateur de publier ceux-ci depuis Studio.
• Docs : https://create.roblox.com/docs/en-us/cloud/guides/usage-place-publishing

Exécutez-le avec le marqueur de coffre (le marqueur va à l'intérieur de la commande shell, jamais dans votre texte de message) :

curl -sS -X POST \
  "https://apis.roblox.com/universes/v1/$UNIVERSE_ID/places/$PLACE_ID/versions?versionType=Saved" \
  -H "x-api-key: {{secret:ROBLOX_API_KEY}}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @place.rbxl

Remplacez $UNIVERSE_ID et $PLACE_ID par les nombres donnés par l'utilisateur, et le nom du secret par le vrai nom du coffre (secret_list montre uniquement les noms). Gérez les erreurs sans exposer la clé : 401/403 = clé invalide ou permission/expérience manquante ; 404 = mauvaise paire univers/lieu ; 400 = fichier incorrect (reconstruisez) ; 429 = attendez et réessayez une fois. Citez uniquement le statut HTTP et le corps de la réponse, qui ne contient jamais la clé.

6. Rapport

Terminez chaque tâche par un court rapport dans la langue de l'utilisateur :

1. Ce qui a changé (fichiers et comportement), en termes simples.
2. Le résultat de rojo build et, si publié, le versionNumber, le versionType utilisé et le fait que cela soit allé vers le lieu de test <placeId>.
3. Comment tester dans Studio : ouvrez le lieu de test, ouvrez l'Historique des versions pour charger la nouvelle version Saved, appuyez sur Lecture (F5), et les choses exactes à essayer avec les messages de sortie attendus.
4. Ce que vous n'avez PAS fait (publication en direct, assets ou terrain nécessitant Studio).

7. Option de synchronisation locale

Pour une édition en direct, l'utilisateur peut exécuter rojo serve sur son propre ordinateur avec le plugin Rojo Studio (https://rojo.space/docs/v7/getting-started/installation/). La VM n'est pas accessible depuis son Studio, donc dans la VM, restez avec la construction et le téléchargement via Open Cloud.