Open MiniaczQ opened 2 months ago
This takes the bevy_color
approach to API design. This duplication also extends to EntityRef
, EntityMut
, and DeferredWorld
. We've struggled to keep these in sync before. The downside of course is that core functionality gets moved off of the struct itself, making it a bit less visible in the docs.
We should consider allowing methods, e.g. spawn
to exist both as a struct impl and as a trait impl.
The traits will still ensure that all methods are covered and multiple types share functionality,
while if the type is known the struct impl will be selected and fully documented for that scenario.
I'm not worried about migration, so I'd prefer to avoid duplicating the APIs.
As part of this, I would also propose considering Spawn::spawn_with
as a generalization of Spawn::spawn
:
spawn(bundle)
= spawn_empty
+ add(insert(bundle))
spawn_with(command)
= spawn_empty
+ add(command)
Old related issue: #5647 (for .spawn()
APIs only)
I think this could use a working group once there's enough bandwidth, since it'll require design work and has cross-cutting impact.
Agreed with that. Lots of changes that need to be made in concert, and high levels of controversy.
Another family of traits is GetCommands
, GetWorld
, etc.
Commands
and World
are usually the core of implementing additional functionality, if access to them is unified across word, subapp, app, etc. it's going to reduce extension trait boilerplate and remove bevy_app
requirements
What problem does this solve or what need does it fill?
Parts of ECS API are missing methods, which have no reason to not exist.
Types that this is most visible on are:
Commands
ChildBuilder
EntityCommands
World
WorldChildBuilder
EntityWorldMut
For example, you cannot use
trigger
fromChildBuilder
, but if you spawn an entity and getEntityCommands
you can callEntityCommands::commands()
and thenCommands::trigger_targets()
.Proposed solution
This issue proposed the following traits: a)
Spawn
withspawn_empty()
andspawn()
for [1, 2, 4, 5], b)GetCommands
withcommands()
for [1, 2, 3], c)GetEntity
withentity()
for [1, 2, 4, 5], d)Trigger
traittrigger()
andtrigger_targeted()
for [1, 2, 4, 5], e)TriggerEntity
withtrigger()
for [3, 6], f)Observe
withobserve()
for [1, 3, 4, 6], g)ModifyEntity
withinsert()
andremove()
for [3, 6], h)WithChildren
withwith_children()
for [3, 6].In general pairs of [1, 4], [2, 5], [3, 6] should share traits.
Now, this is just a proposal. I want this issue to help decide the actual scope. Ideally, key traits would make it to 0.14 without introducing breaking changes.
Example implementation for
Spawn
What alternative(s) have you considered?
The traits can theoretically be a 3rd part crate, but missing methods need to be added in
bevy_ecs
anyways.Additional context
This is mostly frustrations collected during development of Bevy Jam Template Relevant discord discussion can be found here