#phaser3

[browndragon]

The Problem With Arcade Physics

TL;DR: I have a fix for arcade physics, but it's disruptive, so I'm not trying particularly hard to get it upstream. Let me know if I should! My asks (etc) are open!

If you want it, it's available @ [my github](https://github.com/browndragon/phaser/tree/solidArcade)

Phaser comes batteries-included with arcade physics, an AABB basic physics engine. So of course I'm building fidough, my ridiculous boxes on conveyor belt game with it. Which is insane. It's fine.

But I hit a problem: naive conveyorbelts didn't work:

Okay. So why does that happen?

The code was simple:

function overlap(sprite, tile) {

const {x, y} = this.offsets[tile.index];

console.assert(Number.isFinite(x) && Number.isFinite(y));

ticknudge(sprite, x, y);

}

function ticknudge(sprite, x, y, still=.01, nudge=.001) {

sprite.body.x += x;

sprite.body.y += y;

sprite.body.updateCenter();

}

So what gives? that looks right! It isn't.

_dx and _dy: why?

The old code had a simple flaw: it had multiple representations of the same data, and needed to remember them all. The core metaphor of arcade physics separation is to determine the motion of the two intersecting objects and to restore them roughly antiparallel to the direction of motion.

This is deadly: motion is underspecified. Antiparallel isn't hugely specified. Motion brings in the notion of time.

Obviously, the old code had `velocity` concept, it is a physics engine. Velocity is tricky. In a physics engine, it represents the continuously updated per-frame motion component, but it is obviously not the actual total amount of movement that was definitely executed. For instance: if the physics body has a lot of drag and perpendicular acceleration and lots of colliding objects, its actual displacement over the last tick (upcoming AND over the last frame!) isn't necessarily the velocity times time.

This is a problem for me. Remember, my whole schtick is walkways, which are effectively sticking an object in a constant velocity frame of reference relative to the camera, which for one reason and another isn't ideally represented with careful force-and-drag (or absolute max veloc), but instead a per-tick direct modification to colliding objects' velocity.

The first advice was to ensure that if I modified `position.x`, to modify `_dx`. That's definitely good advice; the way that Arcade Physics detects motion is through that _dx thing; if I modify position.x of a completely still object, it won't reflect in its actual motion, and so it won't reject from the walls. QED.

Okay, so let's grab a snap with the above code modifying _dx & _dy whenever we modify position.x and position.y. Spoiler, it still doesn't work!

This is the `embedded` logic biting us, deciding that two colliding objects without motion can't be repaired. At first, I thought that Phaser was wrong when it estimates how much an arcade body has moved, because it uses velocity ("per-tick added motion") instead of a continuously evaluated _dx & _dy ("per-tick observed displacement"); it does so much math already that I just deleted _dx and _dy in favor of subtracting previous position from current position. I also gave it enough intelligence to extrapolate a per-second displacement from the observed previous-tick displacement.

And do you know what? It still didn't work!

On passing data between ticks

The logic was simple. The physics algorithm is:

For each body: Start the frame: copy bounds and transform information from the game object back into the arcade body

For each body: Start the tick: calculate next position from velocity, drag, acceleration, etc

For each collider: Execute it! (and by coincidence, I'm doing object intersection first and walls nearly last)

Goto 2 if there's more time left in this frame

For each body: End the frame: Push position information back to the game object.

So what's missing? The only logical time to snapshot prev (and calculate dx) is on step 2. But my treadmills execute in step 3! So their motion is *always* forgotten by this algorithm, since the snapshot captures the value they'd written; any objects that are stranded within walls seem always to have been there, since the current and previous position are equal as an accident of this algorithm.

The Fix

We truly don't need dx as a body property; it's just the difference of current and previous position, so we can throw that out. But we need to capture previous position in such a way that the velocity in the last tick and the wall rejection, tread application etc are included! The obvious fix is to calculate a snapshot just *after* calculating position at 2, but to put it in place just *before* calculating 2 on the next run through. As a result, the displacement on each tick is the previous tick's collider adjustments, any updates from the game object position [for ticks that span frames], and the current round's velocity update. There's a risk here! We actually sync out to the game object a value which is never actually used as a previous value in the physics engine. This doesn't seem to be a problem in practice, but perhaps there are exotic collision schemes which pose a problem here.

This version no longer uses velocity as an input to collision or separation, preferring to use calculated-on-demand dx & dy values. Everywhere. This means that everything "just works":

If you modify your game object's position during e.g. `update`: the body will be set to that position during its next step 1 as before (and then have its velocity added), but newly, the body's prev during update & collision will be the value just after the velocity was added

If you modify your body's position during a collider: the body's prev was snapshotted before any colliders ran, so that new position will count as motion for collision and embedding logic.

So, the ridiculous finished project: fully generic relative motion on walkways in arcade physics. Whew!

[browndragon]

Phaser tile + arcade shenanigans

I'm actually designing fidough levels now, since I've got autogroups (& colliders), dough springs, treadmills, 2d models, and other fanciness. I've open sourced all of it, reach out if there's something you want that I haven't already made available or want some help with.

I wired it all together and... it didn't work. I could either have map collisions working or else have intersprite collisions working. Everything I'm doing is sane, so the bug is either in phaser's implementation or else I've misunderstood something (latter more likely). But it's easy enough to test for phaser bugs, so I did (link to the multimedia tax). The problem is a programmer understanding one.

What I learned along the way (no I haven't fixed the underlying issues yet)

Tile collision faces are mess(ier than you could possibly imagine)

Say that you have a map composed of tiles like floor, wall, spike, coin (for a variety of reasons that's silly, but whatever), etc, and of mobs and pickups like player, enemy, coin (again!), maybe bullet, you know, that sort of thing.

The graph of interactions is complex. Neither players or enemies can walk through walls. Players can step on spikes but they hurt; for simplicity, we might say that enemies simply cannot step on spikes. Players can step on coins (and flip them into floor), but we'll say again that enemies treat coins as solid.

Phaser supports this super duper messily. At the end of the day, the internal structures are boolean "does this block movement" and maybe a callback. Which means that if the answer to blocked movement is complex -- you have characters that can swim and fly and so on -- it's going to be a bit uphill.

There's actually an example on the included game. If you line yourself up with the spikes along the bottom edge of the map, you can walk through walls. You see, phaser checked whether it should separate you when you entered the spikes (they're solid... to robots...) and the spikes said "no, let them in, we'll just hurt them". But Phaser removed the internal boundary between the southern edge of the spikes and the wall -- because the wall is solid too! -- and so the player was effectively embedded in the wall the moment they touched the spikes!

The answer is annoying; disable recalculateFaces for anything you know you want to treat as a separate crossing domain. So for instance in this example, I wanted to prevent robots from stepping on spikes and players from crossing over from spikes (ouch) to walking through walls; by doing this I accomplish that. I think there will be micro-jaggedies as a result. Alas. Ai me.

Phaser tilemap callbacks basically require double dispatch

You can associate one callback per tile type -- not per tile type per colliding group, note. So since your one tile layer likely has tiles that different units respond to differently, you have to do double dispatch from the tile callback back into the colliding instance. Due to... reasons... the callbacks are always called (sprite, tile) (even if your collider registered them in the order (layer, spritegroup)), so it seems very likely that the tile callback is always literally (sprite, tile) => sprite[`on_${tile.type}`](tile) (or similar).

What should you do?

Note, I haven't done any of this.

A lot of people suggest you have one colliding layer and n art layers. I've resisted that for a while, but I think I have to give it up. If you had one colliding layer per movement type, you could absolutely have water and walls block walking, floor and walls block swimming, and walls (only) block flying. Building that out without a separate layer per collision type seems hard. You can even derive that on the fly (generate the additional colliders dynamically off of the loaded map's tile types).

[browndragon]

An update on singletongroups

Continuing from Automatic Collision Groups, I've updated and provided an npm-able external package and rethought the actual names and examples; this post supercedes that post.

What is this?

When trying to publish "Automatic Collision Groups", the biggest problem I'd run into was the name. I was trying to augment a Sprite with the behavior of a Group and of a Collider; I tried a few different names (is it a Club, a set of interests and ideas that has a formal existence beyond its current membership? A Polity? A Gang?), but it was always messy.

The existing logic worked, but to pull it into a library, I needed to discuss what the moving parts were, and I hated it.

Enter SingletonGroups

The big change from when I started this project to now was the explicit addedToScene() method new in Phaser 3.50. That fixes a lot of the problems I'd had around initializing sprites, and so it allowed me to stop treating the thing I was writing as a coordination point, and instead just focus on the object/group/collider organizational principle.

Well! The easiest solution for that is to stop focusing on the Sprite and to instead focus on the Group. So that's what I did; the newest version is just a scoped singleton group, scoped at the level of the scene.

What do they do?

The S[ingleton]G[roup].Groupis a subclass of Phaser.GameObjects.Group (and SG.PGroup of Phaser.Physics.Arcade.PhysicsGroup). Its static SG.PGroup.group(scene) method does an atomic cache lookup on the scene in a symbol-guarded class-keyed map for the group class itself; if it's not there, it uses the class' one-argument constructor to construct a new group and returns it. This also automatically subscribes to scene shutdown and cleans itself up.

You can of course override SG.PGroup.install(scene) to do additional post-scene-addition method calls (like: tuning physics), or SG.PGroup.constructor(scene) to pass additional parameters (like: config options). I kept the same API for PGroups as I'd already had for identifying collisions -- PGroup has static methods static get colliders() and static collider(a, b), overlaps and overlap, and optional process; on static insert(scene) (which remember is called once per scene on group, the necessary colliders are automatically created.

This does nothing to modify phaser game objects. For that, we add the method SG.induct(gameObject, ...sgs), which just adds the gameObject to the instances of each named class SingletonGroup in sgs, and SG.Member(clazz, ...sgs) which provides a safe-for-multiple-call-of-Member subclass of clazz which automatically overrides addedToGroup to add instances of the subclazz to the groups identified in sgs.

Whew!

WHERE ARE MY VIDEOS AND PICTURES

Next post. The unit test I wrote was fun enough that I posted it online.

[browndragon]

Phaser3 sprite lifecycle, groups and groupalikes

TL;DR: It's an evolved mess and I'm not sure how to escape the morass. Remember to implement everything important to you in three places. Lots of places suggest subclassing sprite; I'm not sure that's the best idea anymore [if it ever was].

How do you work with a scene?

Phaser3 starts strong, with a small number of justifiable stances: the display list is (basically) flat, so manage your own overlaps. Everything is a plugin, including physics and the display list, so you can add your own if you want to. Managing object lifecycle is a little tricky, so there are groups which know about the sprite .destroy() method so that you can more easily clean up dangling references. And so on.

If you read the examples, they basically proceed in a straight line:

1. create sprite A 2. create sprite B 3. create the A->B collider 4. profit

Wrinkle 1: These are all different things

The displaylist, the physics bodies list, and each group are all separate implementations of the same underlying concept (which is also provided in a reusable wrapper, ProcessQueue ). Mostly this is fine, but it means that you'll find yourself specializing methods in ways which seem to me to be repetitive.

Why a PQ? Because the displayList and physicsList (at least) actually do implement a stepped, phased logic. Groups might get away without this; they at least use underlying Phaser.Struct.Sets to manage their membership. But since nobody else does, that's not very helpful; I imagine in an es6 world that class would go away.

Wrinkle 2: Creating a sprite isn't adding it to the scene

You can create a sprite without adding it to the scene. Maybe it's in an object pool, maybe it's hopping between scenes; whatever. The sprite constructor requires a scene reference, but it doesn't matter; taking a scene reference doesn't mean you're on the scene's display list. You have to do that via interaction with the display list (explicitly or via GameObjectFactory i.e. scene.add.create or GameObjectCreator + scene.add.existing).

Wrinkle 3: The API is 'helpfully' verbose

As alluded in the previous wrinkle, there's more than one way to spell it at the scene level. Hang on, it gets worse: groups are not just passive containers of membership; they're also factories of membership via Group.create(...), .createFromConfig(...) and .createMultiple(...). Are those objects created using the overridden scene.add objects you might want? Of course not.

Wrinkle 3a: Groups are 'helpful' to work around the number of ways there are to do this.

Groups will optionally modify the scene displaylist and updatelist. PhysicsGroups go further, and sneakily use internal only create and remove handlers to give their members physics bodies; these have special handling in the base Group implementation.

These methods are technically available to you, but far too complex to imagine they were planned.

So how does that extend for e.g. Ammo sprites which should be in the Ammo group for colliding against enemies, but also in the Bounded group for colliding against the edges of the map & the MapBounded group for colliding against the contents of the map?

It doesn't. You can't add your own special cases; your single Ammo create callback will have to enumerate the other groups to add your new objects into (though you can to some degree rely on them cascading; if all MapBounded are also Bounded then you should rely on MB to give you B).

Terrible consequences

There's no obvious coordination layer for sprite initialization. Since the constructor doesn't add the sprite to the display list, it shouldn't put the object in the world with a physics body. It shouldn't be added to any tracking groups which would otherwise own it -- after all, it might not be on the display list yet.

There's a lot of code specialization and repetition; if you provide a new class ClownSprite extends Sprite, then you have to override the GameObjectFactory AND the GameObjectCreator; one to create the object, the other to actually wire it into the scene (plus anything else that needs to know about it).

There's unrelated code specialization, since groups do a sort of unspecified amount of work for you; anything you did to add your own sprite type might also require you add your own group methods too!

Summary: It's pretty messy!

How would it work in my dream world?

The scene field on sprite should be immutable; a sprite should be as linked to its parent scene as an iterator to its parent container. As a result of this, constructing a sprite is synonymous with adding it to the scene.

This implies that there are some fields currently on sprite which should be extracted up into some other reusable class. For the most part I think this is a historical accident, though -- sprites should be flyweight, since most of their work is in state tracking objects like animation managers (, transforms, timers, mouse click targets, pubsub event objects, etc). To the degree that they have all those things, surely there's a more efficient way to support them than to precache objects -- if it's too expensive to spin up an animation manager on demand, are we sure we're even going to use it? Surely the better-still solution is to spin up the object in the scene, but off screen somewhere and invisible? Etc.

Can we get there?

I kind of doubt it, without having thought hard enough about it. Phaser4 is under development and promises to break APIs, but their fix to the same conundrum is different (ctrl-f 'Effect layer'; note that the sprite constructor no longer takes a scene reference). Per the discord, the solution for physics groups is "it's up to you" (that is, current ph4ser plans include offering physics libraries as a side hustle, but updating sprite positions to match body locations is left as an exercise to the reader).

I haven't thought through the consequences of this; if scene is more "normal" AND physics is outside of the library, than many of these issues -- which at core center around trying to identify who-collides-with-what -- might just disappear. Or get one thousand times worse. Only time will tell!

Can I get there unofficially?

Maybe. What I'm imagining is a method on Sprite like Sprite.enterScene called when being added to the scene -- that solves the question of where to unify the scene.add and group.create methods -- which would give a natural place to override and add to any additional required groups. Override the various places that need to be overridden just once, adding your Once And For All GameObjectFactory, GameObjectCreator, and Group subclasses.

But this still requires enumerating each of the groups you want to join (barring, like, class hierarchy stuff) -- and worse, since it's on the class, you've introduced some tight coupling.

So, still an open question.

[browndragon]

Doughwobbles 2

FYI doughwobbles is now publicly available

[browndragon]

Got sidetracked (so I published a new library)

Got sidetracked from working on Fidough, so I published a library instead.

Fidough has Dogs and Treadmills and Walls and Dough and... and the more I worked on it, the more concerned I became that I was going to get eaten by complexity. Let's say this is popular, beyond my dreams of avarice; then expanding it will be pretty important. Adding new art assets is annoying but doable, but I was faced with a problem. Let's say for sake of argument that we have

class Mob extends Phaser.Physics.Arcade.Sprite {...} class Dog extends Mob {...} class CustomDog extends Dog {...} class PieRat extends Mob {...}

If CustomDog has more animations than Dog, I'm going to get into deep doo-doo and fast, because PieRat and Dog can both run, but their animations are different... I foresaw pain.

What I wanted to be able to do was have something like

class Running extends Mystery { } class Dog extends Mystery { } class CustomDog extends Mystery { } class PieRat extends Mystery { }

so that the logic for run existed in one place... and Dog (, CustomDog, PieRat, etc) merely implemented the animations for run (and dig etc).

Well! Wait no more, I've published phaser3 aspects on github & npm to fill that need.

You can now write code almost literally like the "good" example, and it will self-assemble and execute, just like you might want.

Now, back to what I was doing.

[browndragon]

First

Hello world.

I'm a (former?) programmer taking some time off and making some games. As I write this, I have a few ideas I'm playing with, and I'll be working on developing the fundamentals of game design, animation, art, writing, and everything else I haven't had time to work on to-date.

What do I expect to write about here?

Lessons learned. Development logs for the various games I want to make. Art tips and tricks for extremely non-artists. A few different games published along the way towards making a more final game. Descriptions of the upcoming games under the cut.

The zeroth game: Phaser Plugins

I plan to publish the various parts of my games as phaser plugins. Which means it behooves me to keep track of, like, demos and unit tests for the plugins. So some of them might rise to the level of usable games, and I'll tend to publish those (and discuss them) here.

The first game: Fidough

The first game has been through a few names, but its working title is Fidough. It's a bit like Lemmings, or other worker-placement video games: in this one, you attempt to operate a bakery staffed entirely by dogs. Different dogs have different proclivities: puppies require frequent breaks, terriers prefer to dig down and enjoy hunting pie rats, setters dig upwards, retrievers excel in bringing ingredients where they're needed, sheepdogs are mops, and so forth. Levels are timed (probably turn-based), and so you attempt to optimize baked goods generated per level, using as few dogs as possible. This will get some game play mechanics ironed out, get something low-stakes published, and maybe provide some passive revenue.

The target game: Fairest

The "real" game is a SNES adventure/RPG called "Fairest". You're Rose Red, a human raised by bears in a storybook world like that of Disney or Narnia. The wicked old queen is dead, the new young queen has ascended the throne, and things aren't better yet, so you strap on your broom and set on a quest to set things right. I want to spend some time making other games first, figuring out the ins and outs of publishing with those and build up some techniques for game and level design, before I get into this.

Expect updates here!