zImporter

The second part of zStudio - seamlessly load your designed scenes into your Pixi.js and Phaser games and interactive ads. Export from zStudio, import with zImporter, and bring your UI to life in code.

Quick Start Tutorial

What You Get After Exporting

Once you export your scene in zStudio, you'll have these essential files ready for import:

./scene/
    placements.json --> Scene positioning and hierarchy structure
    ta.json --> Texture Atlas coordinates
    ta.png --> The texture atlas image

You can also export with individual images instead of a texture atlas.

🖼️ Pixi.js Integration

📦 Get Started with Pixi.js

Get the zImporter package and example project to start integrating zStudio scenes into your games and ads.

📦 zImporter Pixi 7 📦 zImporter Pixi 8 🚀 Example Project 📚 Documentation

Installation

Choose the package that matches your Pixi.js version. Both packages share the exact same API and interface.

Pixi.js v7

npm i zimporter-pixi

Pixi.js v8

npm i zimporter-pixi8

zImporter Integration

Import the Classes

Replace zimporter-pixi with zimporter-pixi8 if you are using Pixi.js v8 — the interface is identical.

import * as PIXI from 'pixi.js';
import { ZButton, ZContainer, ZScene, ZState, ZSceneStack } from 'zimporter-pixi';
// or for Pixi v8:
// import { ZButton, ZContainer, ZScene, ZState, ZSceneStack } from 'zimporter-pixi8';

Code Examples

App Setup (app.ts)

import * as PIXI from 'pixi.js';
import { ZSceneStack, ZUpdatables } from 'zimporter-pixi';

const app = new PIXI.Application({
  backgroundColor: 0x000000,
  resolution: window.devicePixelRatio || 1,
  autoDensity: true,
  antialias: true
});
document.body.appendChild(app.view as any);

window.addEventListener("resize", () => {
  app.renderer.resize(window.innerWidth, window.innerHeight);
  ZSceneStack.resize(window.innerWidth, window.innerHeight);
});

ZUpdatables.init(24);

app.ticker.add(() => {
  const deltaMS = app.ticker.deltaMS / 1000;
  ZUpdatables.update();
});

Loading a Scene

import { ZScene, ZSceneStack } from 'zimporter-pixi';

const scene = new ZScene("myScene");
scene.load("./assets/myScene/", () => {
    ZSceneStack.push(scene);
    scene.loadStage(app.stage as any);
}, (progress: number) => {
    console.log(`Loading... ${Math.floor(progress * 100)}%`);
});

⚡ Phaser Integration

🚧 Phaser Support (Beta)

zImporter now supports Phaser 3! This feature is currently in beta - please report any issues you encounter.

📦 zImporter Phaser 3 Package 🚀 Example Project 📚 Documentation

Phaser Installation

Install

npm i zimporter-phaser

All dependencies (Phaser, Spine, GSAP, etc.) are bundled — no additional peer dependency installation required.

Phaser zImporter Integration

Import the Classes

import Phaser from 'phaser';
import { ZButton, ZContainer, ZScene, ZSceneStack, ZUpdatables, SpinePlugin } from 'zimporter-phaser';

Note: SpinePlugin is re-exported directly from zimporter-phaser — no separate spine package import needed.

Phaser Code Examples

Game Scene Setup

import Phaser from 'phaser';
import { ZContainer, ZScene, ZSceneStack, ZUpdatables } from 'zimporter-phaser';

export class GameScene extends Phaser.Scene {

    constructor() {
        super({ key: 'GameScene' });
    }

    preload() {}

    create() {
        ZUpdatables.init(24);

        // Create a root ZContainer — the Phaser equivalent of PIXI's app.stage
        const rootStage = new ZContainer(this);
        this.add.existing(rootStage);

        // Load a zStudio scene — pass the Phaser scene as second argument
        const scene = new ZScene("myScene", this);
        scene.load("./assets/myScene/", () => {
            ZSceneStack.push(scene);
            scene.loadStage(this);
        }, (progress: number) => {
            console.log(`Loading... ${Math.floor(progress * 100)}%`);
        });
    }

    update(_time: number, _delta: number) {
        ZUpdatables.update();
    }
}

Game Configuration

import Phaser from 'phaser';
import { GameScene } from './GameScene';
import { ZSceneStack, SpinePlugin } from 'zimporter-phaser';

const config: Phaser.Types.Core.GameConfig = {
    type: Phaser.AUTO,
    width: window.innerWidth,
    height: window.innerHeight,
    parent: 'game-container',
    scene: [GameScene],
    backgroundColor: '#000000',
    scale: {
        mode: Phaser.Scale.RESIZE,
        autoCenter: Phaser.Scale.CENTER_BOTH
    },
    plugins: {
        scene: [{
            key: 'SpinePlugin',
            plugin: SpinePlugin,
            mapping: 'spine'
        }]
    }
};

const game = new Phaser.Game(config);
(globalThis as any).__PHASER_GAME__ = game;

window.addEventListener('resize', () => {
    ZSceneStack.resize(window.innerWidth, window.innerHeight);
});

🌐 HTML Integration

🚧 HTML Support (Beta)

zImporter now supports plain HTML using standard divs! No canvas framework required. This feature is currently in beta - please report any issues you encounter.

📦 zImporter HTML Package 📚 Documentation 🚀 Example Project

HTML Installation

Add to package.json

"dependencies": {
  "zimporter-html": "latest"
}

No Canvas Framework Required

zImporter HTML works with standard browser divs and CSS — no Pixi.js or Phaser needed. Perfect for HTML banners, interactive web ads, and lightweight UI projects.

Install Dependencies

npm install

HTML zImporter Integration

Import the Classes

import { ZButton, ZContainer, ZScene, ZState, ZSceneStack } from 'zimporter-html';

HTML Code Examples

Loading a Scene

import { ZScene, ZSceneStack } from 'zimporter-html';

const loadPath = './assets/testScene/';
const scene = new ZScene('testScene');

scene.load(loadPath, () => {
    ZSceneStack.push(scene);
    // Mount the scene into a DOM element
    scene.loadStage(document.getElementById('app')!);
});

Interacting with Elements

import { ZScene, ZSceneStack, ZButton, ZContainer } from 'zimporter-html';

const scene = new ZScene('myScene');
scene.load('./assets/myScene/', () => {
    ZSceneStack.push(scene);
    scene.loadStage(document.getElementById('app')!);

    const stage: ZContainer = scene.sceneStage;
    const myBtn: ZButton = stage.get('myBtn') as ZButton;

    myBtn.setLabel('Click Me');
    myBtn.setCallback(() => {
        console.log('Button clicked!');
    });
});

Quick Navigation

🖼️ Pixi.js ⚡ Phaser 🌐 HTML