Feat: v8 guides update (#74)

* Restructuring: Move Tutorial and Playground into the Docusaurus Docs Structure * Fix main container styling in coding mode for full-screen * Chore: Website Restructuring * Updated content generation scripts * Minor fixes * Chore: Website Versioning * Chore: Create v7.x Snapshot + Make Working Docs the Pre-Release v8 * Versions page fixes * Tweaked Sandpack Dependencies Config * Hotfix: Restructure Source Examples and Tutorial * Type hotfix * Pre-Release v8 Examples Update * Added back parcel-bundler for all pixi versions * More examples updated * More examples update * Updated/Added/Removed more examples * Reverted conditioned babel core dev dependency * Pre-update Shader examples * Revert Ticker.shared back to app.ticker * Lint fix * Chore: Upgrade Working Docs to use PixiJS v8.0.0-rc.1 * Remove v8.0.0-rc (old) content * Simplify source versioning for examples and tutorials * Bump up to v8.0.0-rc.2 * Type fix * Add ghtoken ignore * Fix Versioned Links * Upgrade to RC4 * Chore: Website Versioning Scripts (#52) * Chore: Website Versioning * Versions page fixes * Add `Working with Content` Section on README (#54) * Added Working with Content Section on README * Quick adjustment --------- Co-authored-by: Baz Utsahajit <[email protected]> * Chore: Create v7.x Snapshot + Make Working Docs the Pre-Release v8 (#53) * Chore: Create v7.x Snapshot + Make Working Docs the Pre-Release v8 * Tweaked Sandpack Dependencies Config * Hotfix: Restructure Source Examples and Tutorial (#55) * Hotfix: Restructure Source Examples and Tutorial * Type hotfix * Added back parcel-bundler for all pixi versions * Reverted conditioned babel core dev dependency * Chore: Upgrade Working Docs to use PixiJS v8.0.0-rc.2 and Simplify examples and tutorial source versioning (#60) * Chore: Upgrade Working Docs to use PixiJS v8.0.0-rc.1 * Simplify source versioning for examples and tutorials * Bump up to v8.0.0-rc.2 * Type fix * Add ghtoken ignore * Fix Versioned Links * Upgrade to RC4 * More Assorted fixes --------- Co-authored-by: Baz Utsahajit <[email protected]> --------- Co-authored-by: Baz Utsahajit <[email protected]> --------- Co-authored-by: Baz Utsahajit <[email protected]> --------- Co-authored-by: Baz Utsahajit <[email protected]> * Upgrade to RC4 * No footer on example pages * Update v7.x versioned docs * Use semver to pick the latest version instead of relying on the latest tag * Update Versions Page + Add devs and unmaintained versions * More readme update * Allowing user to customize pixi version label * Add the ability to manage generic snapshots * add v8 migration guide * Combine gitignores into the root one * Updated Mesh and Shaders Section * Remove Nested Boundary with Projection Example * Remove 7.3.2 * Update generate example docs script to fix sidebar names * Add ability to add extra packages to the playground * Split out Triangle example into multiple files * Update examples config to allow multiple files * Adapt syntax highlighting on tab switches * Extract multi-file handling into a useCodeSource function * Split long examples into multiple files * Allow active file override with '$' * Editor tutorial code change fix * Allow extra packages on tutorial + add babel plugin * Resolve conflict * Fix editor styling and persisting playground changes * Updated editor now keep persisted changes on all visible files + Fix tabs overflowing * Tabs style update and fixes * Upgrade to RC5 * Remove unused types and functions * Fix tab scroll * Fix texture url * Lint Fix * Remove ShaderToy Filter Render Texture Example * Update Instanced Geometry + Multipass Mesh Codes * Bump up to RC6 * Uncomment in instanced geometry * Fix uniform float type * fix up the custom shaders for gl * Upgrade to RC7 * Updated v7.x to latest * add more examples for v8 * v8 launch post * remove unused images * PixiJS not Pixi * missed one * update based on feedback * added final migration for v8 * typo * typos * typo * final tweak * guide updates * update * many fixes * added final migration for v8 (#73) * added final migration for v8 * typo * typos * typo * final tweak * feedback * undo versions * remove blog * update current --------- Co-authored-by: Baz Utsahajit <[email protected]> Co-authored-by: bbazukun123 <[email protected]> Co-authored-by: Zyie <[email protected]>
pixijs · Mar 5, 2024 · 01f14ea · 01f14ea
1 parent 8d462b6
commit 01f14ea
Show file tree

Hide file tree

Showing 22 changed files with 491 additions and 276 deletions.
diff --git a/blog/2024-03-01-pixi-v8-launches.md b/blog/2024-03-01-pixi-v8-launches.md
@@ -39,8 +39,8 @@ We're incredibly proud of PixiJS v8 and eager to share the improvements and new
 
 ## 🔗 Quick links
 - The new Docs for v8 can be found here [LINK TO DOCS]
-- [Migration](/next/guides/migrations/v8)
-- [Examples](/next/examples)
+- [Migration](/guides/migrations/v8)
+- [Examples](/examples)
 - [Open Games](https://github.com/pixijs/open-games)
 
 ---
@@ -197,7 +197,7 @@ myContainer.blendMode = 'color-burn` // easy!
 
 ```
 
-For more information on these graphics upgrades and guidance on how to adapt to the enhanced Graphics API, please refer to the [migration guide](/next/guides/migrations/v8), or why not jump in and play with some [examples](next/examples/graphics/simple).
+For more information on these graphics upgrades and guidance on how to adapt to the enhanced Graphics API, please refer to the [migration guide](/guides/migrations/v8), or why not jump in and play with some [examples](examples/graphics/simple).
 
 #### 📝 Text Upgrades
 

diff --git a/docs/guides/advanced/render-groups.md b/docs/guides/advanced/render-groups.md
@@ -0,0 +1,45 @@
+# Render Groups
+
+## Understanding RenderGroups in PixiJS
+
+As you delve deeper into PixiJS, especially with version 8, you'll encounter a powerful feature known as RenderGroups. Think of RenderGroups as specialized containers within your scene graph that act like mini scene graphs themselves. Here's what you need to know to effectively use Render Groups in your projects:
+
+### What Are Render Groups?
+
+Render Groups are essentially containers that PixiJS treats as self-contained scene graphs. When you assign parts of your scene to a Render Group, you're telling PixiJS to manage these objects together as a unit. This management includes monitoring for changes and preparing a set of render instructions specifically for the group. This is a powerful tool for optimizing your rendering process.
+
+### Why Use Render Groups?
+
+The main advantage of using Render Groups lies in their optimization capabilities. They allow for certain calculations, like transformations (position, scale, rotation), tint, and alpha adjustments, to be offloaded to the GPU. This means that operations like moving or adjusting the Render Group can be done with minimal CPU impact, making your application more performance-efficient.
+
+In practice, you're utilizing Render Groups even without explicit awareness. The root element you pass to the render function in PixiJS is automatically converted into a RenderGroup as this is where its render instructions will be stored. Though you also have the option to explicitly create additional RenderGroups as needed to further optimize your project.
+
+This feature is particularly beneficial for:
+
+- **Static Content:** For content that doesn't change often, a Render Group can significantly reduce the computational load on the CPU. In this case static refers to the scene graph structure, not that actual values of the PixiJS elements inside it (eg position, scale of things).
+- **Distinct Scene Parts:** You can separate your scene into logical parts, such as the game world and the HUD (Heads-Up Display). Each part can be optimized individually, leading to overall better performance.
+
+### Examples
+
+```ts
+const myGameWorld = new Container({
+  isRenderGroup:true
+})
+
+const myHud = new Container({
+  isRenderGroup:true
+})
+
+scene.addChild(myGameWorld, myHud)
+
+renderer.render(scene) // this action will actually convert the scene to a render group under the hood
+```
+
+Check out the [container example] (../../examples/basic/container).
+
+### Best Practices
+
+- **Don't Overuse:** While Render Groups are powerful, using too many can actually degrade performance. The goal is to find a balance that optimizes rendering without overwhelming the system with too many separate groups. Make sure to profile when using them. The majority of the time you won't need do use them at all!
+- **Strategic Grouping:** Consider what parts of your scene change together and which parts remain static. Grouping dynamic elements separately from static elements can lead to performance gains.
+
+By understanding and utilizing Render Groups, you can take full advantage of PixiJS's rendering capabilities, making your applications smoother and more efficient. This feature represents a powerful tool in the optimization toolkit offered by PixiJS, enabling developers to create rich, interactive scenes that run smoothly across different devices.
diff --git a/docs/guides/basics/architecture-overview.md b/docs/guides/basics/architecture-overview.md
@@ -8,18 +8,16 @@ Before we get into how the code is layed out, let's talk about where it lives.
 
 ## The Components
 
-PixiJS is a modular rendering engine.  Each task required for generating, updating and displaying content is broken out into its own component.  Not only does this make the code cleaner, it allows for greater extensibility.  Additionally, with the use of the [PixiJS Customize tool](https://pixijs.io/customize/), it's possible to build a custom PixiJS file containing only the subset of features your project needs, saving download size.
-
 Here's a list of the major components that make up PixiJS.  Note that this list isn't exhaustive.  Additionally, don't worry too much about how each component works.  The goal here is to give you a feel for what's under the hood as we start exploring the engine.
 
 ### Major Components
 
 | Component                                  | Description                                                                                                                                                                                            |
 | ---                                        | ---                                                                                                                                                                                                    |
-| **Renderer** `@pixi/core`                  | The core of the PixiJS system is the renderer, which displays the scene graph and draws it to the screen.  The default renderer for PixiJS is based on WebGL under the hood.                           |
-| **Container** `@pixi/display`              | Main display object which creates a scene graph: the tree of renderable objects to be displayed, such as sprites, graphics and text. See [Scene Graph](scene-graph) for more details.             |
-| **Loader** `@pixi/loader`                  | The loader system provides tools for asynchronously loading resources such as images and audio files.                                                                                                  |
-| **Ticker** `@pixi/ticker`                  | Tickers provide periodic callbacks based on a clock.  Your game update logic will generally be run in response to a tick once per frame.  You can have multiple tickers in use at one time.            |
-| **Application** `@pixi/app`                | The Application is a simple helper that wraps a Loader, Ticker and Renderer into a single, convenient easy-to-use object. Great for getting started quickly, prototyping and building simple projects. |
-| **Interaction** `@pixi/interaction`        | PixiJS supports both touch and mouse-based interaction - making objects clickable, firing hover events, etc.                                                                                           |
-| **Accessibility** `@pixi/accessibility`    | Woven through our display system is a rich set of tools for enabling keyboard and screen-reader accessibility.                                                                                         |
+| **Renderer**                  | The core of the PixiJS system is the renderer, which displays the scene graph and draws it to the screen. PixiJS will automatically determine whether to provide you the WebGPU or WebGL renderer under the hood.                           |
+| **Container**             | Main scene object which creates a scene graph: the tree of renderable objects to be displayed, such as sprites, graphics and text. See [Scene Graph](scene-graph) for more details.             |
+| **Assets**                 | The Asset system provides tools for asynchronously loading resources such as images and audio files.                                                                                                  |
+| **Ticker**                  | Tickers provide periodic callbacks based on a clock.  Your game update logic will generally be run in response to a tick once per frame.  You can have multiple tickers in use at one time.            |
+| **Application**                | The Application is a simple helper that wraps a Loader, Ticker and Renderer into a single, convenient easy-to-use object. Great for getting started quickly, prototyping and building simple projects. |
+| **Events**         | PixiJS supports pointer-based interaction - making objects clickable, firing hover events, etc.                                                                                           |
+| **Accessibility**   | Woven through our display system is a rich set of tools for enabling keyboard and screen-reader accessibility.                                                                                         |
diff --git a/docs/guides/basics/getting-started.md b/docs/guides/basics/getting-started.md
@@ -31,7 +31,7 @@ OK!  With those notes out of the way, let's get started.  There are only a few s
 * Create an HTML file
 * Serve the file with a web server
 * Load the PixiJS library
-* Create an [Application](https://pixijs.download/release/docs/PIXI.Application.html)
+* Create an [Application](https://pixijs.download/release/docs/app.Application.html)
 * Add the generated view to the DOM
 * Add an image to the stage
 * Write an update loop
@@ -81,27 +81,28 @@ Loading the library doesn't do much good if we don't *use* it, so the next step
 
 ```html
 <script>
-  let app = new PIXI.Application({ width: 640, height: 360 });
+  const app = new PIXI.Application();
+  await app.init({ width: 640, height: 360 })
 </script>
 ```
 
-What we're doing here is adding a JavaScript code block, and in that block creating a new PIXI.Application instance. [Application](https://pixijs.download/release/docs/PIXI.Application.html) is a helper class that simplifies working with PixiJS.  It creates the renderer, creates the stage, and starts a ticker for updating.  In production, you'll almost certainly want to do these steps yourself for added customization and control - we'll cover doing so in a later guide.  For now, the Application class is a perfect way to start playing with PixiJS without worrying about the details.
+What we're doing here is adding a JavaScript code block, and in that block creating a new PIXI.Application instance. [Application](https://pixijs.download/release/docs/app.Application.html) is a helper class that simplifies working with PixiJS.  It creates the renderer, creates the stage, and starts a ticker for updating.  In production, you'll almost certainly want to do these steps yourself for added customization and control - we'll cover doing so in a later guide.  For now, the Application class is a perfect way to start playing with PixiJS without worrying about the details. The `Application` class also has a method `init` that will initialize the application with the given options. This method is asynchronous, so we use the `await` keyword to wait for it to complete. This is because PixiJS uses WebGPU or WebGL under the hood, and the former API asynchronous.
 
-### Adding the View to the DOM
+### Adding the Canvas to the DOM
 
 When the PIXI.Application class creates the renderer, it builds a Canvas element that it will render *to*.  In order to see what we draw with PixiJS, we need to add this Canvas element to the web page's DOM.  Append the following line to your page's script block:
 
 ```javascript
-  document.body.appendChild(app.view);
+  document.body.appendChild(app.canvas);
 ```
 
-This takes the view created by the application (the Canvas element) and adds it to the body of your page.
+This takes the canvas created by the application (the Canvas element) and adds it to the body of your page.
 
 ### Creating a Sprite
 
 So far all we've been doing is prep work.  We haven't actually told PixiJS to draw anything.  Let's fix that by adding an image to be displayed.
 
-There are a number of ways to draw images in PixiJS, but the simplest is by using a [Sprite](https://pixijs.download/release/docs/PIXI.Sprite.html).  We'll get into the details of how the scene graph works in a later guide, but for now all you need to know is that PixiJS renders a hierarchy of [DisplayObjects](https://pixijs.download/release/docs/PIXI.DisplayObject.html).  A Sprite is a type of DisplayObject that wraps a loaded image resource to allow drawing it, scaling it, rotating it, and so forth.
+There are a number of ways to draw images in PixiJS, but the simplest is by using a [Sprite](https://pixijs.download/release/docs/scene.Sprite.html).  We'll get into the details of how the scene graph works in a later guide, but for now all you need to know is that PixiJS renders a hierarchy of [Containers](https://pixijs.download/release/docs/scene.Container.html).  A Sprite is a type of Container that wraps a loaded image resource to allow drawing it, scaling it, rotating it, and so forth.
 
 Before PixiJS can render an image, it needs to be loaded.  Just like in any web page, image loading happens asynchronously.  We'll talk a lot more about resource loading in later guides.  For now, we can use a helper method on the PIXI.Sprite class to handle the image loading for us:
 
@@ -114,7 +115,7 @@ Before PixiJS can render an image, it needs to be loaded.  Just like in any web
 
 ### Adding the Sprite to the Stage
 
-Finally, we need to add our new sprite to the stage.  The stage is simply a [Container](https://pixijs.download/release/docs/PIXI.Container.html) that is the root of the scene graph.  Every child of the stage container will be rendered every frame.  By adding our sprite to the stage, we tell PixiJS's renderer we want to draw it.
+Finally, we need to add our new sprite to the stage.  The stage is simply a [Container](https://pixijs.download/release/docs/scene.Container.html) that is the root of the scene graph.  Every child of the stage container will be rendered every frame.  By adding our sprite to the stage, we tell PixiJS's renderer we want to draw it.
 
 ```javascript
   app.stage.addChild(sprite);
@@ -129,9 +130,9 @@ While you _can_ use PixiJS for static content, for most projects you'll want to
   let elapsed = 0.0;
   // Tell our application's ticker to run a new callback every frame, passing
   // in the amount of time that has passed since the last tick
-  app.ticker.add((delta) => {
+  app.ticker.add((ticker) => {
     // Add the time to our total elapsed time
-    elapsed += delta;
+    elapsed += ticker.deltaTime;
     // Update the sprite's X position based on the cosine of our elapsed time.  We divide
     // by 50 to slow the animation down a bit...
     sprite.x = 100.0 + Math.cos(elapsed/50.0) * 100.0;
@@ -155,17 +156,18 @@ Here's the whole thing in one place.  Check your file and make sure it matches i
   <body>
     <script>
       // Create the application helper and add its render target to the page
-      let app = new PIXI.Application({ width: 640, height: 360 });
-      document.body.appendChild(app.view);
+      const app = new PIXI.Application();
+      await app.init({ width: 640, height: 360 })
+      document.body.appendChild(app.canvas);
 
       // Create the sprite and add it to the stage
       let sprite = PIXI.Sprite.from('sample.png');
       app.stage.addChild(sprite);
 
       // Add a ticker callback to move the sprite back and forth
       let elapsed = 0.0;
-      app.ticker.add((delta) => {
-        elapsed += delta;
+      app.ticker.add((ticker) => {
+        elapsed += ticker.deltaTime;
         sprite.x = 100.0 + Math.cos(elapsed/50.0) * 100.0;
       });
     </script>

diff --git a/docs/guides/basics/render-loop.md b/docs/guides/basics/render-loop.md
@@ -28,7 +28,7 @@ A note about frame rates.  The render loop can't be run infinitely fast - drawin
 
 <!--For most projects, you can use the default settings for the Ticker object, which will ... (TODO: The docs are a bit unclear on what happens if you don't set a min/max FPS - confirm)-->
 
-In cases where you want to adjust that behavior, you can set the `minFPS` and `maxFPS` attributes on a Ticker to give PixiJS hints as to the range of tick speeds you want to support.  Just be aware that due to the complex environment, your project cannot _guarantee_ a given FPS.  Use the passed `delta` value in your ticker callbacks to scale any animations to ensure smooth playback.
+In cases where you want to adjust that behavior, you can set the `minFPS` and `maxFPS` attributes on a Ticker to give PixiJS hints as to the range of tick speeds you want to support.  Just be aware that due to the complex environment, your project cannot _guarantee_ a given FPS.  Use the passed `ticker.deltaTime` value in your ticker callbacks to scale any animations to ensure smooth playback.
 
 ## Custom Render Loops