DEV Community: Renato Cassino

I built the best virtual joystick for PhaserJS, then went to bed.

Renato Cassino — Sat, 25 Oct 2025 21:15:00 +0000

Lately I’ve been building a lot of games, and for one of my mobile projects I wanted the controls to feel great. At some point I realized I needed an on-screen joystick.

My first idea was to use simple virtual buttons — but of course, they don’t offer any real tactile feedback. You just can’t feel them.

That’s when I remembered Brawl Stars, which I used to play years ago. Its joystick always felt incredibly smooth and responsive.

So I decided to study its behavior and rebuild something similar — but this time as an open-source library, so any Phaser developer can use and improve it.

Observations

One of the biggest challenges with virtual joysticks is maintaining touch consistency.
If the joystick always stays fixed in place, the player will inevitably touch different spots every time. That leads to confusion, you might intend to move left, but if your finger lands slightly to the right, your input ends up reversed.

The solution used by top-tier games like Brawl Stars is to reposition the joystick to the initial touch point. This way, movement always starts exactly where the player’s finger touches, creating a more natural and intuitive control feel.

Another important design choice is the active area limitation: since action buttons usually sit on the right side of the screen, the joystick only responds to touches on the left side. This prevents input conflicts and ensures smoother gameplay.

And there’s one more subtle UX detail: when the player’s finger moves too far away, the joystick follows the motion slightly, keeping a safe margin so it doesn’t interfere with direction control. That way, the player never has to drag the finger all the way back, the joystick adapts and moves gracefully with them.

From binary touches to analog movement

When I started integrating the Xbox controller, I realized that the analog stick isn’t binary (obviously), it’s not just “pressed or not pressed.”
Each axis (horizontal and vertical) actually provides a float value between -1 and 1, representing both direction and intensity.

That means if you tilt the stick slightly to the right, you might get 0.3; push it all the way, and it reaches 1.0. The same goes for up, down, and left — just with negative values.

I found that behavior fascinating — it’s what gives console games their smooth and precise control. So I decided to replicate the exact same logic in my virtual joystick.

Now, instead of just asking “which direction is the finger moving?”, the joystick calculates the distance and angle from the starting point to the current touch position, normalizing both axes to the [-1, 1] range.
The result feels much more natural: the character doesn’t just move or stop, it moves with varying speed and direction, depending on how far you drag your finger.

How I approached the development

I started by creating a container to represent the entire joystick. Inside it, I placed a small central circle, inspired by Brawl Stars, which acts as the neutral reference point — the center of movement.

Around that circle, I defined the movement area, the boundary within which the joystick can move.
On top of it, I added another movable circle, representing the stick itself — visually similar to an Xbox analog stick.

When the player touches the screen, the system stores the initial touch position.
Then, on every move event, it calculates the current finger position and uses that data to compute the movement angle, determining the direction the stick should point to.

To prevent the stick from drifting too far, I applied an angular limit, ensuring it stays within its defined movement radius.

Finally, with the angle in hand, I normalize the movement by converting the distance and direction into float values between -1 and 1 for both the horizontal and vertical axes.
The result is a virtual joystick that behaves just like a real analog stick — smooth, responsive, and with proportional control based on touch intensity.

Turning the concept into an open-source library

To make this logic reusable, I created three main events in PhaserVirtualJoystick:
press, move, and release.
Their names are self-explanatory — they represent the initial touch, the continuous movement, and the moment the player lifts their finger.

These three events make it simple to capture the full joystick behavior.
They allow you to react instantly to player input without worrying about angle calculations or normalization math.

Here’s a small usage example:

import { VirtualJoystick } from 'phaser-virtual-joystick';

class GameScene extends Phaser.Scene {
    create() {
        // Create a virtual joystick with default settings
        const joystick = new VirtualJoystick({
            scene: this
        });

        // ⚠️ IMPORTANT: Don't forget to add the joystick to the scene!
        this.add.existing(joystick);

        // Listen to joystick events
        joystick.on('move', (data) => {
            console.log(`Joystick position: ${data.x}, ${data.y}`);
            // Move your character based on joystick input
            this.moveCharacter(data.x, data.y);
        });

        joystick.on('press', () => {
            console.log('Joystick pressed');
        });

        joystick.on('release', () => {
            console.log('Joystick released');
        });
    }

    moveCharacter(x: number, y: number) {
        // Your character movement logic here
        const speed = 200;
        this.character?.setVelocity(x * speed, y * speed);
    }
}

With just a few lines of code, you get a smooth, responsive virtual joystick ready to drop into any Phaser game.

Installation

You can install the lib Phaser-Virtual-Joystick using npm, yarn or pnpm.

$ npm i --save phaser-virtual-joystick
# or
$ yarn i phaser-virtual-joystick
# or
$ pnpm add phaser-virtual-joystick

Usage

In your scene, you must create the virtual joystick and add it.

import { VirtualJoystick } from 'phaser-virtual-joystick';

export class GameScene extends Phaser.Scene {
  private joystick!: VirtualJoystick;
  private player!: Phaser.Physics.Arcade.Sprite;

  create() {
    // Create the virtual joystick
    this.joystick = new VirtualJoystick({
      scene: this
    });

    // ⚠️ IMPORTANT: Don't forget to add the joystick to the scene!
    this.add.existing(this.joystick);

    // Create a player sprite
    this.player = this.physics.add.sprite(400, 300, 'player');

    // Listen to joystick events
    this.joystick.on('move', (data) => {
      // data.x and data.y are normalized between -1 and 1
      this.player.setVelocity(
        data.x * 200, // Move speed
        data.y * 200
      );
    });

    this.joystick.on('release', () => {
      this.player.setVelocity(0, 0);
    });
  }

  update() {
    // Update joystick (required for smooth following behavior)
    this.joystick?.update();
  }
}

Convention over configuration

One of my favorite development principles is “Convention over Configuration”, and that’s exactly what I applied to PhaserVirtualJoystick.
The idea is simple: everything should work great out of the box, but still be easy to customize when needed.

For example, by default, the joystick is active only on the left half of the screen, which is the usual layout for mobile games.
But if you want to change that, just use the bounds parameter:

bounds?: {
  topLeft: { x: number; y: number };
  bottomRight: { x: number; y: number };
};

This lets you define exactly where the joystick can be triggered.
Want it active across the entire screen?
Just set topLeft: { x: 0, y: 0 } and bottomRight to match your game’s dimensions.

Another convention is styling.
If you don’t provide any configuration, the joystick defaults to a smooth blue theme (the one you’ve seen in the GIFs).
But every part of it can be customized.

The joystick is made up of three elements:

deadZone: the central neutral circle
baseArea: the outer movement boundary
stick: the movable analog itself

Each element accepts a StyleConfig object:

export type StyleConfig = {
  alpha: number;
  strokeColor: number;
  strokeAlpha: number;
  strokeWidth: number;
  radius: number;
  fillColor: number;
}

You can override just a few values or all of them — it’s up to you.

Here’s an example of a yellow custom joystick using the phaser-wind color palette:
👉 StackBlitz Demo

Conclusion

This project started out as a small curiosity — I just wanted a joystick that felt right on mobile.
But after tweaking the movement, normalizing the axes, and testing over and over again, it turned out so good that it became an open-source library: PhaserVirtualJoystick.

If you’re building a game with PhaserJS and want smooth, responsive controls, give it a try.
You can check out the full documentation here:
👉 PhaserVirtualJoystick Docs

Our repo in Github

Contributions are always welcome!

If you have ideas, improvements, or want to adapt it for different gameplay styles, open an issue or pull request.
My goal is for this library to keep evolving with the Phaser community.

And that’s when I finally went to bed… mission accomplished 😴.

Stop Struggling with State in Phaser js: How Phaser-Hooks Will Revolutionize Your Code

Renato Cassino — Fri, 19 Sep 2025 22:44:00 +0000

You’re developing your Phaser game and suddenly… BOOM! An impossible-to-track bug. The player state disappears between scenes, listeners aren’t removed, and memory leaks start showing up. Sound familiar?

Get ready to discover how a small library revolutionized my code and my sanity.

The Problem: State Management Chaos

If you’ve ever developed games with Phaser, you’ve probably faced the frustration of managing states. Phaser’s native system, while functional, presents several pitfalls that can turn a simple project into a nightmare of hard-to-track bugs.

1. Naming Inconsistency

Who hasn’t had those “blank” moments while programming? I confess: I’m terrible at remembering variable names and syntax. And the worst part is that Phaser’s native system offers no validation to save us from these traps.

// Scene 1
this.registry.set('user-state', { name: 'Player', level: 5 });

// Scene 2 - Oops! Typo that will only error at runtime
this.registry.set('userState', { name: 'Player', level: 6 });

The result? Hours lost hunting an invisible bug. You alternate between camelCase in one scene and kebab-case in another, creating duplicate states without noticing. The worst part is that this type of error is silent - the game doesn't break, it just doesn't work as expected.

2. Confusing Event System

Phaser automatically generates events in the changedata- format, which are:

Hard to remember
Prone to typos
Without proper TypeScript support

// Native system - confusing and error-prone
this.registry.events.on('changedata-player-health', (parent, key, value) => {
  // Callback logic
});

// Problem: how to cleanup without memory leaks?
// If you use arrow functions, you can't do .off() later

3. Confusion Between Local and Global States

// Global state - persists between scenes
this.registry.set('global-score', 100);

// Local state - cleared when changing scenes
this.data.set('local-ui', { menuOpen: false });

While both have the same contract (.set(), .get()), you need to constantly remember: "Is this state registry or data?". The difference between global and local is conceptual, but you have to memorize which object to use for each situation. One more thing taking up mental space that should be focused on your game's logic.

4. Zero TypeScript Support

Without proper typing, you completely lose the intellisense and type safety that TypeScript offers.

The Solution: Phaser-Hooks

Inspired by the elegance of React Hooks, phaser-hooks is a library that brought a consistent, type-safe, and intuitive API to my Phaser workflow. After using it in production, I can say: it’s impossible to go back to the native system.

Installation

$ npm i phaser-hooks

Simple and Familiar API

If you’ve used React, you’ll feel right at home. The API is intuitive and fully typed:

// Define your state type
type PlayerUI = {
  health: number;
  mana: number;
  menuOpen: boolean;
};

// Create state with destructuring (very React-like)
const { get, set, on } = withLocalState<PlayerUI>(this, 'player-ui', {
  health: 100,
  mana: 50,
  menuOpen: false
});

// Use with complete type safety
set({ health: 80, mana: 30, menuOpen: true }); // ✅ Validated by TypeScript
set({ helth: 80 }); // ❌ Compilation error - typo detected!

// Retrieve typed values
const currentHealth = get().health; // Complete IntelliSense

// Listen to changes
on('change', (newValue, oldValue) => {
  console.log(`Health: ${oldValue.health} → ${newValue.health}`);
});

The library offers two main hooks with exactly the same contract:

withLocalState: State isolated per scene - perfect for UI, temporary states, or data that should "reset" when changing scenes
withGlobalState: State shared between all scenes - ideal for score, player settings, game progress

No matter which one you choose, the API is identical. No need to memorize if it’s registry or data anymore - just think about the scope you want and use the corresponding hook.

A Simple Example

Let’s create a custom hook to manage player UI:

import { withLocalState, type HookState } from 'phaser-hooks';

// Define your state type
type PlayerUI = {
  health: number;
  mana: number;
  menuOpen: boolean;
};

// Create a custom hook
export type PlayerUIHook = HookState<PlayerUI> & {
  takeDamage: (damage: number) => void;
  useMana: (cost: number) => void;
  toggleMenu: () => void;
};

export const withPlayerUI = (scene: Phaser.Scene): PlayerUIHook => {
  const { get, set, ...rest } = withLocalState<PlayerUI>(scene, 'player-ui', {
    health: 100,
    mana: 50,
    menuOpen: false
  });

  return {
    ...rest,
    get,
    set,
    takeDamage: (damage: number) => {
      const current = get();
      set({ ...current, health: Math.max(0, current.health - damage) });
    },
    useMana: (cost: number) => {
      const current = get();
      set({ ...current, mana: Math.max(0, current.mana - cost) });
    },
    toggleMenu: () => {
      const current = get();
      set({ ...current, menuOpen: !current.menuOpen });
    },
  };
};

// In your scene
class GameScene extends Phaser.Scene {
  create() {
    const playerUI = withPlayerUI(this);

    // Use with complete type safety
    playerUI.takeDamage(20); // ✅ Typed method

    // Listen to changes
    playerUI.on('change', (newValue, oldValue) => {
      console.log(`Health: ${newValue.health} - ${oldValue.health}`);
    });
  }
}

Advanced Features

1. Clean Event System

// Permanent listener
const unsubscribe = state.on('change', (newValue, oldValue) => {
  console.log('State changed:', newValue);
});

// One-time listener
state.once('change', (newValue, oldValue) => {
  console.log('First change detected:', newValue);
});

// Easy cleanup
unsubscribe(); // or
state.clearListeners(); // Remove all listeners

Important: The on('change') method returns an unsubscribe function that should be called before leaving the scene to prevent memory leaks. A common practice is to use the scene's own destroy event:

create() {
  const playerState = withLocalState(this, 'player', initialValue);

  const unsubscribe = playerState.on('change', (newValue, oldValue) => {
    console.log('State changed from:', oldValue, 'to:', newValue);
  });

  // Automatic cleanup
  this.events.once('destroy', () => {
    unsubscribe();
  });
}

2. Advanced Custom Hooks

You can create complex hooks that encapsulate specific game logic:

// Timer hook with complete control
export const withTimer = (scene: Phaser.Scene): TimerHook => {
  const { get, set, ...rest } = withGlobalState<Timer>(scene, 'TIMER', { seconds: 0 });
  let timer: Phaser.Time.TimerEvent | null = null;

  return {
    ...rest,
    get,
    set,
    start: () => {
      if (!timer) {
        timer = scene.time.addEvent({
          delay: 1000,
          loop: true,
          callback: () => set({ seconds: get().seconds + 1 }),
        });
      }
    },
    pause: () => timer?.paused && (timer.paused = true),
    reset: () => {
      set({ seconds: 0 });
      timer?.remove(false);
      timer = null;
    },
  };
}

// Score hook with convenient methods
export const withScore = (scene: Phaser.Scene): ScoreHook => {
  const { get, set, ...rest } = withGlobalState<Score>(scene, 'SCORE', { home: 0, away: 0 });

  return {
    ...rest,
    get,
    set,
    reset: () => set({ home: 0, away: 0 }),
    addHomeGoal: () => set({ ...get(), home: get().home + 1 }),
    addAwayGoal: () => set({ ...get(), away: get().away + 1 }),
  };
}

Advanced Options

Debug Mode

const state = withLocalState(scene, 'debug-state', initialValue, {
  debug: true  // Enables detailed console logs
});

Custom Validation

const healthState = withLocalState<number>(scene, 'health', 100, {
  validator: (value) => {
    const health = value as number;
    return health >= 0 && health <= 100 ? true : 'Health must be between 0-100';
  }
});

Advantages of Phaser-Hooks

✅ Complete Type Safety

Full IntelliSense in VSCode
Errors detected at compile time
Custom interfaces for each state
✅ Consistent API

Same contract for local and global states
Standardized and intuitive naming
Unified event system
✅ Memory Leak Prevention

clearListeners() method for easy cleanup
unsubscribe functions returned by listeners
Clear documentation about best practices
✅ Extensibility

Custom hooks for specific logic
Feature composition
Reuse across projects
✅ Developer Experience

Debug mode with detailed logs
Custom value validation
Clear error messages

Performance

The library is just an abstraction layer over Phaser’s native system (registry and data). There's no significant performance overhead, maintaining all the efficiency of the original engine.

Conclusion

Phaser-hooks solves real problems that every Phaser developer faces, offering:

Productivity: Fewer bugs, faster development
Maintainability: Cleaner and more organized code
Scalability: Custom hooks for complex logic
Reliability: Type safety and memory leak prevention

Personally, I’ve been using the library in my production projects — both in Coin Flick Soccer (still in development) and Smart Dots Reloaded. The difference in development experience was transformative.

If you develop games with Phaser and want a more professional and productive development experience, try phaser-hooks in your next project.

Links

GitHub: phaser-hooks
NPM: phaser-hooks

Developed with ❤️ for the Phaser community

Matrix Typer – Typing game built with Phaser 3 + TypeScript

Renato Cassino — Mon, 08 Sep 2025 15:33:27 +0000

Hi everyone!

I’d like to share a small project I built with Phaser 3 and TypeScript: Matrix Typer.

It’s a typing game inspired by the classic Matrix rain effect:

💻 Letters fall down the screen

⌨️ You type them before they reach the bottom

🎯 Goal: keep up with the pace and improve your typing skills

I also included a mini typing course, so players can train step by step, starting from the basics and gradually increasing the challenge.

For the UI icons, I used font-awesome-for-phaser

Link to play: https://games.cassino.dev/game/matrix-typer/

Some screenshots bellow:

gamedev #phaser #typescript #indiedev #phaser3