v8 迁移指南
¥v8 Migration Guide
欢迎来到 PixiJS v8 迁移指南!本文档旨在帮助你顺利地将项目从 PixiJS v7 过渡到最新、最好的 PixiJS v8。请按照以下步骤操作以确保成功迁移。
¥Welcome to the PixiJS v8 Migration Guide! This document is designed to help you smoothly transition your projects from PixiJS v7 to the latest and greatest PixiJS v8. Please follow these steps to ensure a successful migration.
目录
¥Table of Contents
1. 介绍
¥ Introduction
PixiJS v8 引入了一些令人兴奋的变化和改进,极大地提高了渲染器的性能。尽管我们已尽力保持迁移过程尽可能顺利,但一些重大变化是不可避免的。本指南将引导你完成将 PixiJS v7 项目迁移到 PixiJS v8 的必要步骤。
¥PixiJS v8 introduces several exciting changes and improvements that dramatically enhance the performance of the renderer. While we've made efforts to keep the migration process as smooth as possible, some breaking changes are inevitable. This guide will walk you through the necessary steps to migrate your PixiJS v7 project to PixiJS v8.
2. 重大变化
¥ Breaking Changes
在深入了解迁移过程之前,我们先回顾一下 PixiJS v8 中引入的重大更改。请务必密切关注这些更改,因为它们可能会影响你现有的代码库。
¥Before diving into the migration process, let's review the breaking changes introduced in PixiJS v8. Make sure to pay close attention to these changes as they may impact your existing codebase.
我应该升级吗?
¥Should I Upgrade?
通常,答案是肯定的!但目前,可能有一些理由表明最好不要立即升级。问自己以下问题:
¥Generally, the answer is yes! But currently, there may be reasons that suggest it's best not to upgrade just yet. Ask yourself the following questions:
我需要 ParticleContainer 吗?我们已经从 v8 中删除了它,因为在大多数情况下,常规容器速度更快。但是,当粒子数量开始超过 10,000 个范围时,情况并非如此。我们确实计划创建一个针对这种高级元素进行优化的新粒子容器。理想情况下,我们希望使其更快,并且占用的内存更少。创建 100,000 个精灵会消耗大量内存,而创建一个更轻的粒子容器 + 粒子类会有所帮助。如果你现在需要数以万计的粒子,并且性能是关键,那么最好继续利用 v7,直到我们发布新的粒子容器。
¥Do I need the ParticleContainer? We have removed this from v8 because, in most cases, a regular container is faster. However, this is not the case when the number of particles begins to exceed the 10,000s range. We do plan on creating a new particle container optimized for this high level of elements. Ideally, we would like to make it even faster and also less memory intensive. Creating 100,000 sprites consumes a lot of memory, and instead, creating a much lighter particle container + particle class would help here. If you need tens of thousands of particles right now and performance is key, then it's best to continue leveraging v7 until we release the new Particle Container.
你是否使用自定义批处理渲染器?批量渲染的逻辑已被广泛重新设计以提高速度!可以通过创建自己的批处理程序来实现自定义批处理,但构建一个批处理程序并将其插入现有批处理架构的能力尚未直接公开。如果你大量使用自定义批处理器,v8 中目前还没有高级类似替代方案。你需要更深入一层。展示自定义批处理功能已列入我们的路线图,我们希望我们的新方法将更加易于使用。请关注此处以获取该更新。
¥Do you make use of custom batch renderers? The logic for batch rendering has been extensively reworked for speed! Custom batching can be achieved by creating your own batcher, but the ability to build one and slot it into the existing batching architecture has not been directly exposed just yet. If you are making extensive use of custom batchers, there is no high level analogous alternative in v8 just yet. You would need to go a layer deeper. Exposing the ability for custom batching is on our roadmap, and we hope that our new approach will be even easier to use. Watch this space for that update.
你的项目是否利用了尚未迁移到 v8 的现有 Pixi 库?我们正在努力将我们的关键库迁移到 v8,但不希望这成为那些使用纯 Pixi 的人的障碍。这意味着一些库暂时没有 v8 对应库。如果你是这种情况,最好推迟迁移。
¥Does your project leverage existing Pixi libraries that have not yet been migrated to v8? We are working hard to migrate our key libraries to v8 but did not want this to be a blocker for those who are using pure Pixi. This means some libraries will not have a v8 counterpart just yet. It's best to hold off on migration if this is the case for you.
已迁移
¥Migrated
过滤器
¥Filters
声音
¥Sound
Gif
故事书
¥Storybook
UI
开放游戏
¥Open Games
正在迁移:
¥Migrating Right Now:
React
Spine(深奥版本)
¥Spine (esoteric version)
待迁移:
¥To Be Migrated:
Pixi 层(我们可能会将其作为一项功能直接合并到 PixiJS v8 中,而不是迁移它)
¥Pixi layers (rather than migrating this, we will likely incorporate it directly into PixiJS v8 as a feature)
新的封装结构
¥New Package Structure
从版本 5 开始,PixiJS 使用单独的子包将其代码库组织成更小的单元。然而,这种方法会导致一些问题,例如不同 PixiJS 版本的安装冲突,导致内部缓存复杂化。
¥Since version 5, PixiJS has utilized individual sub-packages to organize its codebase into smaller units. However, this approach led to issues, such as conflicting installations of different PixiJS versions, causing complications with internal caches.
在 v8 中,PixiJS 已恢复为单包结构。虽然你仍然可以导入 PixiJS 的特定部分,但你只需要安装主包。
¥In v8, PixiJS has reverted to a single-package structure. While you can still import specific parts of PixiJS, you only need to install the main package.
老的:
¥Old:
import { Application } from '@pixi/app';
import { Sprite } from '@pixi/sprite';
新的:
¥New:
import { Application, Sprite } from 'pixi.js';
定制构建
¥Custom Builds
PixiJS 使用 "extensions" 系统来添加渲染器功能。默认情况下,PixiJS 包含许多扩展,可提供全面的开箱即用体验。但是,为了完全控制功能和包大小,你可以手动导入特定的 PixiJS 组件。
¥PixiJS uses an "extensions" system to add renderer functionality. By default, PixiJS includes many extensions for a comprehensive out-of-the-box experience. However, for full control over features and bundle size, you can manually import specific PixiJS components.
// imported by default
import 'pixi.js/accessibility';
import 'pixi.js/app';
import 'pixi.js/events';
import 'pixi.js/filters';
import 'pixi.js/sprite-tiling';
import 'pixi.js/text';
import 'pixi.js/text-bitmap';
import 'pixi.js/text-html';
import 'pixi.js/graphics';
import 'pixi.js/mesh';
import 'pixi.js/sprite-nine-slice';
// not added by default, everyone needs to import these manually
import 'pixi.js/advanced-blend-modes';
import 'pixi.js/unsafe-eval';
import 'pixi.js/prepare';
import 'pixi.js/math-extras';
import 'pixi.js/dds';
import 'pixi.js/ktx';
import 'pixi.js/ktx2';
import 'pixi.js/basis';
import { Application } from 'pixi.js';
const app = new Application();
await app.init({
manageImports: false, // disable importing the above extensions
});
初始化应用时,你可以禁用自动导入功能,防止 PixiJS 自动导入任何扩展。你需要手动导入它们,如上面所示。
¥When initializing the application, you can disable the auto-import feature, preventing PixiJS from importing any extensions automatically. You'll need to import them manually, as demonstrated above.
还应该指出的是,pixi.js/text-bitmap
还添加了 Assets
加载功能。因此,如果你想在初始化渲染器之前加载位图字体,则需要导入此扩展。
¥It should also be noted that the pixi.js/text-bitmap
, also add Assets
loading functionality.
Therefore if you want to load bitmap fonts BEFORE initialising the renderer, you will need to import this extension.
import 'pixi.js/text-bitmap';
import { Assets, Application } from 'pixi.js';
await Assets.load('my-font.fnt'); // If 'pixi.js/text-bitmap' is not imported, this will not load
await new Application().init();
异步初始化
¥Async Initialisation
PixiJS 现在需要异步初始化。随着 WebGPU 渲染器的引入,PixiJS 现在需要等待才能使用
¥PixiJS will now need to be initialised asynchronously. With the introduction of the WebGPU renderer PixiJS will now need to be awaited before being used
老的:
¥Old:
import { Application } from 'pixi.js';
const app = new Application();
// do pixi things
新的:
¥New:
import { Application } from 'pixi.js'
const app = new Application();
(async () => {
await app.init({
// application options
});
// do pixi things
})()
通过此更改,还意味着 ApplicationOptions
对象现在可以传递到 init
函数而不是构造函数中。
¥With this change it also means that the ApplicationOptions
object can now be passed into the init
function instead of the constructor.
** 纹理调整 **
¥** Texture adjustments **
纹理结构已被修改,以简化 v7 中后台变得相当混乱的情况。纹理不再知道或管理资源的加载。这需要由你或资源管理员提前完成。纹理只需要完全加载的资源。这使得事情变得更容易管理,因为纹理的验证基本上可以在构造时完成并就此结束!BaseTexture 不再存在。相反,我们现在有各种可用的 TextureSource。纹理源将纹理的设置与如何上传和使用该纹理相结合。在 v8 中有以下纹理源:
¥Textures structures have been modified to simplify what was becoming quite a mess behind the scenes in v7. Textures no longer know or manage loading of resources. This needs to be done upfront by you or the assets manager. Textures expect full loaded resources only. This makes things so much easier to manage as the validation of a texture can essentially be done at construction time and left at that! BaseTexture no longer exists. In stead we now have a variety of TextureSources available. A texture source combines the settings of a texture with how to upload and use that texture. In v8 there are the following texture sources:
TextureSource - 你可以根据需要渲染或上传的原始纹理。(主要由渲染纹理使用)ImageSource - 包含某种图片资源的纹理源(例如 ImageBitmap 或 html 图片)CanvasSource - 包含画布的画布源。主要用于渲染画布或渲染到画布 (webGPU) VideoSource - 包含视频的纹理源。负责更新 GPU 上的纹理以确保它们保持同步。BufferSource - 包含缓冲区的纹理源。无论你真正想要什么!确保你的缓冲区类型和格式兼容!CompressedSource - 处理压缩纹理的纹理源。由 GPU 压缩纹理格式使用。
¥TextureSource - a vanilla texture that you can render too or upload however you wish. (used mainly by render textures) ImageSource - a texture source that contains an image resource of some kind (eg ImageBitmap or html image) CanvasSource - a canvas source that contains a canvas. Used mainly for rendering canvases or rendering to a canvas (webGPU) VideoSource - a texture source that contains a video. Takes care of updating the texture eon the GPU to ensure that they stay in sync. BufferSource - a texture source that contains a buffer. What ever you want really! make sure your buffer type and format are compatible! CompressedSource - a texture source that handles compressed textures. Used by the GPU compressed texture formats.
虽然大多数时候 Assets
都会返回你可能想要自己制作的纹理!祝你更强大!
¥Whilst the majority of the time Assets
will return Textures you may want to make you own! More power to ya!
要创建纹理源,签名与 baseTexture 不同。示例:
¥To create a texture source the signature differs from baseTexture. example:
const image = new Image();
image.onload = function(){
// create a texture source
const source = new ImageSource({
resource: image,
});
// create a texture
const texture = new Texture({
source
});
}
image.src = 'myImage.png';
图形 API 大修
¥Graphics API Overhaul
图形 API 有一些关键更改。事实上,这可能是 v8 中变化最大的部分。我们在可能的情况下添加了弃用内容,但以下是更改的概要:
¥There are a few key changes to the Graphics API. In fact this is probably the most changed part of v8. We have added deprecations where possible but below is the rundown of changes:
v8 不是先开始填充或描边,然后构建形状,而是要求你构建形状,然后描边/填充它。
Line
的术语已替换为Stroke
的术语¥Instead of beginning a fill or a stroke and then building a shape, v8 asks you to build your shape and then stroke / fill it. The terminology of
Line
has been replaced with the terminology ofStroke
老的:
¥Old:
// red rect
const graphics = new Graphics()
.beginFill(0xFF0000)
.drawRect(50, 50, 100, 100)
.endFill();
// blur rect with stroke
const graphics2 = new Graphics()
.lineStyle(2, 'white')
.beginFill('blue')
.circle(530, 50, 140, 100)
.endFill();
新的:
¥New:
// red rect
const graphics = new Graphics()
.rect(50, 50, 100, 100)
.fill(0xFF0000);
// blur rect with stroke
const graphics2 = new Graphics()
.rect(50, 50, 100, 100)
.fill('blue')
.stroke({width:2, color:'white'});
形状函数已重命名。每个绘图函数都被简化为其名称的较短版本。但它们具有相同的参数:
¥Shape functions have been renamed. Each drawing function has been simplified into a shorter version of its name. They have the same parameters though:
v7 API 调用 | v8 API 等效项 |
---|---|
drawChamferRect | chamferRect |
drawCircle | circle |
drawEllipse | ellipse |
drawFilletRect | filletRect |
drawPolygon | poly |
drawRect | rect |
drawRegularPolygon | regularPoly |
drawRoundedPolygon | roundPoly |
drawRoundedRect | roundRect |
drawRoundedShape | roundShape |
drawStar | star |
填充函数需要
FillStyle
个选项或颜色,而不是参数字符串。这也取代了beginTextureFill
¥fills functions expect
FillStyle
options or a color, rather than a string of parameters. This also replacesbeginTextureFill
老的:
¥Old:
const rect = new Graphics()
.beginTextureFill({texture:Texture.WHITE, alpha:0.5, color:0xFF0000})
.drawRect(0, 0, 100, 100)
.endFill()
.beginFill(0xFFFF00, 0.5)
.drawRect(100, 0, 100, 100)
.endFill();
新的:
¥New:
const rect = new Graphics()
.rect(0, 0, 100, 100)
.fill({texture:Texture.WHITE, alpha:0.5, color:0xFF0000})
.rect(100, 0, 100, 100)
.fill({color:0xFFFF00, alpha:0.5});
stokes 函数需要
StrokeStyle
个选项或颜色,而不是一串参数。这也取代了旧的lineTextureStyle
:¥stokes functions expect
StrokeStyle
options or a color, rather than a string of parameters. This also replaceslineTextureStyle
Old:
const rect = new Graphics()
.lineTextureStyle({texture:Texture.WHITE, width:10, color:0xFF0000})
.drawRect(0, 0, 100, 100)
.endFill()
.lineStyle(2, 0xFEEB77);
.drawRect(100, 0, 100, 100)
.endFill();
新的:
¥New:
const rect = new Graphics()
.rect(0, 0, 100, 100)
.stroke({texture:Texture.WHITE, width:10, color:0xFF0000})
.rect(100, 0, 100, 100)
.stroke({color:0xFEEB77, width:2});
孔现在使用新的
cut
函数。与stroke
和fill
一样,cut
作用于先前的形状。老的:¥holes now make use of a new
cut
function. As withstroke
andfill
,cut
acts on the previous shape. Old:
const rectAndHole = new Graphics()
.beginFill(0x00FF00)
.drawRect(0, 0, 100, 100)
.beginHole()
.drawCircle(50, 50, 20)
.endHole()
.endFill();
新的:
¥New:
const rectAndHole = new Graphics()
.rect(0, 0, 100, 100)
.fill(0x00FF00)
.circle(50, 50, 20)
.cut();
GraphicsGeometry
已替换为GraphicsContext
,这样可以更有效地共享Graphics
数据。¥
GraphicsGeometry
has been replaced withGraphicsContext
this allows for sharing ofGraphics
data more efficiently.
老的:
¥Old:
const rect = new Graphics()
.beginFill(0xFF0000)
.drawRect(50, 50, 100, 100)
.endFill();
const geometry = rect.geometry;
const secondRect = new Graphics(geometry);
新的:
¥New:
const context = new GraphicsContext()
.rect(50, 50, 100, 100)
.fill(0xFF0000);
const rect = new Graphics(context);
const secondRect = new Graphics(context);
着色器更改
¥Shader changes
由于我们现在需要同时容纳 WebGL 和 WebGPU 着色器,因此它们的构造方式已经过调整以考虑到这一点。你会注意到的主要区别(这通常适用于着色器)是纹理不再被视为统一的(因为它们不能包含在统一组中)。相反,我们有资源的概念。资源可以是以下几种东西:
¥As we now need to accommodate both WebGL and WebGPU shaders, the wey they are constructed has been tweaked to take this into account. The main differences you will notice (this is for shaders in general) is that Textures are no longer considered uniforms (as in they cannot be included in a uniform group). Instead we have the concept of resources. A resource can be a few things including:
TextureSource - 源纹理
myTexture.source
¥TextureSource - A source texture
myTexture.source
TextureStyle - 纹理样式
myTexture.style
¥TextureStyle - A texture style
myTexture.style
UniformGroup - 基于数字的统一
myUniforms = new UniformGroup({})
的集合¥UniformGroup - A collection of number based uniforms
myUniforms = new UniformGroup({})
BufferResource - 被视为统一组的缓冲区(高级)
¥BufferResource - A buffer that is treated as a uniform group (advanced)
现在创建一个仅 webgl 的着色器如下所示:
¥creating a webgl only shader now looks like this:
old
const shader = PIXI.Shader.from(vertex, fragment, uniforms);
new
仅 WebGL
¥just WebGL
const shader = Shader.from({
gl: { vertex, fragment },
resources, // resource used from above including uniform groups
});
WebGL 和 WebGPU
¥WebGL and WebGPU
const shader = Shader.from({
gl: { vertex, fragment },
gpu: {
vertex: {
entryPoint: 'mainVert',
source,
},
fragment: {
entryPoint: 'mainFrag',
source,
},
},
resources, // resource used from above including uniform groups
});
统一的构造方式也略有不同。在创建它们时,你现在提供你想要的变量类型。
¥Uniforms are also constructed in a slightly different way. When creating them, you now provide the type of variable you want it to be.
old
const uniformGroup = new UniformGroup({
uTime:1,
});
uniformGroup.uniforms.uTime = 100;
new
const uniformGroup = new UniformGroup({
uTime:{value:1, type:'f32',
});
uniformGroup.uniforms.uTime = 100; // still accessed the same!
要充分了解此新设置,最好的方法是查看 Mesh 和 Shader 示例:
¥The best way to play and fully and get to know this new setup please check out the Mesh and Shader examples:
¥old: v7 example new: v8 example
过滤器
¥Filters
除非你正在构建自定义过滤器,否则过滤器的工作原理几乎完全相同。如果是这种情况,则需要考虑上述着色器更改。
¥Filters work almost exactly the same, unless you are constructing a custom one. If this is the case, the shader changes mentioned above need to taken into account.
old
const filter = new Filter(vertex, fragment, {
uTime: 0.0,
});
new
const filter = new Filter({
glProgram: GlProgram.from({
fragment,
vertex,
}),
resources: {
timeUniforms: {
uTime: { value: 0.0, type: 'f32' },
},
},
});
¥old: v7 example new: v8 example
如果你使用的是 社区过滤器,请注意 @pixi/filter-*
包不再为 v8 维护,但是,你可以直接从 pixi-filters
包导入为子模块。
¥If you're using the community filters, note that the @pixi/filter-*
packages are no-longer maintained for v8, however, you can import directly from the pixi-filters
package as sub-modules.
*旧
¥*old
import { AdjustmentFilter } from '@pixi/filter-adjustment';
*新
¥*new
import { AdjustmentFilter } from 'pixi-filters/adjustment';
其他重大变化
¥Other Breaking Changes
DisplayObject
已被删除。Container
现在是所有 PixiJS 对象的基类。¥
DisplayObject
has been removed.Container
is now the base class for all PixiJS objects.updateTransform
已被删除,因为节点不再包含任何渲染逻辑¥
updateTransform
has been removed as nodes no longer contain any rendering logic我们确实认识到许多人使用此函数在每帧执行自定义逻辑,因此我们添加了一个新的
onRender
函数可用于此目的。¥We do recognise that many people used this function to do custom logic every frame, so we have added a new
onRender
function that can be used for this purpose.老的:
¥Old:
class MySprite extends Sprite {
constructor() {
super();
this.updateTransform();
}
updateTransform() {
super.updateTransform();
// do custom logic
}
}新的:
¥New:
class MySprite extends Sprite {
constructor() {
super();
this.onRender = this._onRender.bind(this);
}
_onRender() {
// do custom logic
}
}Mipmap 生成更改
¥Mipmap generation changes
BaseTexture
mipmap
属性已重命名为autoGenerateMipmaps
。¥The BaseTexture
mipmap
property has been renamed toautoGenerateMipmaps
.RenderTextures
的 Mipmap 已进行调整,以便开发者负责更新它们的 Mipmap。Mipmap 的生成可能会很昂贵,并且由于我们处理纹理的新反应方式,我们不希望在不需要时意外生成 mipmap。¥Mipmaps for
RenderTextures
have been adjusted so that developer is responsible for updating them mipmaps. Mipmap generation can be expensive, and due to the new reactive way we handle textures we do not want to accidentally generate mipmaps when they are not required.
const myRenderTexture = RenderTexture.create({width:100, height:100, autoGenerateMipmaps:true});
// do some rendering..
renderer.render({target:myRenderTexture, container:scene});
// now refresh mipmaps when you are ready
myRenderTexture.source.updateMipmaps();
由于 PixiJS 在内部处理事情的新方式,如果纹理的 UV 被修改,精灵将不再收到通知。最佳实践是纹理 UV 创建后不要对其进行修改。最好准备好纹理(它们的创建和存储成本低廉)。
¥Due to the new way PixiJS handles things internally, sprites no longer get notified if a texture's UVs have been modified. The best practice is not to modify texture UVs once they have been created. It's best to have textures ready to go (they are inexpensive to create and store).
有时,你可能想要采用一种特殊的技术来动画 UV。在最后一个实例中,你将负责更新精灵(值得注意的是,它可能会自动更新 - 但由于新的优化,这将无法得到保证)。然而,更新源数据(例如视频纹理)总是会立即反映。
¥Sometimes, you might want to employ a special technique that animates the UVs. In this last instance, you will be responsible for updating the sprite (it's worth noting that it may update automatically - but due to the new optimizations, this will not be guaranteed). Updating the source data (e.g., a video texture) will, however, always be reflected immediately.
const texture = await Assets.load('bunny.png');
const sprite = new Sprite(texture);
texture.frame.width = texture.frame.width/2;
texture.update();
// guarantees the texture changes will be reflected on the sprite
sprite.onViewUpdate();
// alternatively you can hooke into the sprites event
texture.on('update', ()=>{sprite.onViewUpdate});
当精灵的纹理更改时添加和删除事件的行为会导致不可接受的性能下降,尤其是在交换许多纹理时(想象一下具有大量关键帧纹理交换的射击游戏)。这就是为什么我们现在将这一责任留给用户。
¥The act of adding and removing the event when a sprite's texture was changed led to an unacceptable performance drop, especially when swapping many textures (imagine shooting games with lots of keyframe textures swapping). This is why we now leave that responsibility to the user.
新的容器剔除方法
¥New Container culling approach
在这个版本的 PixiJS 中,我们更改了
cullable
属性在容器上的工作方式。以前,剔除是在渲染循环期间自动为你完成的。然而,我们已经移除了这个逻辑,并为用户提供了自己控制何时发生剔除的能力。¥With this version of PixiJS we have changed how the
cullable
property works on containers. Previously culling was done for you automatically during the render loop. However, we have moved this logic out and provided users the ability to control when culling happens themselves.通过此更改,我们添加了一些新属性:
¥With this change we have added a couple of new properties:
cullable
- 容器是否可以被剔除¥
cullable
- Whether or not the container can be culledcullArea
- 将使用一个剔除区域来代替容器的边界¥
cullArea
- A cull area that will be used instead of the bounds of the containercullableChildren
- 容器子项是否可以被剔除。这可以帮助优化大场景¥
cullableChildren
- Whether or not the containers children can be culled. This can help optimise large scenes
新的:
¥New:
const container = new Container();
const view = new Rectangle(0, 0, 800, 600);
container.cullable = true;
container.cullArea = new Rectangle(0,0,400,400);
container.cullableChildren = false;
Culler.shared.cull(myContainer, view);
renderer.render(myContainer);如果你想模拟旧的行为,还有一个
CullerPlugin
可用于每帧自动调用Culler.shared.cull
。¥There is also a
CullerPlugin
that can be used to automatically callCuller.shared.cull
every frame if you want to simulate the old behaviour.import {extensions, CullerPlugin} from 'pixi.js'
extensions.add(CullerPlugin)重命名了几个网格类
¥Renamed several mesh classes
重命名为
SimpleMesh
->MeshSimple
¥renamed
SimpleMesh
->MeshSimple
重命名为
SimplePlane
->MeshPlane
¥renamed
SimplePlane
->MeshPlane
重命名为
SimpleRope
->MeshRope
¥renamed
SimpleRope
->MeshRope
删除了对
Assets
的弃用¥Deprecations for
Assets
removed老的:
¥Old:
import { Assets } from 'pixi.js';
Assets.add('bunny', 'bunny.png');新的:
¥New:
import { Assets } from 'pixi.js';
Assets.add({ alias: 'bunny', src: 'bunny.png' });settings
对象已被删除¥
settings
object has been removed老的:
¥Old:
import { settings, BrowserAdapter } from 'pixi.js';
settings.RESOLUTION = 1;
settings.FAIL_IF_MAJOR_PERFORMANCE_CAVEAT = false;
settings.ADAPTER = BrowserAdapter;新的:
¥New:
import { AbstractRenderer, DOMAdapter, BrowserAdapter } from 'pixi.js';
// Can also be passed into the renderer directly e.g `autoDetectRenderer({resolution: 1})`
AbstractRenderer.defaultOptions.resolution = 1;
// Can also be passed into the renderer directly e.g `autoDetectRenderer({failIfMajorPerformanceCaveat: false})`
AbstractRenderer.defaultOptions.failIfMajorPerformanceCaveat = false;
// See below for more information about changes to the adapter
DOMAdapter.set(BrowserAdapter);适配器和 Web Worker 更改
¥Adapter and Web Worker Changes
settings.ADAPTER
已被删除并替换为DOMAdapter
¥
settings.ADAPTER
has been removed and replaced withDOMAdapter
DOMAdapter
是一个静态类,可用于设置整个应用的适配器¥
DOMAdapter
is a static class that can be used to set the adapter for the entire applicationPixiJS 有两个内置的适配器
BrowserAdapter
和WebWorkerAdapter
¥PixiJS has two adapters built in
BrowserAdapter
andWebWorkerAdapter
BrowserAdapter
是默认适配器,在浏览器中运行时使用¥
BrowserAdapter
is the default adapter and is used when running in the browser在 Web Worker 中运行时使用
WebWorkerAdapter
¥
WebWorkerAdapter
is used when running in a web worker
老的:
¥Old:
import { settings, WebWorkerAdapter } from 'pixi.js';
settings.ADAPTER = WebWorkerAdapter;
settings.ADAPTER.createCanvas();新的:
¥New:
import { DOMAdapter, WebWorkerAdapter } from 'pixi.js';
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();
应用类型现在接受 Renderer 而不是 https://github.com/pixijs/pixijs/pull/9740 中 @Zyie 的视图
¥Application type now accepts Renderer instead of view by @Zyie in https://github.com/pixijs/pixijs/pull/9740
这是为了让
app.renderer
能够正确输入¥This is to allow
app.renderer
to be typed correctly老的:
¥Old:
const app = new Application<HTMLCanvasElement>();
新的:
¥New:
// WebGL or WebGPU renderer
const app = new Application<Renderer<HTMLCanvasElement>>();
// WebGL specific renderer
const app = new Application<WebGLRenderer<HTMLCanvasElement>>();
// WebGPU specific renderer
const app = new Application<WebGPURenderer<HTMLCanvasElement>>();
Texture.from
不再从 URL 加载纹理。¥
Texture.from
no longer will load a texture from a URL.使用
Texture.from
时,你需要传入CanvasSource
/ImageSource
/VideoSource
等源或HTMLImageElement
/HTMLCanvasElement
/HTMLVideoElement
等资源或通过Assets.load
加载的字符串¥When using
Texture.from
you will need to pass in a source such asCanvasSource
/ImageSource
/VideoSource
or a resource such asHTMLImageElement
/HTMLCanvasElement
/HTMLVideoElement
or a string that has been loaded throughAssets.load
老的:
¥Old:
import { Texture } from 'pixi.js';
const texture = Texture.from('https://i.imgur.com/IaUrttj.png');新的:
¥New:
import { Assets, Texture } from 'pixi.js';
await Assets.load('https://i.imgur.com/IaUrttj.png');
const texture = Texture.from('https://i.imgur.com/IaUrttj.png');
Ticker
的回调现在将传递Ticker
实例而不是增量时间。这是为了更好地控制使用的时间单位。¥The
Ticker
's callback will now pass theTicker
instance instead of the delta time. This is to allow for more control over what unit of time is used.老的:
¥Old:
Ticker.shared.add((dt)=> {
bunny.rotation += dt
});新的:
¥New:
Ticker.shared.add((ticker)=> {
bunny.rotation += ticker.deltaTime;
});文本解析器已重命名
¥Text parsers have been renamed
TextFormat
->bitmapFontTextParser
XMLStringFormat
->bitmapFontXMLStringParser
XMLFormat
->bitmapFontXMLParser
默认
eventMode
现在是passive
而不是auto
¥The default
eventMode
is nowpassive
instead ofauto
utils
已被删除。所有功能都可以直接导入。¥
utils
has been removed. All the functions are available as direct imports.老的:
¥Old:
import { utils } from 'pixi.js';
utils.isMobile.any();新的:
¥New:
import { isMobile } from 'pixi.js';
isMobile.any();container.getBounds()
现在返回Bounds
对象而不是Rectangle
对象。你可以使用container.getBounds().rectangle
来访问矩形。¥
container.getBounds()
now returns aBounds
object instead of aRectangle
object. You can access the rectangle by usingcontainer.getBounds().rectangle
instead.老的:
¥Old:
const bounds = container.getBounds();
新的:
¥New:
const bounds = container.getBounds().rectangle;
ParticleContainer
已被删除,你应该使用普通的Container
代替。由于新的渲染架构,ParticleContainer
提供的性能改进不再是必要的。¥
ParticleContainer
has been removed, you should use normal a regularContainer
instead. The performance improvements thatParticleContainer
provided are no longer necessary due to the new rendering architecture.
3. 已弃用的功能
¥ Deprecated Features
PixiJS v7 中的某些功能在 v8 中已被弃用。虽然它们仍然有效,但建议更新你的代码以使用新的替代方案。有关如何替换它们的详细信息,请参阅已弃用的功能部分。
¥Certain features from PixiJS v7 have been deprecated in v8. While they will still work, it's recommended to update your code to use the new alternatives. Refer to the deprecated features section for details on what to replace them with.
叶节点不再允许子节点
¥Leaf nodes no longer allow children
只有
Containers
可以生子级。这意味着Sprite
、Mesh
、Graphics
等不能再生育子级。¥Only
Containers
can have children. This means thatSprite
,Mesh
,Graphics
etc can no longer have children.要复制旧行为,你可以创建
Container
并向其添加叶节点。¥To replicate the old behaviour you can create a
Container
and add the leaf nodes to it.老的:
¥Old:
const sprite = new Sprite();
const spriteChild = new Sprite();
sprite.addChild(spriteChild);新的:
¥New:
const container = new Container();
const sprite = new Sprite();
const spriteChild = new Sprite();
container.addChild(sprite);
container.addChild(spriteChild);Application.view
替换为Application.canvas
¥
Application.view
replaced withApplication.canvas
老的:
¥Old:
const app = new Application({ view: document.createElement('canvas') });
document.body.appendChild(app.view);新的:
¥New:
const app = new Application();
await app.init({ view: document.createElement('canvas') });
document.body.appendChild(app.canvas);NineSlicePlane
更名为NineSliceSprite
¥
NineSlicePlane
renamed toNineSliceSprite
SCALE_MODES
替换为ScaleMode
字符串¥
SCALE_MODES
replaced withScaleMode
stringsSCALE_MODES.NEAREST
->'nearest'
,SCALE_MODES.LINEAR
->'linear'
,
WRAP_MODES
替换为WrapMode
字符串¥
WRAP_MODES
replaced withWrapMode
stringsWRAP_MODES.CLAMP
->'clamp-to-edge'
,WRAP_MODES.REPEAT
->'repeat'
,WRAP_MODES.MIRRORED_REPEAT
->'mirror-repeat'
,
DRAW_MODES
替换为Topology
字符串¥
DRAW_MODES
replaced withTopology
stringsDRAW_MODES.POINTS
->'point-list'
,DRAW_MODES.LINES
->'line-list'
,DRAW_MODES.LINE_STRIP
->'line-strip'
,DRAW_MODES.TRIANGLES
->'triangle-list'
,DRAW_MODES.TRIANGLE_STRIP
->'triangle-strip'
,
构造函数已很大程度上更改为接受对象而不是多个参数
¥Constructors have largely been changed to accept objects instead of multiple arguments
老的:
¥Old:
const blurFilter = new BlurFilter(8, 4, 1, 5);
const displacementFilter = new DisplacementFilter(sprite, 5);
const meshGeometry = new MeshGeometry(vertices, uvs, index);
const mesh = new Mesh(geometry, shader, state, drawMode);
const plane = new PlaneGeometry(width, height, segWidth, segHeight);
const nineSlicePlane = new NineSlicePlane(texture, leftWidth, topHeight, rightWidth, bottomHeight);
const tileSprite = new TileSprite(texture, width, height);
const text = new Text('Hello World', style);
const bitmapText = new BitmapText('Hello World', style);
const htmlText = new HTMLText('Hello World', style);新的:
¥New:
const blurFilter = new BlurFilter({
blur: 8,
quality: 4,
resolution: 1,
kernelSize: 5,
});
const displacementFilter = new DisplacementFilter({
sprite,
scale: 5,
});
const meshGeometry = new MeshGeometry({
positions: vertices,
uvs,
indices: index,
topology: 'triangle-list';
shrinkBuffersToFit: boolean;
});
const mesh = new Mesh({
geometry
shader
texture
});
const plane = new PlaneGeometry({
width,
height,
verticesX: segWidth,
verticesY: segHeight,
});
const nineSliceSprite = new NineSliceSprite({
texture,
leftWidth,
topHeight,
rightWidth,
bottomHeight,
});
const tileSprite = new TileSprite({
texture,
width,
height,
});
const text = new Text({
text: 'Hello World',
style,
});
const bitmapText = new BitmapText({
text:'Hello World',
style,
});
const htmlText = new HTMLText({
text:'Hello World',
style,
});container.name
现在是container.label
¥
container.name
is nowcontainer.label
4. 资源
¥ Resources