forked from Crown-Studio/roblox-ts-template
85 lines
9.5 KiB
Markdown
85 lines
9.5 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
|
|
|
|
Prérequis : [Roblox Studio](https://create.roblox.com/docs/studio/setup), [mise](https://mise.jdx.dev/getting-started.html) et [Rokit](https://github.com/rojo-rbx/rokit#readme). Sous Windows, rouvrir le terminal après leur installation pour actualiser `PATH`.
|
|
|
|
```powershell
|
|
mise install
|
|
rokit install
|
|
pnpm install --frozen-lockfile
|
|
pnpm check
|
|
pnpm build
|
|
pnpm serve
|
|
```
|
|
|
|
`mise` épingle Node.js 24.16.0, pnpm 11.21.0 et uv 0.13.0. `rokit` installe Rojo 7.7.1, Asphalt 2.0.2, darklua 0.19.0 et Mantle 0.11.18. `pnpm build` compile le TypeScript et crée `game.rbxl` avec Rojo. Ouvrir ce fichier dans Studio, ou utiliser `pnpm start` pour le flux [`rbxts-build`](https://github.com/osyrisrblx/rbxts-build#readme). `pnpm watch` lance la compilation et le serveur Rojo en continu. Le projet Rojo est [`default.project.json`](default.project.json) et les entrées client/serveur sont sous [`src`](src/).
|
|
|
|
Autres commandes : `pnpm lint`, `pnpm format:check` et `pnpm format`. [Husky](https://typicode.github.io/husky/) installe un hook local `pre-commit` qui exécute `pnpm lint`. [Renovate](https://docs.renovatebot.com/) lit [`renovate.json`](renovate.json) une fois son application activée sur le dépôt distant.
|
|
|
|
## 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 paquets ne sont pas automatiquement utilisés par le code de démarrage.
|
|
|
|
- `@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.
|
|
|
|
## Vérification du template
|
|
|
|
Sur Windows, l'installation verrouillée, `pnpm check`, `pnpm format:check`, `pnpm build` et `pnpm start -- --no-watch` ont réussi. `pnpm build` produit `game.rbxl` et `pnpm start` a lancé Roblox Studio. `codex mcp list` reconnaît les deux serveurs. Un test de jeu dans Studio et un appel MCP complet restent à effectuer.
|