113 lines
12 KiB
Markdown
113 lines
12 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.
|
|
- [Mantle](https://mantledeploy.vercel.app/) : binaire épinglé avec Rokit ; le déploiement exige une expérience Roblox et des identifiants propres au projet. Son [dépôt](https://github.com/blake-mealey/mantle#readme) indique qu'il n'est plus maintenu.
|
|
- [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.
|
|
|
|
## 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>
|