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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
//! [![Build Status](https://travis-ci.org/awestlake87/sc2-rs.svg?branch=master)](https://travis-ci.org/awestlake87/sc2-rs)
//! [![Crates Version](https://img.shields.io/crates/v/sc2.svg)](https://crates.io/crates/sc2)
//! [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
//! [![Documentation](https://docs.rs/sc2/badge.svg)](https://docs.rs/crate/sc2)
//!
//! [Documentation (master)](https://awestlake87.github.io/sc2-rs/sc2/)
//!
//! This is my Rust implementation of the [StarCraft II Client API](https://github.com/Blizzard/s2client-api).
//!
//! This crate is still under heavy development, and I've only just decided the
//! direction it's going in regarding futures and streams. It currently relies on
//! the nightly `#[async]/await!`, but if enough people push to support stable
//! futures, I'll consider moving this requirement into a feature, but at the
//! moment, it's *really* convenient to use the experimental features instead of the
//! stable combinators.
//!
//! I tried to keep it close to the s2client-api in terms of the division of
//! functionality into interfaces such as the Action interface and Observer
//! interface, however there are several differences because for one idiomatic C++
//! and idiomatic Rust don't play well together (and for good reason too!), and also
//! I was very interested in the work done with futures-rs and thought that neat
//! asynchronous programming was a good fit for this library. In particular, one of
//! the core differences between s2client-api and this library is the creation of
//! bots and the consumption of events.
//!
//! s2client-api employs polymorphism to define bots, sc2-rs on the other hand uses
//! channels to communicate between the bot and the API. Let's take a look at the
//! creation of a simple bare-bones bot.
//!
//! This bot is simply designed to take a stream of game events and print messages
//! for GameStarted and GameStepped. Normally, you would use these events as
//! opportunities to observe the game state and/or dispatch orders to units. For
//! now, though, a message is good enough.
//!
//! ```no_run
//! #![feature(proc_macro, generators)]
//!
//! extern crate futures_await as futures;
//! extern crate tokio_core;
//! extern crate sc2;
//!
//! use futures::prelude::*;
//! use futures::unsync::mpsc;
//! use sc2::{
//!     agent::{AgentBuilder},
//!     ai::{OpponentBuilder},
//!     data::{GameSetup, Map, Race},
//!     observer::{Event, EventAck},
//!
//!     LauncherSettings,
//!     MeleeBuilder,
//!
//!     Result,
//!     Error,
//! };
//! use tokio_core::reactor;
//!
//! struct SimpleBot;
//!
//! impl SimpleBot {
//!     fn new() -> Self {
//!         Self { }
//!     }
//!
//!     /// Spawn our bot's coroutine on the event loop.
//!     fn spawn(
//!         self,
//!         handle: &reactor::Handle,
//!         rx: mpsc::Receiver<(Event, EventAck)>,
//!     ) -> Result<()> {
//!         handle.spawn(self.run(rx).map_err(|e| panic!("{:#?}", e)));
//!
//!         Ok(())
//!     }
//!
//!     /// Run the bot.
//!     #[async]
//!     fn run(mut self, rx: mpsc::Receiver<(Event, EventAck)>) -> Result<()> {
//!         // Loop over the game events.
//!         #[async]
//!         for (e, ack) in rx.map_err(|_| -> Error { unreachable!() }) {
//!             match e {
//!                 // Triggered once at the start of every game.
//!                 Event::GameStarted => println!("Started a new game!"),
//!                 // Triggered every time the game updates.
//!                 Event::Step => println!("Game Stepped!"),
//!             
//!                 // Ignore the other events for now.
//!                 _ => (),
//!             }
//!
//!             // Notify the coordinator that we have consumed this event.
//!             await!(ack.done())?;
//!         }
//!
//!         Ok(())
//!     }
//! }
//!
//! fn main() {
//!     // Create a new event loop.
//!     let mut core = reactor::Core::new().unwrap();
//!     let handle = core.handle();

//!     // Create a new Agent and set the Race to Terran.
//!     let mut agent = AgentBuilder::new().race(Race::Terran);
//!
//!     // Instantiate our simple bot.
//!     let bot = SimpleBot::new();
//!
//!     // Get the event stream from the Agent and spawn our bot's coroutine.
//!     bot.spawn(&handle, agent.take_event_stream().unwrap()).unwrap();
//!
//!     // Create a match between our bot and a default SC2 built-in AI Opponent.
//!     let melee = MeleeBuilder::new()
//!         .add_player(agent)
//!         .add_player(OpponentBuilder::new())
//!         .launcher_settings(LauncherSettings::new())
//!         .one_and_done(GameSetup::new(Map::LocalMap(
//!             "maps/Ladder/(2)Bel'ShirVestigeLE (Void).SC2Map".into()
//!         )))
//!         .step_interval(1)
//!         .handle(&handle)
//!         .create()
//!         .unwrap();
//!
//!     // Run the match to completion on the event loop.
//!     core.run(melee.into_future()).unwrap();
//! }
//! ```
//!
//! Here we create an event loop, spawn our bot as a coroutine and listen for events
//! from a Melee (PvP) match against a built-in SC2 AI opponent.
//!
//! An important thing to note is that the default LauncherSettings will only find
//! your SC2 on Windows. However, since the headless Linux version is not ideal for
//! debugging purposes, I've added support for Wine within the library for all of
//! the people like me who are too lazy to dual-boot (or just prefer Linux in
//! general). The good news is that Wine actually supports SC2, the bad news is that
//! last time I checked, the support requires newer (possibly staging versions) of
//! Wine.
//!
//! Here are some helpful links to get you started with that:
//! - [SC2 Page on Wine HQ](https://appdb.winehq.org/objectManager.php?sClass=version&iId=20882)
//! - [Ask Ubuntu thread on installing Wine Staging and SC2 for Ubuntu 16.04](https://askubuntu.com/questions/846651/installing-starcraft-2-playonlinux)

#![warn(missing_docs)]
#![recursion_limit = "1024"]
#![feature(proc_macro, generators)]

#[macro_use]
extern crate error_chain;

extern crate bytes;
extern crate colored;
extern crate ctrlc;
extern crate futures_await as futures;
extern crate glob;
extern crate nalgebra as na;
extern crate protobuf;
extern crate rand;
extern crate regex;
extern crate sc2_proto;
extern crate tokio_core;
extern crate tokio_timer;
extern crate tokio_tungstenite;
extern crate tungstenite;
extern crate url;

mod constants;
mod instance;
mod launcher;
mod services;

pub mod action;
pub mod agent;
pub mod ai;
pub mod data;
pub mod debug;
pub mod observer;

pub use self::launcher::LauncherSettings;
pub use self::services::melee_service::MeleeBuilder;

use std::path::PathBuf;

error_chain! {
    foreign_links {
        Io(std::io::Error) #[doc="Link io errors."];

        Ctrlc(ctrlc::Error) #[doc="Link to Ctrl-C errors."];
        FutureCanceled(futures::Canceled) #[doc="Link to futures."];
        UrlParse(url::ParseError) #[doc="Link to url parse errors."];
        Protobuf(protobuf::ProtobufError) #[doc="Link to protobuf errors."];
        Timer(tokio_timer::TimerError) #[doc="Link to timer errors."];
        Tungstenite(tungstenite::Error) #[doc="Link to tungstenite errors."];
    }
    errors {
        /// Executable was not supplied to the coordinator.
        ExeNotSpecified {
            description("Executable was not supplied to the coordinator")
            display("StarCraft II exe was not specified")
        }
        /// Executable supplied to the coordinator does not exist.
        ExeDoesNotExist(exe: PathBuf) {
            description("Executable supplied to the coordinator does not exist")
            display("StarCraft II exe does not exist at {:?}", exe)
        }

        /// Auto-detecting the SC2 installation was unsuccessful.
        AutoDetectFailed(msg: String) {
            description("Auto-detecting the SC2 installation was unsuccessful")
            display("SC2 Auto-detect failed {}", msg)
        }

        /// An invalid map path was supplied to the library.
        InvalidMapPath(msg: String) {
            description("An invalid map path was supplied to the library")
            display("Invalid map path - {}", msg)
        }

        /// A required field was not provided to a builder.
        ///
        /// Often, a builder will have no suitable default for a value. These
        /// fields require the user to supply a value. When the builder is
        /// finalized, it will check these values and if it is missing a
        /// requirement, you should expect this error.
        MissingRequirement(msg: String) {
            description("A required field was not provided to a builder")
            display("Missing requirement - {}", msg)
        }

        /// Match settings are invalid.
        InvalidMatch(msg: String) {
            description("Match settings are invalid"),
            display("Invalid Match - {}", msg)
        }

        /// Client failed to open connection to the game instance.
        ClientOpenFailed(msg: String) {
            description("Client failed to open connection to the game instance")
            display("Client open failed - {}", msg)
        }
        /// Client failed to send a message to the game instance.
        ClientSendFailed(msg: String) {
            description("Client failed to send a message to the game instance")
            display("Client send failed - {}", msg)
        }
        /// Client failed to receive a message from the game instance.
        ClientRecvFailed(msg: String) {
            description("Client failed to receive a message from the game instance")
            display("Client recv failed - {}", msg)
        }
        /// Client failed to initiate close handshake.
        ClientCloseFailed(msg: String) {
            description("Client failed to complete close handshake")
            display("Client close failed - {}", msg)
        }

        /// Errors received from game instance.
        GameErrors(errors: Vec<String>) {
            description("Errors received from game instance")
            display("Received errors: {:?}", errors)
        }

        /// EventAck receiver was dropped or closed.
        ///
        /// This should not happen in sc2-rs, but any external libraries with
        /// more flexible event subscribers may encounter this problem, and this
        /// error will allow them the freedom to deal with it in their own way.
        EventAckCanceled(msg: String) {
            description("EventAck receiver was dropped or closed")
            display("Event ACK canceled {}", msg)
        }

        /// Invalid protobuf data from game instance.
        InvalidProtobuf(msg: String) {
            description("Invalid protobuf data from game instance")
            display("Unable to convert protobuf data: {}", msg)
        }
    }
}

trait FromProto<T>
where
    Self: Sized,
{
    /// Convert from protobuf data.
    fn from_proto(p: T) -> Result<Self>;
}

trait IntoSc2<T> {
    fn into_sc2(self) -> Result<T>;
}

impl<T, U> IntoSc2<U> for T
where
    U: FromProto<T>,
{
    fn into_sc2(self) -> Result<U> {
        U::from_proto(self)
    }
}

trait IntoProto<T> {
    /// Convert into protobuf data
    fn into_proto(self) -> Result<T>;
}