CrownStudio Roblox TS Template

Template Roblox TypeScript avec Flamework, Rojo et une sélection de bibliothèques prêtes à importer. Les versions exactes sont dans package.json, pnpm-lock.yaml, rokit.toml et mise.toml. Pour un agent, ces fichiers et les statuts ci-dessous sont la source de vérité : une référence dans ce README ne signifie pas qu'une fonction de jeu est déjà implémentée.

Démarrage

Sous Windows 10/11, lancer depuis le dépôt :

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1

$paths = @(
  "$env:LOCALAPPDATA\mise\installs\pnpm\11.21.0"
  "$env:USERPROFILE\.rokit\bin"
)

$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
$newPath = (($userPath -split ";" ) + $paths | Where-Object { $_ } | Select-Object -Unique) -join ";"

[Environment]::SetEnvironmentVariable("Path", $newPath, "User")
$env:Path = "$($paths -join ';');$env:Path"

pnpm --version
rokit --version

Le script d'installation nécessite WinGet (App Installer du Microsoft Store). Il installe Git, mise, Rokit, Roblox Studio et Blender via WinGet, puis les versions définies dans mise.toml et rokit.toml, et les dépendances pnpm verrouillées. Il termine par pnpm check et pnpm build et s'arrête dès qu'une commande échoue. Windows peut demander une élévation pour certains installateurs. Une relance conserve les applications déjà installées ; elle ne les met pas à jour automatiquement. Les applications WinGet utilisent la version disponible dans son catalogue, les outils du projet restent épinglés.

Configuration complète dans Ubuntu WSL2

Depuis un terminal Ubuntu WSL2, lancer :

bash scripts/setup.sh

Comme setup.ps1 sous Windows, ce script prépare le projet entier. Il installe les paquets Ubuntu nécessaires, mise, Node.js avec npm, pnpm et uv aux versions de mise.toml, Rokit et les outils de rokit.toml, puis les dépendances pnpm verrouillées. Il termine par pnpm check et pnpm build ; bash scripts/setup.sh --skip-checks saute ces deux dernières vérifications. Il peut demander le mot de passe sudo pour les paquets Ubuntu.

Il installe aussi Blender 5.2.2 LTS pour Linux dans ~/.local/opt/blender-5.2.2, vérifie l'archive avec le SHA-256 publié par Blender, exécute un test Python sans interface, puis crée ~/.local/bin/blender. Une relance réutilise les installations existantes. Il ne modifie pas les installations Windows ; Roblox Studio reste sur Windows pour tester le jeu. Pour de meilleures performances, placer le dépôt dans le système de fichiers Linux d'Ubuntu plutôt que sous /mnt/c ou /mnt/e. Rouvrir le terminal Ubuntu après la première installation pour charger les chemins de Rokit. Les commandes du projet sont disponibles via ~/.local/bin/mise exec -- pnpm <commande>.

Pour exécuter un script de création ou d'export d'asset sans ouvrir Blender :

~/.local/bin/blender --background --factory-startup --python-exit-code 1 --python path/to/asset_script.py

La connexion du plugin Blender MCP décrite plus bas concerne une session Blender ouverte. Les scripts Python lancés en mode --background n'en ont pas besoin.

Bibliothèques installées

Chaque paquet de cette section est une dépendance directe. Les liens mènent à la documentation du projet ou à son README actuel ; les versions exécutables sont épinglées dans le lockfile. Les 22 bibliothèques ont été examinées : Flamework, son gestionnaire de composants, Cmdr et le logger sont branchés au démarrage ; les autres bibliothèques s'utilisent à l'import ou se configurent avec les données de leur fonctionnalité.

Console Cmdr : en mode Play dans Studio, ouvrir avec F2. Les commandes intégrées sont enregistrées et protégées côté serveur. Hors Studio, seuls le propriétaire individuel de l'expérience et les UserIds renseignés dans cmdr-permissions.ts sont autorisés. Pour une expérience de groupe, renseigner les administrateurs explicitement. pnpm test:cmdr vérifie cette politique ; ce test fait aussi partie de pnpm check. La configuration client est dans cmdr-controller.ts.

• @flamework/core (documentation) — services, contrôleurs et injection ; le service de démarrage en donne un exemple.
• @flamework/components (documentation) — composants d'instances.
• @flamework/networking (documentation) — réseau typé.
• @rbxts/react (documentation React Lua, liaison roblox-ts) — interface React.
• @rbxts/react-roblox (documentation ReactRoblox, liaison roblox-ts) — rendu React dans Roblox.
• @rbxts/reflex (documentation) — état applicatif.
• @rbxts/ripple (README et API) — animations.
• @rbxts/services (README) — accès typé aux services Roblox.
• @rbxts/lapis (documentation) — persistance de données.
• @rbxts/trove (README et API) — nettoyage des ressources.
• @rbxts/log (README) — journalisation.
• @rbxts/sift (documentation) — collections immuables
• @rbxts/t (README et API) — validation de valeurs à l'exécution.
• @rbxts/cmdr (documentation, types roblox-ts) — commandes de développement.
• @rbxts/gamejoy (README) — contrôles de jeu.
• @rbxts/tween (README et API) — interpolations.
• @rbxts/timer (README) — temporisation.
• @rbxts/ui-labs (documentation) — prévisualisation d'interface.
• @rbxts/sound-manager (documentation du projet) — gestion des sons
• @rbxts/object-cache (documentation amont) — cache de pièces/objets
• @rbxts/net (README) — contient ExperienceBroadcastEvent pour les messages entre serveurs.
• @rbxts-js/roblox-lua-promise (README) — implémentation de promesses

Pour choisir une approche lors d'une nouvelle fonctionnalité, le skill local roblox-feature-docs compare les bibliothèques pertinentes, leurs documentations et les API réellement disponibles dans les versions verrouillées.

Outils initialisés

• roblox-ts : roblox-ts, @rbxts/types, @rbxts/compiler-types et le transformer Flamework sont configurés dans tsconfig.json.
• Rojo : manifeste default.project.json, pnpm build et pnpm serve.
• rbxts-build : commandes pnpm start, pnpm watch, pnpm open, pnpm stop et construction game.rbxl.
• Asphalt : binaire épinglé avec Rokit ; aucun asset à synchroniser dans ce template vierge.
• darklua : binaire épinglé avec Rokit ; aucune transformation de Lua requise pour le démarrage.
• Bedrock : CLI @bedrock-rbx/core@0.3.4 épinglée avec pnpm ; les setups Windows et WSL l’installent et vérifient son démarrage. Voir la configuration de déploiement ci-dessous.
• mise et pnpm : versions du runtime et gestion reproductible des dépendances.
• ESLint : configuration flat dans eslint.config.mjs, avec typescript-eslint et Prettier.
• Husky : vérification Git locale.
• Renovate : règles de mise à jour des dépendances ; l'activation du bot sur l'hébergeur reste à faire.

Déploiement avec Bedrock

Bedrock est installé par pnpm, avec Node.js 24.12 minimum (la version de mise.toml convient). Après une mise à jour du template, lancer rokit install puis pnpm install --frozen-lockfile et pnpm bedrock --version. Les scripts de setup réalisent aussi ces étapes. La version 0.3.4 est antérieure à la version 1.0 ; sa configuration peut évoluer lors des mises à jour. Voir le README du paquet.

1. Créer ou choisir l’expérience Roblox cible.
2. Copier bedrock.config.example.json vers bedrock.config.json, puis remplacer REPLACE_WITH_UNIVERSE_ID et REPLACE_WITH_PLACE_ID. Le fichier publie game.rbxl dans l’environnement production. La génération de code est désactivée pour conserver le build roblox-ts existant.
3. Copier .env.example vers .env et renseigner BEDROCK_API_KEY (clé Roblox Open Cloud autorisée sur l’expérience cible). Adapter les permissions Open Cloud aux ressources gérées selon la documentation Bedrock. Les commandes ci-dessous chargent .env automatiquement ; les variables déjà exportées dans le terminal ont priorité. Ne jamais commiter les jetons.

pnpm build
pnpm deploy:diff
pnpm deploy

Le plugin local utilise le contrat officiel de Bedrock 0.3.4. Il conserve l’état dans .bedrock/state/production.json (chemin relatif à la racine du dépôt), sans Gist, compte de stockage supplémentaire ou jeton GitHub. Ces fichiers sont ignorés par Git, ESLint et Prettier. Sauvegarder ce dossier après un déploiement et le conserver lors d’un changement de machine : il relie les ressources du projet aux IDs Roblox. Un état corrompu provoque une erreur et ne devient jamais un état vide.

Un verrou local empêche deux déploiements simultanés sur le même environnement. Si un processus interrompu laisse un verrou, arrêter tous les déploiements concernés avant de lancer pnpm bedrock state unlock --env production. Ne pas partager ce dossier entre plusieurs machines ni le synchroniser pendant un déploiement. La publication contacte toujours Roblox et nécessite BEDROCK_API_KEY.

pnpm deploy:diff prévisualise les opérations sans les appliquer ; game.rbxl doit déjà exister. pnpm deploy reconstruit le jeu puis applique les changements à l’expérience configurée. Le setup ne déploie rien. La configuration réelle bedrock.config.json peut être versionnée : les IDs ne sont pas des secrets. Aucun état de déploiement antérieur n’est présent dans ce template.

MCP : Codex, Claude, Cursor et Antigravity

Les deux serveurs sont définis dans les fichiers de projet suivants. Chaque client lit son propre fichier, et les processus sont lancés à la demande :

Client	Configuration dans ce dépôt	Référence du client
Codex	.codex/config.toml	MCP Codex
Claude Code	.mcp.json	MCP Claude Code
Cursor	.cursor/mcp.json	MCP Cursor
Antigravity	.agents/mcp_config.json	MCP Antigravity

• Roblox Studio MCP (documentation officielle) : les configurations lancent %LOCALAPPDATA%\Roblox\mcp.bat via cmd.exe. Ce lanceur est fourni par Studio sous Windows. Démarrer Studio, activer son serveur MCP dans les paramètres Assistant/MCP, puis redémarrer le client d'agent si nécessaire. Le fichier mcp.bat est présent sur la machine d'initialisation ; une connexion à une session Studio ouverte reste à vérifier.
• Blender MCP (documentation officielle) : les configurations lancent blender-mcp depuis le dépôt officiel Blender Lab, épinglé sur v1.0.3, au moyen de uvx. Blender 5.1+ et l'extension MCP doivent être installés et actifs. Sur la machine d'initialisation, Blender 5.2.2 LTS et l'extension 1.0.3 ont été installés ; le serveur se lance et le pont de l'extension a été vu à l'écoute sur localhost:9876. Un appel MCP complet depuis un client reste à vérifier. Rouvrir les clients après installation de uvx pour qu'ils héritent du nouveau PATH.

Le serveur Blender peut exécuter du code Python dans Blender : utiliser uniquement des projets de confiance. Les configurations n'incluent aucun secret.

L'API Cloud Creator Store est une API Roblox distincte des serveurs MCP ci-dessus. Elle n'est pas activée ici : son usage nécessite une clé et un cas d'utilisation précis.

_{Version du template : 1.1.0}