Introduce Bevy-specific requirements

[CorvusPrudens]

This PR provides a few guidelines for audio engines with respect to Bevy integration.

@alice-i-cecile please feel free to suggest further changes! If we want to expand more on these points, Alice will do a better job than me. However, the requirements really aren't that onerous, so I doubt there's too much more to say.

Closes #5.

[CorvusPrudens]

Okay, I think I've captured all the feedback that's actionable for audio engine authors. The justification for each point is still fairly minimal, so we can expand on those further if we want.

[dvdsk]

Currently this is written expecting the reader to know some ECS. I've just looked at ECS for the first time (reading the Bevy quick start guide).

To me its reasonable to require readers to put in that effort, though having just done that myself the ECS driven design section is still not clear to me.

Specifically the section about keeping track of emitter positions and transform. Why is that easy when the components share the same entity?

Is entity sharing something that the audio engine needs to be written for or is that just a detail of how a bevy user interacts with the audio system? If its just a detail of how the user sets things up I would propose removing the sentence. Otherwise I would suggest clarifying it.

[dvdsk]

(nitpick) lets link to the Bevy ECS guide (probably this one right? https://bevyengine.org/learn/quick-start/getting-started/ecs/) since its required reading to understand this section.

[dvdsk]

with transform components you mean effects like low_pass?

[alice-i-cecile]

No, Bevy's GlobalTransform.

[dvdsk]

Suggestion:

• replace 'transform' with a link to bevy's GlobalTransform.
• replace emitter with 'sound emitter' (though that's clear if you keep reading it lowers cognitive load to have the word sound here).

[dvdsk]

Specifically the section about keeping track of emitter positions and transform. Why is that easy when the components share the same entity?

maybe we can feature this in the demo and then link to that code section from here?

[CorvusPrudens]

@dvdsk It's easy to keep track of positions in relation to emitters because a single entity owns both. That means you can query for both at once:

fn emitters(emitters: Query<(&SpatialNode, &GlobalTransform)>) {
    for (spatial_node, transform) in &emitters {
        // ...
    }
}

The spatial_node and transform components come from the same entity, so storing and accessing them together is easy and natural. If you opt for a less ECS-driven design, you'll need to maintain some secondary structure to keep track of which entities (and positions) correspond to the emitters in your audio engine. This is just one among many points in favor of ECS-driven.

The above is a more complete explanation, but I'm not sure it's appropriate for the section on ECS here. If you think the sentence on this will throw some readers off, it may be better to simply remove it and link to a more thorough ECS overview. In any case, people looking to implement a Bevy-native-feeling audio integration will need a solid understanding of Bevy's ECS and the community's general patterns -- and these people probably don't need to be told why an ECS can be nice!

[CorvusPrudens]

Alternatively, if we feel the ECS section really should have some justification on why ECS-driven is preferred, I could add a more thorough explanation and possibly even a handful of other examples that really demonstrate the principle. We could even tuck it into a details element to not distract from the rest of the document.

[dvdsk]

@dvdsk It's easy to keep track of positions in relation to emitters because a single entity owns both. That means you can query for both at once:

fn emitters(emitters: Query<(&SpatialNode, &GlobalTransform)>) {
    for (spatial_node, transform) in &emitters {
        // ...
    }
}

Very clear, thanks for the example. I agree that we should not explain the finer details of ECS here. I'll see if I can find a small tweak to the text that would help a bit with understanding without distracting.

[dvdsk]

We could even tuck it into a details element to not distract from the rest of the document.

Some sort of requirements appendix might work?

edit: we could then go into a little more detail on other elements too, such as channel order/masking