Mapping Tiled custom properties to Bevy components

[adrien-bon]

Hey,

As discussed in my last PR, I started to implement mapping from Tiled custom properties to Bevy components.

The system is heavilly inspired from bevy_ecs_ldtk and bevy_entitiles (which I am using in my game right now).
The idea is to let the user define Tiled custom properties and corresponding Bevy components / bundles. When loading the map, the crate will automatically spawn said components on corresponding tile entities / object entity.

Here is my dev branch:
main...adrien-bon:bevy_ecs_tiled:wip/user_properties
It currently only work for tiles, not for objects (I did not want to mess with your colliders implementation) eventhough nearly everything is there. It seems to work with my basic example but I did not test it in depth.

I wanted to quickly code something so we can exchange about the way we want to handle this.
For instance, I believe we could use this to handle colliders instead of the list we currently have. See here

Sooo, let me know what you think about this so we can move forward :)

[stevepryde]

I've had a brief look and it looks really cool.

Regarding the colliders, I think it would be good to provide a way to specify which shapes should have colliders added and which ones should be treated differently. That goes for object layers as well as tiles. Just because tile shapes are called collision shapes in Tiled doesn't mean we can't use them for other things.

Unifying the way we handle these seems like a good idea. Btw getting the collider shapes working correctly was a nightmare because of the different co-ordinate systems. Bevy has positive Y pointing up while Tiled points down. But I think you were referring to changing where/how that logic gets invoked, not changing the actual construction of colliders, if I understood correctly.

Automatically mapping custom properties to components seems like a good idea. And the macro makes that easy to use.

Just a suggestion with the macro. Have a look at the darling crate for parsing attributes. It makes everything so much nicer.

We will need to restructure the repo to put the macro and main crate side by side. It could be a cargo workspace if that helps.

How do you feel about being a co-maintainer?

[adrien-bon]

I've had a brief look and it looks really cool.

Thanks!

Regarding the colliders, I think it would be good to provide a way to specify which shapes should have colliders added and which ones should be treated differently. That goes for object layers as well as tiles. Just because tile shapes are called collision shapes in Tiled doesn't mean we can't use them for other things.

The idea was to use the tiled_shape_as_collider attribute on user-defined TiledObject to select on which "Tiled custom type" we want a collider for. And you are right, we could do that for tiles as well.

What do you mean by "should be treated differently" ?
Do you mean like spawning a mesh / a sprite / another physic object using the shape ?

If I follow along, yes, it would be very nice and we should consider that.
However, as you said in one of your comment earlier, I don't think we should handle all possible use cases but instead give power to the user to do what he wants.
For instance, what if he prefers to use avian instead of rapier?
We cannot have one tiled_shape_as_XXX attribute per use-case.

One solution could be to replace this with a tiled_callback attribute.
It would take a list of functions, using as argument both the EntityCommand and either TileData or ObjectData (where the Shape information is stored). This way, the user can deal with it as he wants: create a collider, spawn a sprite, spawn a mesh, etc...
Bonus point: we could provide some sort of "ready-to-use" callbacks, for instance a shape_as_rapier_collider.

One of the down-side of this is that we should also provide some "common" parameters (one that comes to mind is the Res<AssetServer>. If we don't provide enough, the user won't be able to do what he wants.

Maybe there is a better way to handle this ?

Unifying the way we handle these seems like a good idea. Btw getting the collider shapes working correctly was a nightmare because of the different co-ordinate systems. Bevy has positive Y pointing up while Tiled points down. But I think you were referring to changing where/how that logic gets invoked, not changing the actual construction of colliders, if I understood correctly.

I can imagine ! :)
And yes, I don't want to touch this at all if it works! I'm bad at maths!

Automatically mapping custom properties to components seems like a good idea. And the macro makes that easy to use.

Just a suggestion with the macro. Have a look at the darling crate for parsing attributes. It makes everything so much nicer.

Thanks for the info, I'll have a look!

We will need to restructure the repo to put the macro and main crate side by side. It could be a cargo workspace if that helps.

I'm still new to Rust so I don't really know the exact implications.
From what I see in The Book, cargo workspace seems to fit our use case.
So whatever the best to ease the publishing part!

How do you feel about being a co-maintainer?

Sure! Why not! :)
I'm still pretty new to Rust and gamedev but eager to learn.

However, I won't have as much time as I did in the last few days, as I was at home on PTO.
Also, I'll be gone for a week starting tomorrow without access to a dev laptop.

[adrien-bon]

I finished what I wanted to do in terms of code and achieved to get something usable! :)

I did not open a PR yet because it still need some polish and a proper documentation (with associated examples) and I won't have time to do that now. It will have to wait next week.
Here is the current dev branch. Feel free to review and even contribute if you want ! :)

What I did

• Re-organized a bit the repository. Now, we have dedicated for components and for events. I feel it's better to separate these from the reste of the code. I also reworked a bit the physicsdirectory to simplify it since I felt it was not big enough to have dedicated directories. Finally, I put everything related to user_properties in a dedicated directory.

• Added a callback and an observer system. As I said in my previous comment, instead of having one particular attribute for one particular use-case, we can now define either a callback and / or an observer. I did not choose between these two because I think they can both be useful:

  • Callback will be called immediately after the user properties are inserted (I believe it will not even be available in the ECS world since technically the system spawning it would not have returned yet). Callback has a limited number of arguments (essentially, only the TileDataor the ObjectData) but it could be usefull to quickly spawn additional Components on the same entity.
  • Observer will be triggered after some time through an event on the entity (new from Bevy 0.14!). This allow us to take full advantage of Bevy and to get all the arguments we want: Resources (hello AssetServer!), Query (so we can acces other entities component), everything! The main of this method is that there will be a slight delay between the custom component spawn and the observer call. I think it's acceptable.

• Removed all the physics stuff from loader.rs. I believe it should be used through the user_properties system. I wrote a small example in hex_map with custom tiles. I also removed the TiledMapSettings because it was not needed anymore (we could always re-add it in the future if needed). I kept the ObjectNameFilteras I believe it can be very useful, eventhough we can now distinguish between objects based on their class and not only on their name. I did not create "ready-to-use" observers for colliders, because right now we can only have a single observer per TiledObject / TiledCustomTile. But it's definitely something I have in mind (see below the "macros stuff" for more infos on this).

What remains to do / What I'm not sure about

• Content of the TiledObjectCreated and TiledCustomTileCreated structs. I think we may need to add some stuff here in the future. For instance, to get information that are either not Bevy component but "Tiled only" data, or some information that are also stored in components but either not yet accessible from the observer or that we want access to from the callback (since we cannot perform queries from the callback). Right now, I put the minimum, I think we will see when / if the needs arise. On a side note, I put an offset in the TiledObjectCreated struct. I'm not sure what exactly it is but it seems needed by the physics system.

• ECS-World access for callbacks. I though at some point about having a callback with a mut World parameter. It would be very handy so we can access the ECS world from our callback (which are a bit limited right now). I did not got this way because it implied to basically put everything in the loader with world access too, which was quite complex. Maybe we will need it at some point but I prefered to increment over a first working version and not change everything.

• Macros stuff. I did not use the darling crate as you suggested. I prefered to stick to what I know: there is a lot of room for improvement. Speaking of this, currently, we only support one observer and one callback. It could be nice to be able to have more. To give an example, you can do #[tiled_callback(my_callback)] but you cannot do #[tiled_callback(my_first_cb, my_second_cb)]. One advantage to be able to have several callbacks or observers would be to provide the user with "ready-to-use" functions. Right now it would feel a bit weird since we don't want our user to choose between defining its own callback/observer and calling ours.

• Cargo workspace. I did not change anything regarding the associated bevy_ecs_tiled_macros crate because I'm not sure what to do. I'm not familiar at all with the process of publishing crate / organizing Rust repository. There is very probably some room for improvement, so feel free to provide some directions ! :)

[stevepryde]

Thanks for the write up. I haven't had time to look at it yet. I've been focused on the Bevy game jam. I will take a look hopefully later this week when I get some time.

[adrien-bon]

No problem, take your time :)

Another idea: I was thinking about a new interface for the user to be notified for every tile added, even those without custom properties.
This is not directly related to this discussion, but it could use the same mechanisms / same kind of interface (ie. observers or callbacks).

The idea would be to be able to attach new "generic" components on our tiles that do not depend on the tile kind.
Instead of adding a placeholder Tiled property to trigger the mechanism, it would be nice to trigger a global notification for all tiles.
One application would be for instance to add bevy_mod_picking components to add some interactivity to the grid.
A bevy_ecs_tilemapbackend already exists and I think it would be nice to be able to interface with it.

I'll try to open a PR regarding this topic after the "custom properties" one.

[stevepryde]

Hey, these are great ideas.

Unfortunately after working on the game jam I've decided to take a step back from Bevy and return to Godot. I have a few game projects that I'd really like to finish so it's mostly a matter of priorities, and I felt that I wouldn't be productive enough in Bevy to justify it.

I hope you'll continue working on this crate. If you're happy to take it over, I will transfer the ownership to you. I can provide support on any of the Rust things like how to publish it etc. You'll need a crates.io account if you don't already. Let me know if you're happy to do that.

[adrien-bon]

Oh :( That's too bad..
Did you have time to publish something for the Bevy game jam ?

Yeah, I can take over this crate. I mainly do 2D stuff on grid, so it match my use cases.
Don't know exactly how it works since I'm pretty new to Github / open-source contributions: let me know how you want to proceed

[stevepryde]

For the Github side I think you can just use your fork and enable issues on there etc but it might be nicer if I transfer the repo, especially since it's all fairly new. It's not like I'm handing over years of work for example.

For crates.io I just need to add you there.

I did have time to publish my game for the Bevy jam. I was pretty happy with it - I think it turned out pretty well. I had major issues with the physics. I don't think rapier is good for actually preventing objects from going through colliders. It seems that in the right circumstances stuff just goes through walls. I really lost all confidence in it as a physics lib. Maybe there's something I was doing wrong, but my "fix" was to use a collision hook to just force the player away from the walls. It results in jitter which I then had to compensate for in other ways. I also had issues with events where you can "trigger" an event and observers will fire, but if you write the same event using EventWriter the observers will not fire. And likewise an EventReader will not see "trigger"ed events even though it's the same event type. That feels strange to me.

After the jam I tried building the same game in Godot and I had the basic game working in under an hour. I have nothing against Bevy and I'll continue to follow its progress, but realistically I just find myself far more productive with Godot.

[stevepryde]

Let's move the handover discussion to email. You can find my email address in the commit log.

[adrien-bon]

Closing this discussion since I openned a PR for these changes (see #10)