asr/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
#![no_std]
#![warn(
    clippy::complexity,
    clippy::correctness,
    clippy::perf,
    clippy::style,
    clippy::missing_const_for_fn,
    clippy::undocumented_unsafe_blocks,
    missing_docs,
    rust_2018_idioms
)]
#![cfg_attr(doc_cfg, feature(doc_auto_cfg))]

//! Helper crate to write auto splitters for LiveSplit One's auto splitting
//! runtime.
//!
//! There are two ways of defining an auto splitter.
//!
//! # Defining an `update` function
//!
//! You can define an `update` function that will be called every frame. This is
//! the simplest way to define an auto splitter. The function must have the
//! following signature:
//! ```no_run
//! #[no_mangle]
//! pub extern "C" fn update() {}
//! ```
//!
//! The advantage of this approach is that you have full control over what
//! happens on every tick of the runtime. However, it's much harder to keep
//! state around as you need to store all state in global variables as you need
//! to return out of the function on every tick.
//!
//! ## Example
//!
//! ```no_run
//! # use asr::Process;
//! #[no_mangle]
//! pub extern "C" fn update() {
//!     if let Some(process) = Process::attach("explorer.exe") {
//!         asr::print_message("Hello World!");
//!         if let Ok(address) = process.get_module_address("explorer.exe") {
//!             if let Ok(value) = process.read::<u32>(address) {
//!                 if value > 0 {
//!                     asr::timer::start();
//!                 }
//!             }
//!         }
//!     }
//! }
//! ```
//!
//! # Defining an asynchronous `main` function
//!
//! You can use the [`async_main`] macro to define an asynchronous `main`
//! function.
//!
//! Similar to using an `update` function, it is important to constantly yield
//! back to the runtime to communicate that the auto splitter is still alive.
//! All asynchronous code that you await automatically yields back to the
//! runtime. However, if you want to write synchronous code, such as the main
//! loop handling of a process on every tick, you can use the
//! [`next_tick`](future::next_tick) function to yield back to the runtime and
//! continue on the next tick.
//!
//! The main low level abstraction is the [`retry`](future::retry) function,
//! which wraps any code that you want to retry until it succeeds, yielding back
//! to the runtime between each try.
//!
//! So if you wanted to attach to a Process you could for example write:
//!
//! ```no_run
//! # use asr::{Process, future::retry};
//! # async fn example() {
//! let process = retry(|| Process::attach("MyGame.exe")).await;
//! # }
//! ```
//!
//! This will try to attach to the process every tick until it succeeds. This
//! specific example is exactly how the [`Process::wait_attach`] method is
//! implemented. So if you wanted to attach to any of multiple processes, you
//! could for example write:
//!
//! ```no_run
//! # use asr::{Process, future::retry};
//! # async fn example() {
//! let process = retry(|| {
//!    ["a.exe", "b.exe"].into_iter().find_map(Process::attach)
//! }).await;
//! # }
//! ```
//!
//! ## Example
//!
//! Here is a full example of how an auto splitter could look like using the
//! [`async_main`] macro:
//!
//! Usage on stable Rust:
//! ```ignore
//! async_main!(stable);
//! ```
//!
//! Usage on nightly Rust:
//! ```ignore
//! #![feature(type_alias_impl_trait, const_async_blocks)]
//!
//! async_main!(nightly);
//! ```
//!
//! The asynchronous main function itself:
//! ```ignore
//! async fn main() {
//!     // TODO: Set up some general state and settings.
//!     loop {
//!         let process = Process::wait_attach("explorer.exe").await;
//!         process.until_closes(async {
//!             // TODO: Load some initial information from the process.
//!             loop {
//!                 // TODO: Do something on every tick.
//!                next_tick().await;
//!             }
//!         }).await;
//!     }
//! }
//! ```

#[cfg(feature = "alloc")]
extern crate alloc;

mod primitives;
mod runtime;

pub mod deep_pointer;
pub mod emulator;
#[macro_use]
pub mod future;
pub mod file_format;
pub mod game_engine;
#[cfg(feature = "signature")]
pub mod signature;
pub mod string;
pub mod sync;
pub mod time_util;
#[cfg(all(feature = "wasi-no-std", target_os = "wasi"))]
mod wasi_no_std;
pub mod watcher;

pub use self::{primitives::*, runtime::*};
pub use arrayvec;
pub use time;

#[cfg(feature = "itoa")]
pub use itoa;

#[cfg(feature = "ryu")]
pub use ryu;

#[macro_use]
mod panic;