You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title = "Extending Bevy with C: Communicating via FFI"
3
+
date = 2024-11-14
4
+
[extra]
5
+
tags=["rust","bevy","gamedev"]
6
+
hidden = true
7
+
custom_summary = "We released the bevy_channel_trigger crate to simplify communication between Bevy and foreign libraries or languages."
8
+
+++
9
+
10
+
In this short post we introduce the recently released [bevy_channel_trigger](https://crates.io/crates/bevy_channel_trigger) crate, why we need it to talk to foreign code and what it sets it apart from alternatives. If you just want to start using it, find it on [GitHub](https://github.com/rustunit/bevy_channel_trigger).
Let's start with why we need to talk to C libraries or any other language in the first place. Bevy is written in Rust, Rust is great but not everything can be supported in Rust natively:
17
+
18
+
* maybe you want to interface with libraries that are closed source like Apple's native iOS libraries
19
+
* maybe you want to talk to web APIs using [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen) because your game runs on the web
20
+
* maybe because time is finite and you don't want to [RiiR](https://transitiontech.ca/random/RIIR) (Rewrite it in Rust) all the way down
21
+
22
+
You can just call foreign functions of course right from your Bevy Systems but that is often not a good idea as we don't want to block our game logic. Often these APIs are async as well which means they will produce a result sometime later that we then want to receive back in our Bevy Systems. The schema on the right visualizes this.
23
+
24
+
This is where channels like [crossbeam](https://github.com/crossbeam-rs/crossbeam), [async-channel](https://docs.rs/async-channel/latest/async_channel/) or [flume](https://github.com/zesterer/flume) come in handy to communicate back into our Bevy game logic.
25
+
26
+
Lets look at an example.
27
+
28
+
# Show me an example
29
+
30
+
```rust,linenos
31
+
#[derive(Event)]
32
+
struct MyEvent(i32);
33
+
34
+
fn main() {
35
+
use bevy_channel_trigger::ChannelTriggerApp;
36
+
37
+
let mut app = App::new();
38
+
app.add_plugins(MinimalPlugins);
39
+
40
+
// create channel
41
+
let sender = app.add_channel_trigger::<MyEvent>();
42
+
43
+
// use sender from anywhere:
44
+
thread::spawn(move || {
45
+
let mut counter = 1;
46
+
loop {
47
+
// send events back to bevy
48
+
sender.send(MyEvent(counter));
49
+
thread::sleep(Duration::from_secs(1));
50
+
counter += 1;
51
+
}
52
+
});
53
+
54
+
// register an observer to receive the events sent via `sender`
55
+
app.observe(on_event);
56
+
57
+
app.run();
58
+
}
59
+
```
60
+
61
+
The above example shows how we define an Event type `MyEvent` (line **2**)
62
+
that we want to send as a reaction to a foreign function calling us
63
+
(via callbacks or whatever the mechanism).
64
+
65
+
For the purposes of this example we simulate this by spinning off a
66
+
separate thread (line **14**) and passing `sender` into it. Since this is
67
+
a multiple-producers-single-consumer channel we can clone the sender
68
+
as often as we want.
69
+
70
+
The thread will send this event once a second (line **18**).
71
+
We want Bevy systems to react to these Events.
72
+
Therefore we register a observer (line **25**) that will trigger every
73
+
time this event gets send.
74
+
75
+
Let's look at the code of the observer:
76
+
77
+
```rust
78
+
fnon_event(trigger:Trigger<MyEvent>) {
79
+
letevent=trigger.event();
80
+
info!("trigger with: {}", event.0);
81
+
}
82
+
```
83
+
84
+
Thanks to `bevy_channel_trigger` we can react to these Events now just
85
+
like we would with any other Observer. In this example we simply trace
86
+
this to the console.
87
+
88
+
> You can find a more elaborate example in this
89
+
[drop images into bevy on the web](https://github.com/rustunit/bevy_web_drop_image_as_sprite) demo.
90
+
91
+
# How does crossbeam, flume and others compare
92
+
93
+
You might be wondering why we chose to use **crossbeam** here under the hood.
94
+
95
+
First of all we abstracted that decision away and can easily exchange the
96
+
underlying channel when we want to.
97
+
98
+
As a matter of fact the initial implementation was using **flume**, but
99
+
ultimately we decided to move to crossbeam because it is by far the most
100
+
actively maintained channel implementation in Rust and creates less wasm size than flume.
101
+
102
+
> Flume seems actually more lean in direct comparison to crossbeam but by
103
+
using flume we effectively add another dependency because Bevy itself already brings crossbeam along.
104
+
105
+
Bevy also brings **async-channel** along surprisingly but just like flume
106
+
it pales in comparison to crossbeam in regards to maintenance.
107
+
108
+
# What about bevy_crossbeam_event?
109
+
110
+
Last but not least let's look at the alternative: **bevy_crossbeam_channel**
111
+
We actually used this one before but it dates to a time when the only messaging
112
+
system Bevy had was `EventWriter`/`EventReader`. These matter as they are more performant in cases where you want to send massive amounts of events at the expense of slightly less ergonomic event handling.
113
+
114
+
**But** for our use cases events are used to cross the language barrier primarily and we want to have maximum ergonomics in how to write handlers for these using the new Observer API.
115
+
116
+
Migration of using `bevy_channel_trigger` in our crates like [bevy_web_popups](https://github.com/rustunit/bevy_web_popups) has already begun an will be finished with the migration to bevy 0.15!
117
+
118
+
---
119
+
120
+
You need support building your Bevy or Rust project? Our team of experts can support you! [Contact us.](@/contact.md)
<metaname="description" content="Rustunit offers software development consulting with a focus on rust, game-development and large scale distributed backend services.">
<p>In this short post we introduce the recently released <ahref="https://crates.io/crates/bevy_channel_trigger">bevy_channel_trigger</a> crate, why we need it to talk to foreign code and what it sets it apart from alternatives. If you just want to start using it, find it on <ahref="https://github.com/rustunit/bevy_channel_trigger">GitHub</a>.</p>
<p>Let's start with why we need to talk to C libraries or any other language in the first place. Bevy is written in Rust, Rust is great but not everything can be supported in Rust natively:</p>
38
+
<ul>
39
+
<li>maybe you want to interface with libraries that are closed source like Apple's native iOS libraries</li>
40
+
<li>maybe you want to talk to web APIs using <ahref="https://github.com/rustwasm/wasm-bindgen">wasm-bindgen</a> because your game runs on the web</li>
41
+
<li>maybe because time is finite and you don't want to <ahref="https://transitiontech.ca/random/RIIR">RiiR</a> (Rewrite it in Rust) all the way down</li>
42
+
</ul>
43
+
<p>You can just call foreign functions of course right from your Bevy Systems but that is often not a good idea as we don't want to block our game logic. Often these APIs are async as well which means they will produce a result sometime later that we then want to receive back in our Bevy Systems. The schema on the right visualizes this.</p>
44
+
<p>This is where channels like <ahref="https://github.com/crossbeam-rs/crossbeam">crossbeam</a>, <ahref="https://docs.rs/async-channel/latest/async_channel/">async-channel</a> or <ahref="https://github.com/zesterer/flume">flume</a> come in handy to communicate back into our Bevy game logic.</p>
45
+
<p>Lets look at an example.</p>
46
+
<h1id="show-me-an-example">Show me an example</h1>
</span></td></tr><tr><td>24</td><td><span></span><spanstyle="font-style:italic;color:#4a4a4a;">// register an observer to receive the events sent via `sender`
<p>Thanks to <code>bevy_channel_trigger</code> we can react to these Events now just
94
+
like we would with any other Observer. In this example we simply trace
95
+
this to the console.</p>
96
+
<blockquote>
97
+
<p>You can find a more elaborate example in this
98
+
<ahref="https://github.com/rustunit/bevy_web_drop_image_as_sprite">drop images into bevy on the web</a> demo.</p>
99
+
</blockquote>
100
+
<h1id="how-does-crossbeam-flume-and-others-compare">How does crossbeam, flume and others compare</h1>
101
+
<p>You might be wondering why we chose to use <strong>crossbeam</strong> here under the hood.</p>
102
+
<p>First of all we abstracted that decision away and can easily exchange the
103
+
underlying channel when we want to.</p>
104
+
<p>As a matter of fact the initial implementation was using <strong>flume</strong>, but
105
+
ultimately we decided to move to crossbeam because it is by far the most
106
+
actively maintained channel implementation in Rust and creates less wasm size than flume.</p>
107
+
<blockquote>
108
+
<p>Flume seems actually more lean in direct comparison to crossbeam but by
109
+
using flume we effectively add another dependency because Bevy itself already brings crossbeam along.</p>
110
+
</blockquote>
111
+
<p>Bevy also brings <strong>async-channel</strong> along surprisingly but just like flume
112
+
it pales in comparison to crossbeam in regards to maintenance.</p>
113
+
<h1id="what-about-bevy-crossbeam-event">What about bevy_crossbeam_event?</h1>
114
+
<p>Last but not least let's look at the alternative: <strong>bevy_crossbeam_channel</strong>
115
+
We actually used this one before but it dates to a time when the only messaging
116
+
system Bevy had was <code>EventWriter</code>/<code>EventReader</code>. These matter as they are more performant in cases where you want to send massive amounts of events at the expense of slightly less ergonomic event handling.</p>
117
+
<p><strong>But</strong> for our use cases events are used to cross the language barrier primarily and we want to have maximum ergonomics in how to write handlers for these using the new Observer API.</p>
118
+
<p>Migration of using <code>bevy_channel_trigger</code> in our crates like <ahref="https://github.com/rustunit/bevy_web_popups">bevy_web_popups</a> has already begun an will be finished with the migration to bevy 0.15!</p>
119
+
<hr/>
120
+
<p>You need support building your Bevy or Rust project? Our team of experts can support you! <ahref="https://rustunit.com/contact/">Contact us.</a></p>
0 commit comments