Importing a Charios rig into a Phaser 3 game

It’s 2 AM. Your dev build of the platformer is due in six hours, and your hero’s left arm still pops out of socket on every other run-cycle frame. You’ve tweaked the sprite sheet coordinates for the tenth time, but the Phaser 3 animation just isn't smooth. We’ve all been there, staring at a janky character, wondering if we should just switch to static sprites. That moment of despair is exactly why we built Charios.

1.The silent cost of manual animation: Why skeletal rigs save sanity

When you start out, frame-by-frame animation feels simple. You draw a few sprites, throw them into an array, and call `play()` in Phaser. For a single idle animation, it’s fine. But then you add a walk, a jump, an attack, and suddenly you’re managing hundreds of individual frames and pixel-perfect adjustments. This manual approach becomes a crushing burden fast.

Skeletal animation, on the other hand, lets you define a single set of art assets and then manipulate bones to create movement. Instead of redrawing, you’re posing. This isn't just about saving time; it's about maintaining consistency and sanity across dozens of animations. It's the difference between sculpting each frame and animating a puppet.

a.Frame-by-frame for NPCs is malpractice

Here's a strong opinion: For any character with more than three animations or a dynamic pose system, frame-by-frame animation is malpractice. Especially for NPCs or multiple playable characters. You will drown in asset management and subtle inconsistencies. Your time is better spent on game design, not pixel-pushing redundant frames.

• Scaling issues: Resizing characters means redrawing every frame.
• Animation consistency: Each new animation can look slightly off from the last.
• Mocap integration: Impossible without a skeletal rig.
• Iteration speed: Tweaking timing means re-exporting entire sprite sheets.
• Memory footprint: Massive sprite sheets eat up precious resources.

Tools like Spine or DragonBones offer solutions, but they come with their own learning curves and licensing costs. For many indie devs, especially solo creators, these can feel like an overkill investment. Charios aims to bridge this gap with a browser-native, intuitive approach.

2.Your Charios export: The asset package you need

When you finish animating in Charios, you export a Unity-prefab zip. Don't let the 'Unity' part scare you if you're a Phaser dev. This zip contains all the raw assets we need: the layered PNGs, the skeletal data in JSON, and the animation sequences. It's a complete package designed for engine-agnostic import.

• Layered PNGs: Individual image files for each body part, perfectly aligned.
• `skeleton.json`: Describes the bone structure, parent-child relationships, and default poses.
• `animations.json`: Contains all your keyframe data for each animation.
• `atlas.json` (optional): A texture atlas definition for optimized loading, if you selected that option.
• `atlas.png` (optional): The combined texture sheet for the atlas.

The key here is that Charios provides clean, structured data. This isn't some proprietary binary blob; it's human-readable JSON and standard image files. This transparency makes it incredibly flexible for integration into any game engine, including Phaser. You get full control over how your assets are interpreted.

a.Why a Unity-prefab zip works everywhere

The Unity-prefab export isn't just for Unity users. It's a convenient bundle format for all the necessary files. Think of it as a well-organized folder containing everything your game engine needs to reassemble the character. We chose it because it's a widely understood and robust packaging method.

Inside, you'll find the individual sprite sheets for each body part. This is crucial for performance and flexibility in Phaser. Instead of one giant sprite sheet that might contain a lot of empty space, you get optimized, individual textures. Phaser can then combine these or use them as-is.

3.Setting up your Phaser 3 project for Charios assets

Before we load anything, we need a place for our assets. Create a dedicated folder, perhaps `assets/characters/your_character_name/`, and extract your Charios export there. This keeps your project tidy and makes asset management a breeze. Good organization prevents future headaches.

1. 1Export from Charios: Choose the 'Unity Prefab' option.
2. 2Unzip the archive: Extract the contents to a temporary location.
3. 3Copy assets: Move the `skeleton.json`, `animations.json`, and the image folder (e.g., `images/`) into your `assets/characters/your_character_name/` directory.
4. 4Verify paths: Ensure all image references in `skeleton.json` are correct relative to your game's asset loader.

a.The bare minimum Phaser setup

You'll need a basic Phaser scene to load and display your character. For this example, we'll assume a standard `preload` and `create` structure. We'll focus on the character-specific loading, but remember to have your game container set up correctly. A working Phaser instance is your foundation.

Most 2D animation tutorials start by telling you to buy Spine. Here's why that advice is wrong half the time for solo devs: complexity and cost often outweigh the benefits for simpler projects.

The core idea is to load the JSON data (skeleton and animations) and then all the individual PNGs that make up your character. Each PNG represents a single body part, like `torso.png` or `left_arm.png`. Phaser needs to know about every piece.

4.Loading your Charios character into Phaser: The anatomy of a sprite

Phaser doesn't natively understand Charios's skeletal format directly, but that's a feature, not a bug. We'll write a simple character manager class or utility function. This gives you absolute control and avoids vendor lock-in. You're building a lightweight, custom runtime.

First, load the JSON files. These define your character's structure and all its animations. Then, loop through the image folder and load each individual PNG. Phaser's `this.load.image()` is perfect for this. Each body part becomes a distinct texture.

1. 1Load skeleton JSON: `this.load.json('characterSkeleton', 'assets/characters/myChar/skeleton.json');`
2. 2Load animations JSON: `this.load.json('characterAnims', 'assets/characters/myChar/animations.json');`
3. 3Load individual body parts: Iterate through your image directory and load each PNG: `this.load.image('char_head', 'assets/characters/myChar/images/head.png');`
4. 4Preload all assets: Ensure all these calls are within your `preload` function.

a.Reconstructing the character in `create()`

In your `create()` function, we'll parse the loaded JSON to reconstruct the skeletal hierarchy. Each bone in `skeleton.json` will correspond to a Phaser `Image` object. We'll parent these `Image` objects to create the visual hierarchy. This is where the magic of skeletal animation begins.

The `skeleton.json` contains parent-child relationships and initial local transforms (position, rotation, scale) for each bone. We'll use these to assemble our character piece by piece. Start with the root bone, then add its children, and so on. It's like building a digital puppet.

• Parse skeleton data: Get `this.cache.json.get('characterSkeleton')`.
• Create a container: Use `this.add.container()` for the entire character.
• Instantiate body parts: For each bone, create a `Phaser.GameObjects.Image` using its corresponding loaded PNG.
• Apply initial transforms: Set position, rotation, and scale based on `skeleton.json`.
• Build hierarchy: Add children to their respective parent containers or images.

5.Bringing your character to life: Playing animations in Phaser

Now that your character is assembled, we need to apply the animation data from `animations.json`. Each animation is a series of keyframes, defining the transformations for each bone over time. We'll interpolate these keyframes to create smooth motion. This is where your character truly moves.

Phaser's built-in tween manager is incredibly powerful for this. We can create tweens for each bone's properties (position, rotation, scale) for every keyframe. This allows for fluid animation without manually setting every single frame. It's an efficient way to handle complex motion.

1. 1Parse animation data: Access `this.cache.json.get('characterAnims')`.
2. 2Identify current animation: Select the animation you want to play (e.g., 'walk', 'idle').
3. 3Iterate through keyframes: For each frame in the animation, extract bone transforms.
4. 4Apply tweens: For each bone, create a Phaser Tween to animate its `x`, `y`, `rotation`, and `scale` properties to the keyframe values.
5. 5Manage timing: Chain or sequence tweens to match the animation's frame duration and playback speed.
6. 6Looping: Set tweens to repeat for continuous animations like an idle or walk cycle.

a.A simple animation playback loop

You'll likely want a state machine to manage your character's animations. When the character enters a 'walk' state, you start the walk animation. When it jumps, you switch to the jump animation. This keeps your game logic clean and organized. State machines are your friend for character control.

Consider a simple `playAnimation(animationName)` function. This function would stop any currently playing tweens, reset the character to its base pose, and then start the new sequence of tweens. This ensures smooth transitions between actions.

Tip:

For complex character animation, especially with Mixamo retargeting on a 2D rig, you might create a dedicated `CharacterAnimator` class. This class would encapsulate all the logic for loading, assembling, and playing animations for a single character instance. It centralizes your animation control.

6.The 2 AM Gotchas: Common pitfalls and fixes

You're almost there. The character is on screen, animations are playing. But something still feels off. These are the frustrating little details that can steal hours from a solo dev. Let's tackle them head-on. Knowing these saves you from late-night debugging.

a.Pivot points and registration

The most common issue is incorrect pivot points. In Charios, you define the pivot for each body part. When Phaser loads an image, its default pivot is usually the top-left (0,0). If your Charios pivot was at the center (0.5,0.5), your parts will rotate incorrectly. Always match your Phaser image origin to your Charios pivot.

• Issue: Body parts rotate around the wrong point, making animations look broken.
• Cause: Phaser's default image origin (0,0) doesn't match Charios's defined pivot for the part.
• Fix: For each `Phaser.GameObjects.Image` representing a body part, call `image.setOrigin(pivotX, pivotY)` where `pivotX` and `pivotY` are read from your `skeleton.json` or derived from the image dimensions. Charios exports pivots relative to the image size, so a center pivot would be `0.5, 0.5`.

b.Scaling inconsistencies

Your character might appear too small or too large. This is often a mismatch between the Charios export scale and your Phaser game's world units. If your Charios canvas was 1000 pixels wide and your game world is 100 units wide, you'll need to adjust. Scale is critical for visual harmony.

The simplest fix is to apply a global scale to your character's main container. For example, if your character is twice as big as it should be, set `characterContainer.setScale(0.5)`. This ensures all body parts scale uniformly. One global adjustment is better than many individual ones.

Warning:

Don't scale individual body parts unless your animation specifically calls for it. Doing so can break the skeletal integrity and make your character look disjointed. Scale the root container instead. Uniform scaling maintains your rig's proportions.

7.Beyond the walk cycle: Advanced animation with Charios and Phaser

Once you've mastered the basics, the true power of skeletal animation with Charios shines. You can do far more than simple walk cycles. Think about dynamic reactions, procedural animation overlays, or even **retargeting motion capture data**. The possibilities expand dramatically.

Charios lets you import BVH format or Mixamo data directly onto your 2D rig. The process involves mapping the 3D skeleton to your 2D bones. While Phaser doesn't have a built-in mocap player, the keyframe data is still in your `animations.json`. This unlocks a professional animation workflow for indie budgets.

a.Integrating mocap data

If you've retargeted mocap in Charios, your `animations.json` will contain the full range of motion. You can then play these animations in Phaser just like any other, but with a much higher fidelity of movement. This is how you get professional-looking animations without needing to be an animator yourself. Mocap brings characters to life with realism.

• Source mocap: Use free libraries like the CMU motion capture database or commercial options like Rokoko.
• Retarget in Charios: Apply the mocap data to your 2D rig. Charios handles the complex bone mapping.
• Export and load: The mocap-driven animations are part of your standard Charios export.
• Play in Phaser: Treat them as any other animation, leveraging Phaser's tweening system for smooth playback.

This approach is particularly powerful for complex actions or emotes. Imagine a dynamic dance sequence or a character performing a nuanced gesture. Manually keyframing that would take days; with mocap, it's hours. You save time without sacrificing quality.

8.Optimizing your Phaser game for Charios characters

While skeletal animation is efficient, having many characters or complex rigs can still impact performance. Phaser is generally performant, but good practices are essential. We want your game to run smoothly on a wide range of devices. Optimization is key for a polished player experience.

a.Batching and texture atlases

Loading many individual PNGs can lead to multiple draw calls, which can slow things down. Charios offers an option to export a single texture atlas (`atlas.png` and `atlas.json`) instead of individual PNGs. This batches draw calls and significantly boosts rendering performance. Always use texture atlases for production builds.

• Enable atlas export: Select the texture atlas option when exporting from Charios.
• Load atlas in Phaser: Use `this.load.atlas('characterAtlas', 'assets/char/atlas.png', 'assets/char/atlas.json');`.
• Create images from atlas: When instantiating body parts, use `this.add.image(x, y, 'characterAtlas', 'part_name.png');`.
• Reduce draw calls: A single atlas means fewer state changes for the GPU.

Even with an atlas, manage the number of visible characters on screen. If you have dozens of animated characters, consider culling off-screen ones or simplifying animations for distant entities. Smart rendering prevents frame drops.

b.Resource management and pooling

Creating and destroying `Phaser.GameObjects.Image` instances frequently can cause garbage collection spikes. For repetitive elements like enemies, consider using an object pool. Initialize a set number of characters at the start and then reuse them. Pooling objects avoids performance hitches.

Similarly, manage your animation tweens. Stop and destroy tweens that are no longer needed. If an animation is about to loop, restart the existing tweens rather than creating new ones. Efficient tween management keeps your game responsive.

9.Making your character interactive: responding to player input

A character that just plays animations isn't a game. You need to connect your character's movements to player input and game events. This is where your Phaser input handling and state management come into play. Your character needs to feel alive and responsive.

When the player presses 'right', set your character's state to 'walk_right' and trigger the corresponding animation. When they release, switch to 'idle'. This event-driven animation is standard practice and makes your character feel dynamic. Input directly drives character behavior.

• Listen for input: Use `this.input.keyboard.createCursorKeys()` or `this.input.on('pointerdown', ...)`.
• Update character state: Change an internal `character.currentState` variable (e.g., 'idle', 'running', 'jumping').
• Trigger animation: In your `update()` loop or a state machine, call `character.playAnimation(character.currentState)`.
• Handle flipping: If moving left, simply `characterContainer.setScale(-1, 1)` to flip the entire character horizontally.

10.The real takeaway for solo game developers

Importing a Charios rig into Phaser 3 might seem like a lot of steps, but it's a one-time investment that pays dividends across your entire project. You gain incredible flexibility, professional-grade animation fidelity, and the ability to iterate rapidly without redrawing. The initial setup cost is far outweighed by the long-term savings in time and effort. Embrace skeletal animation; your future self will thank you.

Stop wrestling with static sprite sheets and janky animations. Grab your layered PNGs, give Charios a spin, and then follow these steps to get your animated characters into Phaser in under an hour. Check out the Charios dashboard to start building your next character right now.