bevy_dojo/
lib.rs

1//! # Bevy Dojo: A Bevy plugin for Starknet integration
2//!
3//! `bevy_dojo` provides a plugin for integrating Starknet blockchain functionality
4//! with the Bevy game engine. It enables executing Starknet transactions from Bevy
5//! systems in a non-blocking way, making it ideal for games that want to interact
6//! with smart contracts on Starknet.
7//!
8//! ## Features
9//!
10//! - Non-blocking Starknet connection management
11//! - Transaction execution with automatic status monitoring
12//! - Environment variable or explicit configuration options
13//! - Seamless integration with Bevy's ECS
14//!
15//! ## Setup
16//!
17//! Add the plugin to your Bevy app:
18//!
19//! ```rust
20//! use bevy::prelude::*;
21//! use bevy_dojo::prelude::*;
22//!
23//! fn main() {
24//!     App::new()
25//!         .add_plugins(DefaultPlugins)
26//!         .add_plugins(BevyDojoPlugin)
27//!         .add_systems(Update, keyboard_control)
28//!         .run();
29//! }
30//! ```
31//!
32//! ## Environment Variables
33//!
34//! The plugin uses the following environment variables by default:
35//!
36//! - `STARKNET_RPC_URL`: URL of your Starknet RPC provider
37//! - `STARKNET_ACCOUNT_ADDRESS`: Your Starknet account address (as a hex string)
38//! - `STARKNET_PRIVATE_KEY`: Your private key (as a hex string)
39//!
40//! Alternatively, you can provide these values explicitly by replacing the
41//! `DefaultStarknetConfig` resource.
42//!
43//! ## Example: Keyboard-controlled Connection and Transactions
44//!
45//! ```no_run
46//! use bevy::prelude::*;
47//! use bevy_dojo::prelude::*;
48//! use starknet::core::types::{Call, Felt};
49//! use std::str::FromStr;
50//!
51//! fn keyboard_control(
52//!     keys: Res<Input<KeyCode>>,
53//!     runtime: Res<TokioRuntime>,
54//!     config: Res<DefaultStarknetConfig>,
55//!     mut sn: ResMut<StarknetConnection>,
56//! ) {
57//!     // Connect to Starknet when the user presses C
58//!     if keys.just_pressed(KeyCode::C) {
59//!         init_starknet_connection(runtime, config, sn);
60//!     }
61//!
62//!     // Execute a transaction when the user presses T
63//!     if keys.just_pressed(KeyCode::T) {
64//!         let calls = vec![
65//!             Call {
66//!                 to: Felt::from_str("0x123456...").unwrap(),  // Contract address
67//!                 selector: Felt::from_str("0x987654...").unwrap(),  // Function selector
68//!                 calldata: vec![],  // Function arguments
69//!             },
70//!         ];
71//!
72//!         execute_transaction(runtime, sn, calls);
73//!     }
74//! }
75//! ```
76//!
77//! ## Connection Status
78//!
79//! You can check the connection status by examining the `StarknetConnection` resource:
80//!
81//! ```no_run
82//! fn display_connection_status(sn: Res<StarknetConnection>) {
83//!     if sn.is_connected() {
84//!         println!("Connected to Starknet");
85//!     } else if sn.is_connecting() {
86//!         println!("Connecting to Starknet...");
87//!     } else {
88//!         println!("Not connected to Starknet");
89//!     }
90//! }
91//! ```
92
93// Re-export modules
94pub mod starknet;
95pub mod tokio;
96
97// Import and re-export main types for convenience
98use bevy::prelude::*;
99
100// Main prelude module that users can import
101pub mod prelude {
102    pub use crate::BevyDojoPlugin;
103    pub use crate::starknet::{
104        DefaultStarknetConfig, StarknetConnection, check_sn_task, connect_to_starknet,
105        execute_transaction, init_starknet_connection,
106    };
107    pub use crate::tokio::{TokioPlugin, TokioRuntime};
108
109    // Re-export commonly used Starknet types
110    pub use starknet::{
111        accounts::{Account, SingleOwnerAccount},
112        core::{
113            types::{Call, Felt, InvokeTransactionResult},
114            utils::get_selector_from_name,
115        },
116    };
117}
118
119/// Starknet integration plugin with default configuration
120///
121/// This plugin initializes all resources needed for Starknet integration:
122/// - Adds the `TokioPlugin` to create a Tokio runtime
123/// - Initializes the `StarknetConnection` resource
124/// - Initializes the `DefaultStarknetConfig` resource
125/// - Registers the `check_sn_task` system to monitor async tasks
126///
127/// # Example
128///
129/// ```no_run
130/// use bevy::prelude::*;
131/// use bevy_dojo::prelude::*;
132///
133/// fn main() {
134///     App::new()
135///         .add_plugins(DefaultPlugins)
136///         .add_plugins(BevyDojoPlugin)
137///         .run();
138/// }
139/// ```
140pub struct BevyDojoPlugin;
141
142impl Plugin for BevyDojoPlugin {
143    fn build(&self, app: &mut App) {
144        app.add_plugins(tokio::TokioPlugin)
145            .init_resource::<starknet::StarknetConnection>()
146            .init_resource::<starknet::DefaultStarknetConfig>()
147            .add_systems(Update, starknet::check_sn_task);
148    }
149}
bevy_dojo/lib.rs

bevy_dojo/
lib.rs
