Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
mattjennings committed Dec 6, 2023
1 parent 6679052 commit d0af50e
Show file tree
Hide file tree
Showing 12 changed files with 66 additions and 51 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Svelte Pixi
# SveltePixi

Create [PixiJS](https://www.pixijs.com) apps with Svelte.

Expand Down
26 changes: 14 additions & 12 deletions docs/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ export default defineConfig({
},
integrations: [
starlight({
title: 'Svelte Pixi',
title: 'SveltePixi',
customCss: ['./src/tailwind.css'],
expressiveCode: {
themes: [codeTheme],
Expand All @@ -46,27 +46,35 @@ export default defineConfig({
lang: 'en', // lang is required for root locales
},
},

tableOfContents: {
minHeadingLevel: 1,
maxHeadingLevel: 6,
},
sidebar: [
{
label: 'Getting Started',
collapsed: true,
autogenerate: {
directory: 'getting-started',
},
},
{
label: 'Releases',
autogenerate: {
directory: 'releases',
},
},
{
label: 'API',
items: [
{
label: 'Components',
collapsed: true,
autogenerate: {
directory: 'api/components',
},
},
{
label: 'Utilities',
collapsed: true,
autogenerate: {
directory: 'api/utilities',
},
Expand All @@ -93,17 +101,11 @@ export default defineConfig({
label: 'Reducing bundle size',
link: '/guides/reducing-bundle-size',
},
{
label: 'Migrations',
collapsed: true,
autogenerate: {
directory: 'guides/migrations',
},
},
],
},
{
label: 'Older Versions',
label: 'Older Documentation',
collapsed: true,
items: [
{
label: 'v0.1.3 (PixiJS v6)',
Expand Down
7 changes: 7 additions & 0 deletions docs/src/content/docs/404.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
title: '404'
editUrl: false
hero:
title: '404'
tagline: Page not found. Check the URL or try using the search bar.
---
2 changes: 1 addition & 1 deletion docs/src/content/docs/api/utilities/get-container.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: getContainer

Returns the context of the parent [Container](/docs/components/container) component.

Any Svelte Pixi component that renders something to the screen will use a Container, so this will return a Sprite, Graphics, etc. instance if the component is a child of one.
Any SveltePixi component that renders something to the screen will use a Container, so this will return a Sprite, Graphics, etc. instance if the component is a child of one.

```js
import { getContainer } from 'svelte-pixi'
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/api/utilities/track.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: track

Returns a writable store that gets updated during a low-priority tick. If there's no Ticker, it will run during the PIXI.Renderer's `postrender` event.

This is useful for watching a property on a PixiJS instance that is getting updated outside of the component (e.g. a physics system). It can also be used to [bind props](/docs/advanced/binding-props), as Svelte Pixi components don't support `bind:` syntax for instance properties.
This is useful for watching a property on a PixiJS instance that is getting updated outside of the component (e.g. a physics system). It can also be used to [bind props](/docs/advanced/binding-props), as SveltePixi components don't support `bind:` syntax for instance properties.

```svelte live
<script>
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/getting-started/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ sidebar:
order: 1
---

Svelte Pixi is a component library that allows you to write PixiJS applications declaratively in Svelte.
SveltePixi is a component library that allows you to write PixiJS applications declaratively in Svelte.

The easiest way to get started is to use one of the [example templates](https://github.com/mattjennings/svelte-pixi/tree/master/examples)

Expand Down
44 changes: 19 additions & 25 deletions docs/src/content/docs/getting-started/usage.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ sidebar:
order: 2
---

Svelte Pixi aims to match the PixiJS API as closely as possible without doing anything too magical.
SveltePixi aims to match the PixiJS API as closely as possible without doing anything too magical.
If you're familiar with PixiJS, you should feel right at home.

You can use the [Application](/docs/components/application) component to create and render a PixiJS application.
All Svelte Pixi components should be children of `Application`.
You can use the [Application](/docs/components/application) component to create and render a PixiJS application.
All SveltePixi components should be children of `Application`.

```svelte live props={{ bg: 'none' }} wrapper=/src/layouts/examples/wrappers/Empty.svelte
<script>
Expand All @@ -26,7 +26,7 @@ All Svelte Pixi components should be children of `Application`.
</Application>
```

Most Svelte Pixi components will correspond to the PixiJS class of the same name
Most SveltePixi components will correspond to the PixiJS class of the same name
(for example the `Text` component renders a [PIXI.Text](https://pixijs.download/dev/docs/PIXI.Text.html) instance).

## Textures
Expand Down Expand Up @@ -55,7 +55,7 @@ PixiJS will load the texture in the background and show it when it's ready - sim

## Preloading Assets

If you have a bunch of images or other resources, you may wish to show a loading screen
If you have a bunch of images or other resources, you may wish to show a loading screen
until all images have finished loading (rather than have them pop in one after another).

_Note: You may want to enable network throttling in your browser dev tools to actually see the loading screen - these are small images!_
Expand Down Expand Up @@ -99,12 +99,12 @@ _Note: You may want to enable network throttling in your browser dev tools to ac
</Application>
```

You can have multiple AssetsLoader components as well, which is useful
You can have multiple AssetsLoader components as well, which is useful
if you want to render a fallbacks at a component-level instead.

## Ticker

A [Ticker](/docs/components/ticker) runs an update loop for the application.
A [Ticker](/docs/components/ticker) runs an update loop for the application.
The `Application` component will create one automatically, which means child
components can hook into the loop with `onTick`.

Expand Down Expand Up @@ -138,8 +138,8 @@ components can hook into the loop with `onTick`.

## Accessing PixiJS Instances

Most Svelte Pixi components have an `instance` prop that
contains the underlying PixiJS instance. It's akin to the `this` prop for HTML elements,
Most SveltePixi components have an `instance` prop that
contains the underlying PixiJS instance. It's akin to the `this` prop for HTML elements,
so you can bind to it if you need to access it.

```svelte live {5,14}
Expand All @@ -150,24 +150,18 @@ so you can bind to it if you need to access it.
let text
onMount(() => {
// manually set property on the PIXI.Text instance
// manually set property on the PIXI.Text instance
text.style.fill = '#00ff00'
})
</script>
<Text
bind:instance={text}
x={360}
y={200}
text="Hello World"
anchor={0.5}
/>
<Text bind:instance={text} x={360} y={200} text="Hello World" anchor={0.5} />
```

## Using a Custom Instance

The `instance` prop also lets you pass down a custom PixiJS class
that you've instantiated yourself. This is particularly useful
The `instance` prop also lets you pass down a custom PixiJS class
that you've instantiated yourself. This is particularly useful
if you have a custom class (whether that be your own or from a third-party library).

```svelte live {14}
Expand All @@ -183,11 +177,11 @@ if you have a custom class (whether that be your own or from a third-party libra
}
</script>
<Text
instance={new GreenText()}
x={360}
y={200}
text="Hello World"
anchor={0.5}
<Text
instance={new GreenText()}
x={360}
y={200}
text="Hello World"
anchor={0.5}
/>
```
6 changes: 3 additions & 3 deletions docs/src/content/docs/guides/binding-props.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
title: Binding Props
---

There are times when the underlying PixiJS instance of a component gets updated externally (e.g, a physics system that applies forces on collision). In such a scenario, it would be helpful to bind our component props to the instance properties so that they are in sync. However, the `bind:` syntax will have no effect for instance-related properties on Svelte Pixi components (such as `x` or `y`) . This is to improve performance as the components would have to sync all props all the time regardless if they are bound, causing a large performance hit.
There are times when the underlying PixiJS instance of a component gets updated externally (e.g, a physics system that applies forces on collision). In such a scenario, it would be helpful to bind our component props to the instance properties so that they are in sync. However, the `bind:` syntax will have no effect for instance-related properties on SveltePixi components (such as `x` or `y`) . This is to improve performance as the components would have to sync all props all the time regardless if they are bound, causing a large performance hit.

Instead, Svelte Pixi provides a [track](/docs/utilities/track) utility function that will allow you to achieve similar behaviour. It returns a writable store that updates on every tick with the passed in function. We can use this to grab instance values and pass them back down as props (effectively creating a bind).
Instead, SveltePixi provides a [track](/docs/utilities/track) utility function that will allow you to achieve similar behaviour. It returns a writable store that updates on every tick with the passed in function. We can use this to grab instance values and pass them back down as props (effectively creating a bind).

```svelte live
<script>
Expand All @@ -28,7 +28,7 @@ Instead, Svelte Pixi provides a [track](/docs/utilities/track) utility function
time += delta * 0.02
instance.x = 360 + Math.cos(time) * 50
instance.y = 200 + Math.sin(time) * 50
})
})
</script>
<Graphics
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/optimizing-performance.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ If you are using the `Renderer` component, see [this example](/docs/components/r

### Triggering Renders Manually

Every Svelte Pixi component will automatically trigger renders when they are updated when rendering on demand. If you are mutating Pixi instances directly or adding functionality to a base component you will need to mark that an update is required manually.
Every SveltePixi component will automatically trigger renders when they are updated when rendering on demand. If you are mutating Pixi instances directly or adding functionality to a base component you will need to mark that an update is required manually.

```svelte
<script>
Expand Down
10 changes: 5 additions & 5 deletions docs/src/content/docs/guides/reducing-bundle-size.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Reducing Bundle Size
---

`pixi.js` is about [226kb minified + gzipped](https://bundlephobia.com/package/pixi.js@7.3.2) (as of v7.3.2).
`pixi.js` is about [226kb minified + gzipped](https://bundlephobia.com/package/pixi.js@7.3.2) (as of v7.3.2).
If you're only using a few features this may be a lot more than you need.

With a modern bundler it is possible to create your own pixi.js file with only the features you need. This
Expand All @@ -13,7 +13,7 @@ guide will show you how to do it using [Vite](https://vitejs.dev/) as that is th
The `pixi.js` package is just a collection of various `@pixi/*` packages. If we look at their [package.json](https://github.com/pixijs/pixijs/blob/main/bundles/pixi.js/package.json),
we can see which ones we might want to install for ourselves.

I've picked out a few below. You can add/remove as necessary, but note that if any Svelte Pixi component
I've picked out a few below. You can add/remove as necessary, but note that if any SveltePixi component
relies on the package you'll get an error. (For example, if you remove `@pixi/sprite` you'll get an error
when using `<Sprite />`.)

Expand Down Expand Up @@ -50,7 +50,7 @@ npm install @pixi/accessibility @pixi/app @pixi/assets @pixi/basis @pixi/compres

## Aliasing

In order for Svelte Pixi to make use of this custom file we'll need to create an alias.
In order for SveltePixi to make use of this custom file we'll need to create an alias.

Update your `vite.config.js` file to include the following:

Expand All @@ -60,7 +60,7 @@ import { defineConfig } from 'vite'

export default defineConfig({
/* ... */

optimizeDeps: {
// required so svelte-pixi will use pixi.js alias
exclude: ['svelte-pixi'],
Expand All @@ -72,4 +72,4 @@ export default defineConfig({
},
},
})
```
```
2 changes: 1 addition & 1 deletion docs/src/content/docs/index.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Svelte Pixi
title: SveltePixi
description: Declaratively create PixiJS applications
template: splash
hero:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@
title: v7.0.0
---

SveltePixi v7.0.0 brings support for PixiJS v7.3.0. This is the first major version of SveltePixi and the first to support PixiJS v7. Going forward, the major version of SveltePixi will match the major version of PixiJS.

It is advised to read through the [PixiJS v7 Migration Guide](https://github.com/pixijs/pixijs/wiki/v7-Migration-Guide) to get an overview of the changes in PixiJS. Additionally the release notes for [v7.2.0](https://github.com/pixijs/pixijs/releases/tag/v7.2.0) are helpful to learn about the changes the interaction system.

# Features

- PixiJS v7 support
- [AssetsLoader](/api/components/assets-loader) component (see [breaking changes](#loader---assetsloader))
- [HTMLText](/api/components/html-text) component

# Breaking Changes

## Loader -> AssetsLoader

[PIXI.Loader has been replaced by PIXI.Assets](https://github.com/pixijs/pixijs/wiki/v7-Migration-Guide#-replaces-loader-with-assets) so the `Loader` component has been replaced by `AssetsLoader`. It works similarly but has a few notable differences:
Expand Down

0 comments on commit d0af50e

Please sign in to comment.