134 lines
14 KiB
Markdown
134 lines
14 KiB
Markdown
# 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`](package.json), [`pnpm-lock.yaml`](pnpm-lock.yaml), [`rokit.toml`](rokit.toml) et [`mise.toml`](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
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1
|
||
```
|
||
|
||
```powershell
|
||
$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](scripts/setup.ps1) nécessite WinGet (App Installer du Microsoft Store). Il installe Git, [mise](https://mise.jdx.dev/installing-mise.html), 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
|
||
bash scripts/setup.sh
|
||
```
|
||
|
||
Comme [`setup.ps1`](scripts/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`](mise.toml), Rokit et les outils de [`rokit.toml`](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 :
|
||
|
||
```bash
|
||
~/.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`](src/server/config/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`](src/client/controllers/cmdr-controller.ts).
|
||
|
||
- `@flamework/core` ([documentation](https://flamework.fireboltofdeath.dev/docs/introduction/)) — services, contrôleurs et injection ; le service de démarrage en donne un exemple.
|
||
- `@flamework/components` ([documentation](https://flamework.fireboltofdeath.dev/docs/additional-modules/components/creating-a-component/)) — composants d'instances.
|
||
- `@flamework/networking` ([documentation](https://flamework.fireboltofdeath.dev/docs/additional-modules/networking/introduction/)) — réseau typé.
|
||
- `@rbxts/react` ([documentation React Lua](https://github.com/jsdotlua/react-lua/blob/main/docs/api-reference/react.md), [liaison roblox-ts](https://github.com/littensy/rbxts-react#readme)) — interface React.
|
||
- `@rbxts/react-roblox` ([documentation ReactRoblox](https://github.com/jsdotlua/react-lua/blob/main/docs/api-reference/react-roblox.md), [liaison roblox-ts](https://github.com/littensy/rbxts-react#readme)) — rendu React dans Roblox.
|
||
- `@rbxts/reflex` ([documentation](https://littensy.github.io/reflex/docs/)) — état applicatif.
|
||
- `@rbxts/ripple` ([README et API](https://github.com/littensy/ripple#readme)) — animations.
|
||
- `@rbxts/services` ([README](https://github.com/roblox-ts/services#readme)) — accès typé aux services Roblox.
|
||
- `@rbxts/lapis` ([documentation](https://github.com/nezuo/lapis/tree/master/docs)) — persistance de données.
|
||
- `@rbxts/trove` ([README et API](https://github.com/Sleitnick/rbxts-trove#readme)) — nettoyage des ressources.
|
||
- `@rbxts/log` ([README](https://github.com/roblox-aurora/rbx-log#readme)) — journalisation.
|
||
- `@rbxts/sift` ([documentation](https://cxmeel.github.io/sift/)) — collections immuables
|
||
- `@rbxts/t` ([README et API](https://github.com/osyrisrblx/t#readme)) — validation de valeurs à l'exécution.
|
||
- `@rbxts/cmdr` ([documentation](https://eryn.io/Cmdr/), [types roblox-ts](https://github.com/sasial-dev/Cmdr#readme)) — commandes de développement.
|
||
- `@rbxts/gamejoy` ([README](https://github.com/Rimuy/GameJoy#readme)) — contrôles de jeu.
|
||
- `@rbxts/tween` ([README et API](https://github.com/Validark/Roblox-TS-Libraries/blob/master/tween/README.md)) — interpolations.
|
||
- `@rbxts/timer` ([README](https://github.com/Bytebit-Org/roblox-Timer#readme)) — temporisation.
|
||
- `@rbxts/ui-labs` ([documentation](https://ui-labs.luau.page/docs/getstarted.html)) — prévisualisation d'interface.
|
||
- `@rbxts/sound-manager` ([documentation du projet](https://github.com/xelnae-r/Sound-Manager#readme)) — gestion des sons
|
||
- `@rbxts/object-cache` ([documentation amont](https://github.com/Pyseph/ObjectCache#readme)) — cache de pièces/objets
|
||
- `@rbxts/net` ([README](https://github.com/roblox-aurora/rbx-net#readme)) — contient `ExperienceBroadcastEvent` pour les messages entre serveurs.
|
||
- `@rbxts-js/roblox-lua-promise` ([README](https://github.com/evaera/roblox-lua-promise#readme)) — implémentation de promesses
|
||
|
||
Pour choisir une approche lors d'une nouvelle fonctionnalité, le skill local [`roblox-feature-docs`](.agents/skills/roblox-feature-docs/SKILL.md) compare les bibliothèques pertinentes, leurs documentations et les API réellement disponibles dans les versions verrouillées.
|
||
|
||
## Outils initialisés
|
||
|
||
- [roblox-ts](https://roblox-ts.com/docs/) : `roblox-ts`, `@rbxts/types`, `@rbxts/compiler-types` et le transformer Flamework sont configurés dans [`tsconfig.json`](tsconfig.json).
|
||
- [Rojo](https://rojo.space/docs/) : manifeste [`default.project.json`](default.project.json), `pnpm build` et `pnpm serve`.
|
||
- [rbxts-build](https://github.com/osyrisrblx/rbxts-build#readme) : commandes `pnpm start`, `pnpm watch`, `pnpm open`, `pnpm stop` et construction `game.rbxl`.
|
||
- [Asphalt](https://github.com/jackTabsCode/asphalt#readme) : binaire épinglé avec Rokit ; aucun asset à synchroniser dans ce template vierge.
|
||
- [darklua](https://darklua.com/docs/) : binaire épinglé avec Rokit ; aucune transformation de Lua requise pour le démarrage.
|
||
- [Bedrock](https://github.com/christopher-buss/bedrock#readme) : 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](https://mise.jdx.dev/) et [pnpm](https://pnpm.io/) : versions du runtime et gestion reproductible des dépendances.
|
||
- [ESLint](https://eslint.org/docs/latest/) : configuration flat dans [`eslint.config.mjs`](eslint.config.mjs), avec [typescript-eslint](https://typescript-eslint.io/) et [Prettier](https://prettier.io/docs/).
|
||
- [Husky](https://typicode.github.io/husky/) : vérification Git locale.
|
||
- [Renovate](https://docs.renovatebot.com/) : 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](https://github.com/christopher-buss/bedrock/tree/v0.3.4/packages/bedrock#readme).
|
||
|
||
1. Créer ou choisir l’expérience Roblox cible.
|
||
2. Copier [`bedrock.config.example.json`](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`](.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](https://github.com/christopher-buss/bedrock#readme). Les commandes ci-dessous chargent `.env` automatiquement ; les variables déjà exportées dans le terminal ont priorité. Ne jamais commiter les jetons.
|
||
|
||
```bash
|
||
pnpm build
|
||
pnpm deploy:diff
|
||
pnpm deploy
|
||
```
|
||
|
||
Le [plugin local](scripts/bedrock-local-state.mjs) utilise le [contrat officiel de Bedrock 0.3.4](https://github.com/christopher-buss/bedrock/blob/v0.3.4/apps/website/docs/bedrock/guide/plugins.md). 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`](.codex/config.toml) | [MCP Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli) |
|
||
| Claude Code | [`.mcp.json`](.mcp.json) | [MCP Claude Code](https://code.claude.com/docs/en/mcp) |
|
||
| Cursor | [`.cursor/mcp.json`](.cursor/mcp.json) | [MCP Cursor](https://prod.cursor.com/help/customization/mcp) |
|
||
| Antigravity | [`.agents/mcp_config.json`](.agents/mcp_config.json) | [MCP Antigravity](https://www.antigravity.google/docs/mcp) |
|
||
|
||
- **Roblox Studio MCP** ([documentation officielle](https://create.roblox.com/docs/studio/mcp)) : 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](https://www.blender.org/lab/mcp-server/)) : 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](https://create.roblox.com/docs/cloud/reference/features/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.
|
||
|
||
<sub>Version du template : 1.1.0</sub>
|