dongnanyanhai / phavuer

A wrapper library for Phaser3 with Vue.

Phavuer

Phavuer is a wrapper library for Phaser 3 with Vue 3.
It makes able to develop games with declarative rendering.

• Phavuer vs Phaser's plane API - A Compilation by example UI.
• Phavuer Example Shooter - A simple shooter that written in Phavuer.
• Phavuer RPG Example - An RPG example (This is just a usage example. Not a completed Game.)
• "The Dream Libra had" - An RPG made with Phavuer (Completed project and published on Steam).

*** Attention ***

• This is still WIP.
• I am not sure the performance, but it is never be faster than plain Phaser.
• If you use Phavuer, the source code will be quite different from plain Phaser. keep in mind that you can not switch the way easily.

However, I am keep going to use it for make own game.
Feel free to contribute.

Usage example

MainScene.vue:

<template>
  <Scene name="MainScene">
    <Text @pointerdown="onClick" text="Add a Rectangle" />
    <Container v-for="(n, i) in count" :key="i" :x="i * 130" :y="30">
      <Rectangle :width="120" :height="30" :origin="0" :fillColor="0x333333" />
      <Text :x="60" :y="15" :origin="0.5" :text="`Rectangle-${n}`" />
      <MyCustomComponent />
    </Container>
  </Container>
</template>

<script>
import { Scene, Container, Rectangle, Text } from 'phavuer'
import { ref } from 'vue'
import MyCustomComponent from './MyCustomComponent.vue'
export default {
  components: { Scene, Container, Rectangle, Text, MyCustomComponent },
  setup () {
    const count = ref(1)
    const onClick = () => count.value++
    return { count, onClick }
  }
}
</script>

The template syntax follows Vue 3 as it is. (doc)
There are no orignal syntax.

Phaser3's GameObjects and its properties can be used as components and its props. They are following the original names, Phaser3's document can be used as is.

Installation

CDN

In addition to Phaser 3, Vue 3 is needed.
Phavuer must be placed below them.

<script src="https://unpkg.com/phaser@3.50.1/dist/phaser.min.js"></script>
<script src="https://unpkg.com/vue@3.0.4/dist/vue.global.prod.js"></script>
<script src="https://unpkg.com/phavuer/dist/phavuer.min.js"></script>

const { Scene } = Phavuer
const MainScene = {
  components: { Scene },
  template: '<Scene>...</Scene>',
  setup () {
    return {}
  }
}
const vueApp = Vue.createApp(MainScene)
const game = new Phaser.Game({ .. })
createPhavuerApp(game, vueApp)

Vite

(Vite)

$ yarn init
$ yarn add phavuer phaser vue@next
$ yarn add -D vite @vitejs/plugin-vue @vue/compiler-sfc @rollup/plugin-replace

package.json

{
  ..
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "serve": "vite preview"
  },
  ..
}

vite.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import replace from '@rollup/plugin-replace'

export default defineConfig({
  plugins: [
    vue(),
    replace({
      'typeof CANVAS_RENDERER': JSON.stringify(true),
      'typeof WEBGL_RENDERER': JSON.stringify(true)
    })
  ]
})

index.html

..
<!-- Don't forget type="module" -->
<script type="module" src="./index.js"></script>
..

index.js

import 'phaser'
import { createApp } from 'vue'
import { createPhavuerApp } from 'phavuer'
import MainScene from './MainScene.vue'
const vueApp = createApp(MainScene)
const game = new Phaser.Game({ .. })
createPhavuerApp(game, vueApp)

API

Methods

createPhavuerApp(gameInstance, vueApp)

Parameters:

gameInstance: Game instance of Phaser vueApp: Vue application that generated from createApp of vue

Return value:

App instance of Vue

useGame()

Return value:

Phaser.Game

useScene()

Return value:

Phaser.Scene

refTo(value, key)

Parameters:

value: Initial value key: Key string of what property of given new value should be set

Return value:

Instance of CustomRefImpl

Usage:

Can be used to get such as a GameObject easily.

const rectangle = refTo(null, 'object')

<Rectangle ref="rectangle">

refObj(value)

A sugar function for refTo(value, 'object')

refScene(value)

A sugar function for refTo(value, 'scene')

onPreUpdate(event)

A method to register an event on pre update of the scene.

onPostUpdate(event)

A method to register an event on post update of the scene.

Components

Scene

Scene component is used for make your scene component.

Props:

• name: (String) Scene name
• autoStart: (Boolean) Scene is started immediately if true

The name can be received from props, so you can use it as is: <Scene :name="props.name">

Events:

• init (scene, data)
• create (scene, data)
• update (scene, time, delta)
• preload (scene)

Properties:

• scene Scene object

If you want to handle multi scenes, root component supposed to be like this:

<template>
  <GameScene />
  <UIScene />
</template>

<script>
import GameScene from './GameScene'
import UIScene from './UIScene'
export default {
  components: { GameScene, UIScene }
}
</script>

Base Components

Base Components are basic components for each Phaser 3's GameObjects such as Sprite or Rectangle.

You can use them like this: <Rectangle :x="0" :y="0" :width="10" :height="10" />

• Basic components return instance of its GameObject in key name object
  • So you can get it with a ref like this: <Rectangle ref="el" /> + el.value.object (from outside: el.object)
• An event for object created can be defined with @create
  • The argument is (GameObject)
• Almost all props names are following the property names of its GameObject
• A Tween for the object can be defined with :tween
  • targets of the options will be set automatically
  • The Tween will be removed automatically before the object destroyed

Currently Phavuer has following base components:

• Container
• Image
• Sprite
• Text
• Rectangle
• RoundRectangle
• Circle
• Line
• Zone
• TilemapLayer
• Light
• StaticBody
• Body

If you want to use another GameObjects, plase make an issue or MR.
Also you can make base components just in your project. (refer)

Methods (for contributers)

initGameObject(gameObject, props, context)

This method gives following features to the given gameObject:

• Having reactivity for given props such as x or y (see all)
• Appended to the parent Container automatically if it exists
• Appended to the Scene automatically if parent Container not exists
• Destroyedautomatically when the component is unmounted
• Able to set interactive events such as @pointerup
• Able to set an event for on create @create

Parameters:

• gameObject: Phaser 3 GameObject instance
• props: Vue 3 props
• context: Vue 3 context

It is used to define Base Components. (like this)

If you just want to use your component in your another component, you don't need this method.
For such a case, you just need to relay props to default components.