DOCSEARCHbyAlgolia
Submit Docs

vue3-pixi

repository·main·Indexed 43 days ago

https://github.com/hairyf/vue3-pixi

A custom Vue 3 renderer for PixiJS that allows developers to build applications using Vue's component-based architecture and declarative templates. It supports all PixiJS objects, including Filter, Container, Sprite, Graphics, and Text, and provides utilities like the <assets> component, onTick composable, and a dedicated Nuxt module (vue3-pixi-nuxt) for auto-imports and client-side safety.

Tokens
56.9K
Snippets
211
Records
275
Agent score
55%

What's inside vue3-pixi

  1. Overview of Vue3 Pixi features

    main

    Vue3 Pixi is a Vue 3 renderer for PixiJS that allows you to develop Pixi applications using Vue's declarative syntax and features. Key capabilities include:

    • Vue Integration: Create PixiJS objects through the Vue renderer, leveraging all standard Vue features.
    • Transition Support: Provides transition effects specifically for PixiJS objects.
    • Full PixiJS Object Support: Supports all built-in PixiJS objects such as Filter, Container, Sprite, Graphics, Text, and more.
    • Automatic Texture Loading: You can specify texture paths directly in templates, and they will load automatically.
    • Event Support: Supports all events emitted by PixiJS objects.
    • TypeScript Support: The library is written in TypeScript and provides full type definitions.
    • Flexible Deployment: Can be used with or without a bundler (via CDN).

  2. Overview of Vue 3 Pixi

    main

    Vue 3 Pixi is a lightweight and flexible library that provides a Custom Vue Renderer for PixiJS. Instead of creating HTML elements, it creates PixiJS objects, allowing you to build PixiJS applications using Vue's declarative template syntax and reactivity system.

    Key Features:

    • Full PixiJS Support: Supports all PixiJS objects including Filter, Container, Sprite, Graphics, Text, etc.
    • Texture Loading: Supports specifying texture paths directly in templates to load texture objects.
    • Event Support: All events emitted by PixiJS objects are supported.
    • Asset Management: Includes an Assets component for bundling assets.
    • Composition Utilities: Offers feature-rich utilities like onTick.
    • Transitions: Supports creating transition effects using the Transition component.

  3. Use the MeshPlane element

    main

    The MeshPlane element creates a mesh that renders a texture mapped to a plane. It features configurable vertex density, making it ideal for creating distortion effects, bent surfaces, and animated deformations. You can control the resolution of the mesh by adjusting the number of vertices along the X and Y axes.

    <template>
  <MeshPlane :texture="myTexture" :vertices-x="20" :vertices-y="20" />
</template>

  4. Map props to PixiJS elements

    main

    In vue3-pixi, props on custom elements are mapped directly to the corresponding properties on PixiJS objects. Most properties can be used with a kebab-case naming convention (e.g., :scale-x) or by using the x/y suffix for coordinate-based properties.

    <container :scale-x="10" :skew-y="0.5" />

  5. Use RenderLayer to decouple render order from scene graph

    main

    The RenderLayer component creates a PixiJS RenderLayer, which allows you to control the visual layering of elements independently from their logical parent-child relationships in the scene graph. This is useful for rendering elements (like UI or HUDs) on top of other content even if they are logically nested deep within a different part of the scene tree.

    To use it, place a <render-layer /> component in your template and pass its reference to the parent-render-layer attribute of the child element you want to re-layer.

    <script setup lang="ts">
import { ref } from 'vue'

const uiLayer = ref()
</script>

<template>
  <!-- Create a layer that renders on top -->
  <render-layer ref="uiLayer" />

  <container>
    <!-- This sprite is a child of the container in the scene graph,
         but renders in the uiLayer visually -->
    <sprite
      :texture="texture"
      :parent-render-layer="uiLayer"
    />
  </container>
</template>

  6. Configure transition easing with TransitionPresets

    main

    By default, all transitions are linear. You can customize the easing of a transition using cubic-bezier curves. The TransitionPresets constant provides several pre-defined easing functions.

    Available presets include:

    • linear
    • easeInSine, easeOutSine, easeInOutSine
    • easeInQuad, easeOutQuad, easeInOutQuad
    • easeInCubic, easeOutCubic, easeInOutCubic
    • easeInQuart, easeOutQuart, easeInOutQuart
    • easeInQuint, easeOutQuint, easeInOutQuint
    • easeInExpo, easeOutExpo, easeInOutExpo
    • easeInCirc, easeOutCirc, easeInOutCirc
    • easeInBack, easeOutBack, easeInOutBack

    You can also provide a custom function for more complex easing requirements.

  7. Use the Container component

    main

    The Container is the base component for all elements that render to the screen in vue3-pixi. It serves as a parent for other components like Sprite or Graphics.

    When you render child components inside a Container (using the default slot), their coordinates become local to that parent Container. This allows you to group elements and move, scale, or rotate them as a single unit.

  8. Use the `<assets>` component to preload resources

    main

    The <assets> component preloads assets (textures, audio, etc.) using the PixiJS Assets API. It manages the loading lifecycle and provides slots to handle different loading states.

    Loading States (Slots)

    • default: Rendered after loading completes. The slot provides a data object containing the loaded assets.
    • fallback: Rendered while assets are loading. Provides a progress number (0 to 1).
    • error: Rendered if asset loading fails. Provides an error object.

    The default slot will not render until all assets have finished loading.

    <assets>
  <template #fallback="{ progress }">
    <div>Loading... {{ progress * 100 }}%</div>
  </template>
  <template #default="{ data }">
    <!-- Use loaded assets here -->
    <sprite :texture="data.someTexture" />
  </template>
  <template #error="{ error }">
    <div>Error loading assets: {{ error.message }}</div>
  </template>
</assets>

  9. Use GraphicsContext to share drawing instructions

    main

    A GraphicsContext holds shareable drawing instructions that can be reused across multiple Graphics instances. Instead of duplicating drawing commands for every object, you define the instructions once in a graphics-context component and pass that context to multiple graphics components via the context prop. This is highly efficient for repeated shapes, texture-based fills, and reducing GPU overhead.

    <script setup lang="ts">
import { ref } from 'vue'

const sharedCtx = ref()
</script>

<template>
  <!-- Define shared drawing instructions -->
  <graphics-context
    ref="sharedCtx"
    @effect="(ctx) => ctx.rect(0, 0, 50, 50).fill('red')"
  />

  <!-- Reuse the context across multiple Graphics instances -->
  <graphics :context="sharedCtx" :x="0" :y="0" />
  <graphics :context="sharedCtx" :x="100" :y="0" />
  <graphics :context="sharedCtx" :x="200" :y="0" />
</template>

  10. Use ParticleContainer for high-performance sprite rendering

    main

    The ParticleContainer is a highly optimized container designed for rendering large numbers of sprites.

    Important Limitations:

    • It does not support advanced features like masking, filters, or nested containers.
    • Imperative Usage Only: In PixiJS v8, you cannot use declarative <particle> children inside <particle-container>. You must manage particles imperatively using the addParticle() and removeParticle() methods via a component ref.

    To use it, create Particle instances from pixi.js and add them to the container instance.

    <script setup>
import { Particle, Texture } from 'pixi.js'
import { ref } from 'vue'
import { onTick } from 'vue3-pixi'

const containerRef = ref()

function onEffect(pc) {
  const particles = Array.from({ length: 100 }, () => {
    const p = new Particle({ texture: Texture.from('mySprite') })
    p.x = Math.random() * 400
    p.y = Math.random() * 300
    return p
  })
  pc.addParticle(...particles)
}

onTick(() => {
  if (!containerRef.value)
    return
  for (const p of containerRef.value.particleChildren) {
    p.y += 1
  }
})
</script>

<template>
  <particle-container ref="containerRef" @effect="onEffect" />
</template>

  12. Use BitmapText for high-performance text rendering

    main

    The BitmapText component renders text using pre-generated bitmap fonts. This is significantly faster than the standard Text component because textures are pre-loaded, meaning changing the text content has minimal performance impact.

    Key considerations:

    • Line Breaks: Use \n, \r, or \r\n to split text into multiple lines.
    • Font Loading: A BitmapText can only be successfully created once the required font is loaded.
    • Character Sets: While efficient, using non-Latin character sets (like CJK) can be impractical due to the massive number of required textures.
    • Font Generation: You can use auto-generated fonts via PixiJS, or provide .fnt files from tools like BMFont or BMGlyph. For vector-like scaling, consider using SDF, MSDF, or MTSDF fonts.