pixijs-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

create pixi.js

is the official CLI for scaffolding a new PixiJS v8 project. Run it with any package manager (

npm

yarn

pnpm

bun

) and pick a template from the interactive menu, or pass

--template

to skip prompts. It writes a self-contained project folder; you then

cd

in, install dependencies, and run the dev script.

create pixi.js

是官方CLI工具，用于搭建新的PixiJS v8项目。你可以通过任意包管理器（

npm

、

yarn

、

pnpm

、

bun

）运行它，从交互式菜单中选择模板，或者通过传递

--template

参数跳过提示。它会生成一个独立的项目文件夹，之后你只需进入该文件夹、安装依赖并运行开发脚本即可。

Quick Start

快速开始

Scaffold a new project with interactive prompts:

bash

npm create pixi.js@latest

Or skip prompts by passing a project name and template:

bash

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

Then:

bash

cd my-game
npm install
npm run dev

Requires Node.js 18+ or 20+. Some templates (notably

creation-web

and

framework-react

) may require a newer Node version; the package manager will warn if so.

通过交互式提示搭建新项目：

bash

npm create pixi.js@latest

或者通过指定项目名称和模板跳过提示：

bash

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

之后执行：

bash

cd my-game
npm install
npm run dev

需要Node.js 18+或20+版本。部分模板（尤其是

creation-web

和

framework-react

）可能需要更新的Node版本；如果不符合要求，包管理器会发出警告。

Adding PixiJS to an existing project

为现有项目添加PixiJS

If you already have a bundler, framework, or project set up, skip the CLI and install the package directly:

bash

npm install pixi.js

Then import from

pixi.js

and construct an

Application

as shown in

pixijs-application

. The CLI templates are a convenience for new projects; they don't add anything to the library that

npm install pixi.js

can't give you.

Related skills:

pixijs-application

(how the scaffolded

new Application()

app.init()

entry point works),

pixijs-core-concepts

(renderers and the render loop),

pixijs-scene-core-concepts

(scene graph fundamentals for the first things you'll add to the stage),

pixijs-assets

(loading textures, fonts, and bundles the template expects you to drop into

public/

src/assets/

如果你已经配置好打包器、框架或项目，可以跳过CLI直接安装包：

bash

npm install pixi.js

然后从

pixi.js

导入并构造

Application

，具体可参考

pixijs-application

。CLI模板只是为新项目提供便利，并不会提供

npm install pixi.js

无法获取的库内容。

相关技能：

pixijs-application

（搭建好的

new Application()

app.init()

入口点的工作原理）、

pixijs-core-concepts

（渲染器与渲染循环）、

pixijs-scene-core-concepts

（场景图基础，是你将添加到舞台的核心内容）、

pixijs-assets

（加载模板预期你放入

public/

或

src/assets/

的纹理、字体和资源包）。

Core Patterns

核心模式

Choose a package manager

选择包管理器

The command is the same shape for every package manager:

bash

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

Under npm 7+ you must pass a

--

before CLI flags so npm doesn't consume them:

bash

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

Yarn, pnpm, and bun don't need the extra separator:

bash

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

Use

as the project name to scaffold into the current directory.

所有包管理器的命令格式一致：

bash

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

在npm 7+版本中，你必须在CLI标志前添加

--

，避免npm解析这些标志：

bash

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

Yarn、pnpm和bun不需要额外的分隔符：

bash

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

使用

作为项目名称，可将项目搭建到当前目录。

Interactive flow

交互式流程

Running with no arguments walks through prompts:

Project name (defaults to
```
pixi-project
```
).
Framework / template category.
Variant (TypeScript vs JavaScript where applicable).
Whether to install dependencies immediately (some runners).

At the end, the CLI prints the

cd

+ install + dev commands for the manager you invoked it with.

不带参数运行命令会进入提示流程：

项目名称（默认值为
```
pixi-project
```
）。
框架/模板分类。
变体（适用时可选TypeScript或JavaScript）。
是否立即安装依赖（部分运行器支持）。

最后，CLI会输出你所使用的包管理器对应的

cd

+ 安装 + 开发命令。

Non-interactive flow

非交互式流程

Pass a project name and

--template

to skip all prompts. This is the form you want for scripts, CI, and quickstart docs:

bash

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

指定项目名称和

--template

参数可跳过所有提示。这种形式适用于脚本、CI和快速入门文档：

bash

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

Available template presets

可用的模板预设

Templates fall into two categories:

Bundler templates (
```
bundler-*
```
): generic PixiJS setup wired up with your bundler of choice. Use one of these when you want to pick your own structure.
Creation templates (
```
creation-*
```
): platform-tailored starters with extras already wired in (AssetPack, sound, UI, scene routing). Use one of these when you want batteries included.
Framework templates (
```
framework-*
```
): PixiJS embedded inside a host framework like React.
Extension templates (
```
extension-*
```
): scaffolding for building a reusable PixiJS package.

For most new projects,

bundler-vite

is the recommended starting point.

Template	What you get
`bundler-vite`	Vite + TypeScript PixiJS project. The default first-stop template.
`bundler-vite-js`	Vite + plain JavaScript.
`bundler-webpack`	Webpack + TypeScript.
`bundler-webpack-js`	Webpack + plain JavaScript.
`bundler-esbuild`	esbuild + TypeScript.
`bundler-esbuild-js`	esbuild + plain JavaScript.
`bundler-import-map`	No-bundler setup using a browser import map (good for learning / demos).
`creation-web`	PixiJS Creation Engine web template with scene-based game scaffolding, AssetPack, sound, and UI integration.
`framework-react`	React + TypeScript + PixiJS via the `@pixi/react` package.
`framework-react-js`	React + plain JavaScript + PixiJS.
`extension-default`	Starter for building a reusable PixiJS extension/package.

The live list is maintained in the

create-pixi

repo; run

npm create pixi.js@latest

without arguments to see the current menu if you need to confirm.

模板分为两类：

打包器模板（
```
bundler-*
```
）：通用PixiJS配置，适配你选择的打包器。当你想要自定义项目结构时可使用此类模板。
创建模板（
```
creation-*
```
）：针对特定平台的启动模板，已集成额外功能（AssetPack、音效、UI、场景路由）。当你想要开箱即用的完整功能时可使用此类模板。
框架模板（
```
framework-*
```
）：将PixiJS嵌入到React等宿主框架中的模板。
扩展模板（
```
extension-*
```
）：用于构建可复用PixiJS包的脚手架模板。

对于大多数新项目，推荐从

bundler-vite

开始。

模板名称	包含内容
`bundler-vite`	Vite + TypeScript PixiJS项目。默认的首选模板。
`bundler-vite-js`	Vite + 纯JavaScript。
`bundler-webpack`	Webpack + TypeScript。
`bundler-webpack-js`	Webpack + 纯JavaScript。
`bundler-esbuild`	esbuild + TypeScript。
`bundler-esbuild-js`	esbuild + 纯JavaScript。
`bundler-import-map`	无需打包器的设置，使用浏览器导入映射（适合学习/演示）。
`creation-web`	PixiJS Creation Engine网页模板，包含基于场景的游戏脚手架、AssetPack、音效和UI集成。
`framework-react`	React + TypeScript + 通过 `@pixi/react` 包集成PixiJS。
`framework-react-js`	React + 纯JavaScript + PixiJS。
`extension-default`	用于构建可复用PixiJS扩展/包的启动模板。

最新的模板列表维护在

create-pixi

仓库中；如需确认，可不带参数运行

npm create pixi.js@latest

查看当前菜单。

Post-scaffold flow

项目搭建后的流程

Every template ships with the same three-step onboarding:

bash

cd my-game
npm install
npm run dev

npm run dev

starts the local dev server on the default port (Vite 5173, webpack 8080, etc.; the template's README has the exact number). Changes to

src/

hot-reload without reloading the whole page.

Other scripts every template exposes (names may vary slightly by preset):

```
npm run build
```
: produce a production build in
```
dist/
```
.
```
npm run preview
```
/
```
npm run serve
```
: serve the production build locally.
```
npm run lint
```
: run the template's configured linter if it ships one.

每个模板都包含相同的三步入门流程：

bash

cd my-game
npm install
npm run dev

npm run dev

会启动本地开发服务器，使用默认端口（Vite为5173，webpack为8080等；模板的README中有确切端口号）。修改

src/

目录下的文件会触发热重载，无需刷新整个页面。

每个模板还提供其他脚本（名称可能因预设略有不同）：

```
npm run build
```
：在
```
dist/
```
目录生成生产构建产物。
```
npm run preview
```
/
```
npm run serve
```
：在本地预览生产构建产物。
```
npm run lint
```
：运行模板配置的代码检查工具（如果模板包含的话）。

Scaffolding into an existing directory

搭建到现有目录

Use

as the project name to write into the current working directory. The CLI refuses to run if non-empty and conflicting files exist unless you confirm the prompt.

bash

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

使用

作为项目名称，可将项目写入当前工作目录。如果目录非空且存在冲突文件，CLI会拒绝运行，除非你确认提示。

bash

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

Next steps

后续步骤

After

npm run dev

starts, the template opens on a blank or bunny-sprite scene. The usual progression is:

Read
```
pixijs-application
```
to understand how the template's entry point constructs
```
new Application()
```
and calls
```
await app.init(...)
```
, how
```
app.stage
```
/
```
app.renderer
```
/
```
app.canvas
```
hang together, and how the ResizePlugin and TickerPlugin behave by default.
Read
```
pixijs-core-concepts
```
for the renderer and render-loop mental model.
Read
```
pixijs-scene-core-concepts
```
before adding your first non-trivial scene so you know the container-vs-leaf rule upfront.
Drop in textures via
```
pixijs-assets
```
once you're ready to load real art.

npm run dev

启动后，模板会打开一个空白或带有兔子精灵的场景。通常的学习流程如下：

阅读
```
pixijs-application
```
，了解模板入口点如何构造
```
new Application()
```
并调用
```
await app.init(...)
```
，
```
app.stage
```
/
```
app.renderer
```
/
```
app.canvas
```
如何协同工作，以及ResizePlugin和TickerPlugin的默认行为。
阅读
```
pixijs-core-concepts
```
，建立渲染器和渲染循环的思维模型。
在添加第一个复杂场景前，阅读
```
pixijs-scene-core-concepts
```
，提前了解容器与叶子节点的规则。
准备好加载实际资源后，通过
```
pixijs-assets
```
添加纹理。

Common Mistakes

常见错误

[HIGH] Missing

--

separator on npm 7+

[高风险] npm 7+版本中缺少

--

分隔符

Wrong:

bash

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

Correct:

bash

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

npm 7+ consumes flags after the package spec unless you pass

--

to forward them. Without the separator, the CLI ignores

--template

and drops back to the interactive prompt. Yarn, pnpm, and bun don't need the separator.

错误写法：

bash

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

正确写法：

bash

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

npm 7+会解析包规范后的标志，除非你添加

--

来传递这些标志。如果没有分隔符，CLI会忽略

--template

参数并回到交互式提示。Yarn、pnpm和bun不需要该分隔符。

[MEDIUM] Running with an old Node version

[中风险] 使用旧版本Node.js

PixiJS requires Node 18+ or 20+. Some templates (framework-react, creation-web) expect a newer Node for their tooling. Upgrade Node before re-running the CLI if you see an "engines" warning from your package manager.

PixiJS需要Node 18+或20+版本。部分模板（framework-react、creation-web）的工具链需要更新的Node版本。如果包管理器发出“engines”警告，请先升级Node版本再重新运行CLI。

[MEDIUM] Top-level

await app.init()

broken in Vite production builds

[中风险] Vite生产构建中顶级

await app.init()

失效

On Vite versions

<=6.0.6

, top-level

await

works in dev but breaks in production builds, so a

bundler-vite

project that does this at module scope will fail after

npm run build

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

Wrap the init in an async IIFE instead:

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

Upgrading Vite past 6.0.6 also resolves it, but the IIFE pattern is safe on every version and matches the PixiJS quick-start guide.

在Vite版本

<=6.0.6

中，顶级

await

在开发环境正常工作，但在生产构建中会失效，因此

bundler-vite

项目中如果在模块作用域执行以下代码，

npm run build

后会失败：

const app = new Application();
await app.init({ resizeTo: window }); // 生产环境中模块顶级的此代码会失效

改为将初始化代码包裹在异步立即执行函数表达式（IIFE）中：

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

将Vite升级到6.0.6以上版本也可解决此问题，但IIFE模式在所有版本中都安全，且与PixiJS快速入门指南一致。

API Reference

API参考

create-pixi on GitHub
create-pixi documentation site
Application: the class the generated entry point instantiates.

GitHub上的create-pixi
create-pixi文档站点
Application：生成的入口点实例化的类。

pixijs-create

Original

Translation

Quick Start

快速开始

Adding PixiJS to an existing project

为现有项目添加PixiJS

Core Patterns

核心模式

Choose a package manager

选择包管理器

Interactive flow

交互式流程

Non-interactive flow

非交互式流程

Available template presets

可用的模板预设

Post-scaffold flow

项目搭建后的流程

Scaffolding into an existing directory

搭建到现有目录

Next steps

后续步骤

Common Mistakes

常见错误

[HIGH] Missing
`--`
separator on npm 7+

[高风险] npm 7+版本中缺少
`--`
分隔符

[MEDIUM] Running with an old Node version

[中风险] 使用旧版本Node.js

[MEDIUM] Top-level
`await app.init()`
broken in Vite production builds

[中风险] Vite生产构建中顶级
`await app.init()`
失效

API Reference

API参考

pixijs-create

Original

Translation

Quick Start

快速开始

Adding PixiJS to an existing project

为现有项目添加PixiJS

Core Patterns

核心模式

Choose a package manager

选择包管理器

Interactive flow

交互式流程

Non-interactive flow

非交互式流程

Available template presets

可用的模板预设

Post-scaffold flow

项目搭建后的流程

Scaffolding into an existing directory

搭建到现有目录

Next steps

后续步骤

Common Mistakes

常见错误

[HIGH] Missing -- separator on npm 7+

[高风险] npm 7+版本中缺少--分隔符

[MEDIUM] Running with an old Node version

[中风险] 使用旧版本Node.js

[MEDIUM] Top-level await app.init() broken in Vite production builds

[中风险] Vite生产构建中顶级await app.init()失效

API Reference

API参考

[HIGH] Missing
`--`
separator on npm 7+

[高风险] npm 7+版本中缺少
`--`
分隔符

[MEDIUM] Top-level
`await app.init()`
broken in Vite production builds

[中风险] Vite生产构建中顶级
`await app.init()`
失效