SveltePixi

If you are extending PIXI.TilingSprite with a custom subclass, you must pass your custom instance to the instance prop.

Failure to do so will result in a base PIXI.TilingSprite being created and unsafely cast to your subclass type, which causes runtime errors when accessing subclass-specific properties or methods.

Correct Pattern:

class MyTilingSprite extends PIXI.TilingSprite {
  myCustomMethod() { ... }
}

const sprite = new MyTilingSprite()
// Pass the custom instance to the component
<TilingSprite instance={sprite} />

If you are extending PIXI.Container with a custom subclass, you must provide the instance prop with your custom instance.

Because of TypeScript limitations, failing to provide the instance prop will result in a base PIXI.Container being created and unsafely cast to your subclass type. This leads to runtime errors when accessing subclass-specific properties or methods that do not exist on the base instance.

class MyContainer extends PIXI.Container {
  myCustomMethod() { ... }
}

const container = new MyContainer()
<Container instance={container} />

If you are extending PIXI.Graphics with a custom subclass, you must provide the instance prop with your custom instance.

Failure to do so will cause the component to create a base PIXI.Graphics instance and unsafely cast it to your subclass type. This leads to runtime errors when attempting to access methods or properties unique to your subclass. This is a known limitation due to TypeScript's handling of generic types in this context.

class MyGraphics extends PIXI.Graphics {
  myCustomMethod() { ... }
}

const graphics = new MyGraphics()
// You MUST pass the custom instance to the component
<Graphics instance={graphics} />

If you are extending PIXI.PerspectiveMesh with your own subclass, you must provide the instance prop with your custom instance.

Due to TypeScript limitations, if you omit the instance prop, svelte-pixi will create a base PIXI.PerspectiveMesh and unsafely cast it to your subclass type. This will lead to runtime errors when you attempt to access properties or methods specific to your subclass. This requirement applies only when using subclasses; using the base PIXI.PerspectiveMesh type does not require this.

class MyPerspectiveMesh extends PIXI.PerspectiveMesh {
  myCustomMethod() { ... }
}

const mesh = new MyPerspectiveMesh(texture)
<PerspectiveMesh instance={mesh} />

In Pixi v8, textures must be loaded before they are used. You can manage this in svelte-pixi using several patterns:

1. Using AssetsLoader (Recommended)

Wrap your components in an AssetsLoader to ensure assets are ready before the child components render.

<AssetsLoader assets={['/my-texture.png']}>
  <Sprite texture={'/my-texture.png'} />
</AssetsLoader>

2. Using PIXI.Assets.load directly

Use a standard Svelte {#await} block to load the texture manually.

{#await PIXI.Assets.load('/my-texture.png') then texture}
  <Sprite {texture} />
{/await}

3. Combining AssetsLoader with PIXI.Texture.from

<AssetsLoader assets={['/my-texture.png']}>
  <Sprite texture={PIXI.Texture.from('/my-texture.png')} />
</AssetsLoader>

The Renderer component is an alternative to the Application component. It allows you to use a custom PIXI.Renderer instance, but unlike Application, it will not automatically start a render loop or create a root container. You must manage the render loop (e.g., using a Ticker) and the root container (the "stage") yourself.

By default, Renderer calls PIXI.autoDetectRenderer to determine the instance. This is an asynchronous operation that triggers the oninit (Svelte 5) or on:init (Svelte 4) callback when complete.

<script>
  import { Renderer, Container, Ticker } from 'svelte-pixi'
  let renderer
  let stage
</script>

<Renderer bind:instance={renderer} width={400} height={400}>
  <Ticker ontick={() => renderer.render(stage)}>
    <Container bind:instance={stage}>
      <!-- Your PIXI content here -->
    </Container>
  </Ticker>
</Renderer>

If you are extending PIXI.Application with a custom subclass, you MUST manually create the instance and pass it to the instance prop.

Warning: If you do not provide the instance prop, the component will create a base PIXI.Application and unsafely cast it to your subclass type. This will cause runtime errors when accessing subclass-specific properties or methods.

Correct Pattern:

class MyApp extends PIXI.Application {
  myCustomMethod() { ... }
}

// 1. Create your instance first
const app = new MyApp()

// 2. Pass it to the component via the instance prop
<Application instance={app} />

If you are extending PIXI.Text with a custom subclass, you must provide the instance prop with your custom instance.

Because of TypeScript limitations, failing to provide the instance prop will cause the component to create a base PIXI.Text and unsafely cast it to your subclass type. This leads to runtime errors when attempting to access methods or properties unique to your subclass.

Correct pattern for subclasses:

class MyText extends PIXI.Text {
  myCustomMethod() { ... }
}

const text = new MyText()
// Pass the custom instance to the component
<Text instance={text} />

If you are extending PIXI.Mesh with a custom subclass, you must provide the instance prop with your custom instance.

If you omit the instance prop, svelte-pixi will create a base PIXI.Mesh and unsafely cast it to your subclass type. This leads to runtime errors when attempting to access properties or methods unique to your subclass.

Correct pattern for subclasses:

1. Instantiate your custom class manually.
2. Pass that instance to the instance prop of the <Mesh /> component.

class MyMesh extends PIXI.Mesh {
  myCustomMethod() { ... }
}

const mesh = new MyMesh(geometry, shader)
<Mesh instance={mesh} />