pixijs-create

create pixi.js est l'interface de ligne de commande officielle pour scaffolder un nouveau projet PixiJS v8. Exécutez-la avec n'importe quel gestionnaire de paquets (npm, yarn, pnpm, bun) et choisissez un modèle dans le menu interactif, ou passez --template pour ignorer les invites. Elle crée un dossier de projet autonome ; vous changez alors de répertoire, installez les dépendances et exécutez le script dev.

Quick Start

Scaffoldez un nouveau projet avec des invites interactives :

npm create pixi.js@latest

Ou ignorez les invites en passant un nom de projet et un modèle :

npm create pixi.js@latest my-game -- --template bundler-vite

Ensuite :

cd my-game
npm install
npm run dev

Nécessite Node.js 18+ ou 20+. Certains modèles (notamment creation-web et framework-react) peuvent nécessiter une version Node plus récente ; le gestionnaire de paquets vous avertira le cas échéant.

Ajouter PixiJS à un projet existant

Si vous avez déjà un bundler, un framework ou un projet configuré, ignorez l'interface de ligne de commande et installez le paquet directement :

npm install pixi.js

Ensuite importez depuis pixi.js et construisez une Application comme indiqué dans pixijs-application. Les modèles de l'interface de ligne de commande sont une commodité pour les nouveaux projets ; ils n'ajoutent rien à la bibliothèque que npm install pixi.js ne puisse pas vous donner.

Skills associées : pixijs-application (fonctionnement du point d'entrée new Application() + app.init() généré), pixijs-core-concepts (renderers et la boucle de rendu), pixijs-scene-core-concepts (fondamentaux du graphe de scène pour les premières choses que vous ajouterez à la stage), pixijs-assets (chargement de textures, de polices et de bundles que le modèle s'attend à ce que vous déposiez dans public/ ou src/assets/).

Core Patterns

Choisir un gestionnaire de paquets

La commande a la même forme pour chaque gestionnaire de paquets :

npm create pixi.js@latest
yarn create pixi.js
pnpm create pixi.js
bun create pixi.js

Sous npm 7+, vous devez passer -- avant les drapeaux CLI afin que npm ne les consomme pas :

npm create pixi.js@latest my-game -- --template bundler-vite

Yarn, pnpm et bun n'ont pas besoin du séparateur supplémentaire :

yarn create pixi.js my-game --template bundler-vite
pnpm create pixi.js my-game --template bundler-vite
bun create pixi.js my-game --template bundler-vite

Utilisez . comme nom de projet pour scaffolder dans le répertoire courant.

Flux interactif

Exécuter sans arguments parcourt les invites :

1. Nom du projet (par défaut pixi-project).
2. Catégorie de framework / modèle.
3. Variante (TypeScript vs JavaScript le cas échéant).
4. Faut-il installer les dépendances immédiatement (certains runners).

À la fin, l'interface de ligne de commande affiche les commandes cd + install + dev pour le gestionnaire avec lequel vous l'avez invoquée.

Flux non-interactif

Passez un nom de projet et --template pour ignorer toutes les invites. C'est la forme que vous voudrez pour les scripts, l'intégration continue et la documentation de démarrage rapide :

npm create pixi.js@latest my-game -- --template bundler-vite

Présets de modèles disponibles

Les modèles se divisent en deux catégories :

• Modèles Bundler (bundler-*) : configuration PixiJS générique câblée avec votre bundler de choix. Utilisez-en un quand vous voulez choisir votre propre structure.
• Modèles Creation (creation-*) : démarreurs adaptés à la plateforme avec des fonctionnalités supplémentaires déjà câblées (AssetPack, son, UI, routage de scène). Utilisez-en un quand vous voulez des fonctionnalités prêtes à l'emploi.
• Modèles Framework (framework-*) : PixiJS intégré dans un framework hôte comme React.
• Modèles Extension (extension-*) : scaffolding pour la construction d'un paquet PixiJS réutilisable.

Pour la plupart des nouveaux projets, bundler-vite est le point de départ recommandé.

La liste en direct est maintenue dans le repo create-pixi ; exécutez npm create pixi.js@latest sans arguments pour voir le menu actuel si vous avez besoin de confirmer.

Flux post-scaffold

Chaque modèle est livré avec le même onboarding en trois étapes :

cd my-game
npm install
npm run dev

npm run dev démarre le serveur dev local sur le port par défaut (Vite 5173, webpack 8080, etc. ; le README du modèle a le numéro exact). Les modifications apportées à src/ se rechargent à chaud sans recharger toute la page.

Autres scripts exposés par chaque modèle (les noms peuvent varier légèrement selon le préset) :

• npm run build : produit une version de production dans dist/.
• npm run preview / npm run serve : servez la version de production localement.
• npm run lint : exécutez le linter configuré du modèle s'il en dispose d'un.

Scaffolding dans un répertoire existant

Utilisez . comme nom de projet pour écrire dans le répertoire de travail courant. L'interface de ligne de commande refuse de s'exécuter si des fichiers non vides et conflictuels existent, sauf si vous confirmez l'invite.

mkdir my-game
cd my-game
npm create pixi.js@latest . -- --template bundler-vite

Prochaines étapes

Après le démarrage de npm run dev, le modèle s'ouvre sur une scène vierge ou avec un sprite lapin. La progression habituelle est :

1. Lisez pixijs-application pour comprendre comment le point d'entrée du modèle construit new Application() et appelle await app.init(...), comment app.stage / app.renderer / app.canvas s'assemblent, et comment ResizePlugin et TickerPlugin se comportent par défaut.
2. Lisez pixijs-core-concepts pour le modèle mental du renderer et de la boucle de rendu.
3. Lisez pixijs-scene-core-concepts avant d'ajouter votre première scène non triviale afin de connaître la règle container-vs-leaf dès le départ.
4. Déposez des textures via pixijs-assets une fois que vous êtes prêt à charger de vraies images.

Erreurs courantes

[HIGH] Séparateur -- manquant sur npm 7+

Incorrect :

npm create pixi.js@latest my-game --template bundler-vite

Correct :

npm create pixi.js@latest my-game -- --template bundler-vite

npm 7+ consomme les drapeaux après la spécification du paquet, sauf si vous passez -- pour les transmettre. Sans le séparateur, l'interface de ligne de commande ignore --template et revient à l'invite interactive. Yarn, pnpm et bun n'ont pas besoin du séparateur.

[MEDIUM] Exécution avec une ancienne version de Node

PixiJS nécessite Node 18+ ou 20+. Certains modèles (framework-react, creation-web) s'attendent à une version Node plus récente pour leurs outils. Mettez à jour Node avant de réexécuter l'interface de ligne de commande si vous voyez un avertissement « engines » de votre gestionnaire de paquets.

[MEDIUM] Top-level await app.init() cassée dans les versions Vite de production

Sur les versions Vite <=6.0.6, top-level await fonctionne en dev mais se casse dans les versions de production, donc un projet bundler-vite qui le fait à la portée du module échouera après npm run build :

const app = new Application();
await app.init({ resizeTo: window }); // broken at module top level in prod

Enveloppez l'init dans une IIFE async à la place :

(async () => {
  const app = new Application();
  await app.init({ resizeTo: window });
  document.body.appendChild(app.canvas);
})();

La mise à niveau de Vite au-delà de 6.0.6 la résout aussi, mais le motif IIFE est sûr sur chaque version et correspond au guide de démarrage rapide PixiJS.

Référence API

• create-pixi sur GitHub
• site de documentation create-pixi
• Application : la classe instanciée par le point d'entrée généré.