bevyengine / bevyengine/bevy

Use traits to make ECS APIs for working with entities more consistent

Open
#14,231 10 comments 11 reactions 0 assignees View on GitHub
A-ECS C-Usability D-Straightforward X-Contentious
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 22h
Merged PRs (30d)
161

Description

## 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:
1. `Commands`
2. `ChildBuilder`
3. `EntityCommands`
4. `World`
5. `WorldChildBuilder`
6. `EntityWorldMut`

For example, you cannot use `trigger` from `ChildBuilder`, but if you spawn an entity and get `EntityCommands` you can call `EntityCommands::commands()` and then `Commands::trigger_targets()`.
```rs
fn spawn_trigger(&mut self, event: E) -> EntityCommands {
// Type juggling to get around lifetime downcasting.
// We cannot recover `entity_commands` if we ever drop it.
let mut entity_commands = self.spawn_empty();
let entity = entity_commands.id();
let mut commands = entity_commands.commands();
commands.trigger_targets(event, entity);
entity_commands
}
```

## Proposed solution

This issue proposed the following traits:
a) `Spawn` with `spawn_empty()` and `spawn()` for [1, 2, 4, 5],
b) `GetCommands` with `commands()` for [1, 2, 3],
c) `GetEntity` with `entity()` for [1, 2, 4, 5],
d) `Trigger` trait `trigger()` and `trigger_targeted()` for [1, 2, 4, 5],
e) `TriggerEntity` with `trigger()` for [3, 6],
f) `Observe` with `observe()` for [1, 3, 4, 6],
g) `ModifyEntity` with `insert()` and `remove()` for [3, 6],
h) `WithChildren` with `with_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`](https://github.com/bevyengine/bevy/pull/14247)

## 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](https://github.com/TheBevyFlock/bevy-template)
Relevant discord discussion can be found [here](https://discord.com/channels/691052431525675048/1258521739395203174/1259991322836861070)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.