Login

Phaser

Phaser is a fast, free and open source HTML5 game framework for 2D games, written in JavaScript/TypeScript. It offers WebGL and Canvas rendering, arcade and matter.js physics, tweens, particles, and a large plugin ecosystem. Since Phaser games are plain web pages, they need no compilation or export step at all — which makes the publishing pipeline the simplest of all our engines.

Website: https://phaser.io

Tutorials

Makefile

This Makefile provides a simple, reproducible workflow for packaging Phaser projects for the web. There is no bundler and no node_modules: the pinned phaser.min.js build is downloaded from the jsDelivr CDN at export time (the same way love-tools downloads love.js), and the game sources are concatenated into a single game.js.

Overview

The workflow is based on four core ideas:

  • Game sources live in src/*.js and are concatenated in filename order into game.js (prefix files with numbers if load order matters)
  • The pinned Phaser runtime and the HTML shell are downloaded at build time, so the repository contains only game code
  • Version management is handled automatically from metadata.json or git commit hash
  • CI/CD targets enable automated build, versioning, and deployment

The templates live in the phaser-tools repository: copy example-makefile.make to Makefile and set PROJECT and PHASER_VERSION.

Configuration Variables

Variable Description Default
PROJECT Project name (used in output filenames) phaserdemo
PHASER_VERSION Phaser release downloaded from jsDelivr 3.90.0
SRC_DIR Directory with the game sources src
DIST_DIR Directory for exported artifacts dist
WEB_DIR Directory for the assembled web bundle dist/web
VERSION_FILE File storing version for CI/CD .version
INDEX_HTML_URL HTML shell downloaded at build time phaser-tools web/index.html

Usage

Build (default)

SH
make build
  • Runs node --check on every file in src/ (syntax check only)

Build web bundle

SH
make web
  • Downloads phaser.min.js (pinned version) and index.html
  • Concatenates src/*.js into dist/web/game.js

Serve locally

SH
make serve
  • Builds the web bundle and serves it on http://localhost:8000 (Python 3's built-in HTTP server)

Export

SH
make export VERSION=1.0.0
  • Requires a VERSION variable.
  • Packages dist/web/ into a versioned ZIP: phaserdemo-1.0.0.html.zip
  • Cleans up the raw web bundle after packaging

Watch Mode

SH
make watch
  • Re-runs the syntax check on changes under src/ (requires fswatch)

Clean

SH
make clean
  • Removes the dist/ directory

VS Code Tasks

The tools repository also contains an example-tasks.json that can be copied to .vscode/tasks.json. It provides Serve (make serve, default build task, Cmd+Shift+B), Build Web and Make build.

CI/CD Targets

make ci-version

  • Extracts version from metadata.json (if exists) or uses git short commit hash
  • If the branch is not main or master, prefixes version as dev-<version>-<branch>
  • Writes the final version to .version

make ci-export

  • Reads version from .version and runs make export with it

make ci-upload

  • Copies metadata.json to phaserdemo-<version>.metadata.json
  • Uploads the ZIP and the metadata via SCP to the droparea
  • Requires environment variables: DROPAREA_SSH_PASSWORD, DROPAREA_PORT, DROPAREA_USER, DROPAREA_HOST, DROPAREA_TARGET_PATH

make ci-update

  • Calls $(UPDATE_SERVER)/update?platform=phaser&name=$(PROJECT)&version=<version>
  • Requires environment variables: UPDATE_SERVER, UPDATE_SECRET

Generated Artifacts

File Description
dist/web/ Assembled web bundle (index.html, phaser.min.js, game.js)
phaserdemo-<version>.html.zip Packaged web build, ready for deployment

Requirements

  • make, git, jq, zip, curl
  • node (for the syntax check)
  • python3 (only for make serve)
  • fswatch (only for watch mode)
  • sshpass and scp (for ci-upload target)

Pipeline

This document describes the Woodpecker CI pipeline used to build, package, upload, and publish a Phaser game project.

Overview

The pipeline logic is almost entirely encapsulated within the Makefile, which is called by each pipeline step. The pipeline performs the following steps:

  1. Version Extraction: make ci-version (alpine) — version from metadata.json or git.
  2. Build & Export: make ci-export in the git.teletypegames.org/internal/phaser-builder image (Node + make/zip/curl, built from builder.Dockerfile in phaser-tools) — syntax check, downloads the pinned Phaser runtime and the HTML shell, packages the ZIP.
  3. Upload Artifacts: make ci-upload — scp to the droparea (vps.teletype.hu:2223).
  4. Notify Update Server: make ci-update — calls the teletypegames /update endpoint with platform=phaser.

Copy example-woodpecker.yaml to .woodpecker.yaml and add the droparea_ssh_password / update_secret_key secrets in Woodpecker.

Demo project

phaser-demo is the reference project using these templates: an animated "TELETYPE GAMES" wave text (the same demo as ebitengine-demo), built on Phaser 3.90.