Un bot pour Starcraft en rouille, C ou toute autre langue

StarCraft: Brood War . Ce jeu compte beaucoup pour moi! Et pour beaucoup d'entre vous, je suppose. Tellement, que je me demande si je devrais même donner un lien vers sa page sur Wikipedia ou non.

Une fois Halt m'a envoyé PM et m'a proposé d'apprendre Rust . Comme toute personne ordinaire, nous avons décidé de commencer par bonjour le monde écrire une bibliothèque dynamique pour Windows qui pourrait être chargée dans l'espace d'adressage de StarCraft et gérer les unités.

L'article suivant décrira le processus de recherche de solutions et l'utilisation de technologies et de techniques qui vous permettront d'apprendre de nouvelles choses sur Rust et son écosystème. Vous pouvez également être inspiré pour implémenter un bot en utilisant votre langage préféré, que ce soit C, C ++, Ruby, Python, etc.

Il vaut vraiment la peine d'écouter l'hymne de la Corée du Sud en lisant cet article:

Bwapi

Ce jeu a presque 20 ans. Et c'est toujours populaire ; Les championnats ont attiré des foules de gens aux États-Unis même en 2017, où la bataille des grands maîtres Jaedong contre Bisu a eu lieu. En plus des joueurs humains, les machines sans âme participent également aux batailles SC! Et cela est possible grâce à BWAPI . Liens plus utiles.

Depuis plus d'une décennie maintenant, il y a une communauté de développeurs de bots autour de ce jeu. Les amateurs créent des bots et participent à divers championnats. Beaucoup d'entre eux étudient l'IA et l'apprentissage automatique. Le BWAPI est utilisé par les universités pour former leurs étudiants. Il existe même une chaîne Twitch diffusant de tels matchs.

Ainsi, une équipe de fans a inversé le back-end de Starcraft il y a plusieurs années et a développé une API en C ++, qui vous permet de créer des bots, de faire des injections dans le processus de jeu et de dominer les humains misérables.

Comme cela arrive souvent, avant construire une maison, il faut extraire du minerai, forger des outils la création d'un bot, vous devez implémenter une API. Qu'est-ce que Rust a à offrir?

Ffi

Il est assez simple de travailler avec d'autres langues de Rust. Il y a un FFI pour cela. Permettez-moi de vous donner un court extrait de la documentation .

Imaginez que nous ayons une bibliothèque snappy , qui a un fichier d'en - tête snappy-ch , qui contient des déclarations de fonctions.

Créons un projet avec cargo .

$ cargo new --bin snappy Created binary (application) `snappy` project $ cd snappy snappy$ tree . ├── Cargo.toml └── src └── main.rs 1 directory, 2 files 

Cargo a créé une structure de fichiers standard pour le projet.

Dans Cargo.toml nous Cargo.toml dépendance à libc :

 [dependencies] libc = "0.2" 

Le fichier src/main.rs ressemblera à ceci:

 extern crate libc; // To import C types, in our case for size_t use libc::size_t; #[link(name = "snappy")] // Specify the name of the library for linking the function extern { // We write the declaration of the function which we want to import // in C the declaration looks like this: // size_t snappy_max_compressed_length(size_t source_length); fn snappy_max_compressed_length(source_length: size_t) -> size_t; } fn main() { let x = unsafe { snappy_max_compressed_length(100) }; println!("max compressed length of a 100 byte buffer: {}", x); } 

Construisons et exécutons le projet:

 snappy$ cargo build ... snappy$ cargo run Finished dev [unoptimized + debuginfo] target(s) in 0.02s Running `target/debug/snappy` max compressed length of a 100 byte buffer: 148 

Vous ne pouvez appeler que le cargo run , ce qui appelle la cargo build avant le vol. Une autre option est de construire le projet et d'appeler directement le binaire:

 snappy$ ./target/debug/snappy max compressed length of a 100 byte buffer: 148 

Si la bibliothèque snappy est installée, le code sera compilé (pour Ubuntu, vous devez installer le paquet libsnappy-dev).

 snappy$ ldd target/debug/snappy ... libsnappy.so.1 => /usr/lib/x86_64-linux-gnu/libsnappy.so.1 (0x00007f8de07cf000) 

Comme vous pouvez le voir, notre binaire est lié à la bibliothèque partagée libsnappy. Et un appel à snappy_max_compressed_length dans notre code est un appel de fonction de cette bibliothèque.

rouille-bindgen

Ce serait bien si nous pouvions générer automatiquement notre FFI. Heureusement, il existe un utilitaire appelé rust-bindgen dans la boîte à outils d'un addict de Rust. Il est capable de générer des liaisons FFI vers les bibliothèques C (et certaines C ++).

Installation:

 $ cargo install bindgen 

À quoi ressemble le rust-bindgen ? Nous prenons les fichiers d'en-tête C / C ++, nous pointons l' utilitaire bindgen vers eux, et la sortie que nous obtenons est un code Rust généré avec les déclarations appropriées pour nous permettre d'utiliser les structures et les fonctions C. Voici ce que bindgen génère pour bindgen :

 $ bindgen /usr/include/snappy-ch | grep -C 1 snappy_max_compressed_length extern "C" { pub fn snappy_max_compressed_length(source_length: usize) -> usize; } 

Il s'avère que bindgen ne peut pas faire face aux en-têtes BWAPI, générant des tonnes de code non utilisable (à cause des fonctions membres virtuelles, std :: string dans une API publique, etc.). Le fait est que BWAPI est écrit en C ++. C ++ est généralement difficile à utiliser même à partir de projets C ++. Une fois la bibliothèque assemblée, il est préférable de la lier avec le même éditeur de liens (même version), les fichiers d'en-tête doivent être analysés avec le même compilateur (même version). Tous ces facteurs peuvent affecter le résultat. Mangling par exemple, qui ne peut toujours pas être implémenté sans erreurs dans GNU GCC. Ces facteurs sont si importants que même gtest n'a pas pu le surmonter. Et dans la documentation, il est dit: vous feriez mieux de construire gtest dans le cadre du projet par le même compilateur et le même éditeur de liens.

Bwapi-c

C est la lingua franca du génie logiciel. Si rust-bindgen fonctionne bien pour le langage C, pourquoi ne pas implémenter BWAPI pour C, puis utiliser son API? Bonne idée!

Oui, c'est une bonne idée jusqu'à ce que vous examiniez l'intérieur de BWAPI et que vous voyiez le nombre de classes et de méthodes que vous devez implémenter. Surtout toutes ces dispositions de mémoire, codes asm, correctifs de mémoire et autres "horreurs" pour lesquelles nous n'avons pas le temps. Il est nécessaire d'utiliser complètement la solution existante.

Mais nous devons en quelque sorte battre les fonctions de mangling, de code C ++, d'héritage et de membre virtuel.

En C ++, il existe deux outils puissants que nous utiliserons pour résoudre notre problème: les pointeurs opaques et le extern "C" .

extern "C" {} permet au code C ++ de se "masquer" lui-même sous C. Il permet de générer des noms de fonction sans malmener.

Les pointeurs opaques nous permettent d'effacer le type et de créer un pointeur vers "un certain type" sans fournir son implémentation. Comme il ne s'agit que d'une déclaration d'un certain type, il est impossible d'utiliser ce type par valeur, vous ne pouvez l'utiliser que par pointeur.

Imaginons que nous ayons ce code C ++:

 namespace cpp { struct Foo { int bar; virtual int get_bar() { return this->bar; } }; } // namespace cpp 

Nous pouvons le transformer en un en-tête C:

 extern "C" { typedef struct Foo_ Foo; // Opaque pointer to Foo // call cpp::Foo::get_bar int Foo_get_bar(Foo* self); } 

Et voici la partie C ++ qui sera le lien entre l'en-tête C et l'implémentation C ++:

 int Foo_get_bar(Foo* self) { // cast the opaque pointer to the certain cpp::Foo and call the method ::get_bar return reinterpret_cast<cpp::Foo*>(self)->get_bar(); } 

Toutes les méthodes de cours n'ont pas dû être traitées de cette façon. Dans BWAPI, il existe des classes que vous pouvez implémenter vous-même en utilisant les champs de ces structures, par exemple typedef struct Position { int x; int y; } Position; typedef struct Position { int x; int y; } Position; et des méthodes comme Position::get_distance .

Il y avait des cours que je devais traiter d'une manière spéciale. Par exemple, AIModule doit être un pointeur vers une classe C ++ avec un ensemble spécifique de fonctions membres virtuelles. Néanmoins, voici l'en- tête et l' implémentation .

Ainsi, après plusieurs mois de dur labeur, 554 méthodes et une douzaine de classes, la bibliothèque multiplateforme BWAPI-C est née, qui vous permet de créer des bots en C. Un sous-produit était la possibilité de compilation croisée et la possibilité d'implémenter l'API dans n'importe quel autre langage prenant en charge FFI et la convention d'appel cdecl.

Si vous écrivez une bibliothèque, veuillez écrire son API en C.

La caractéristique la plus importante de BWAPI-C est l'intégration la plus large possible avec d'autres langages de programmation. Python , Ruby , Rust , PHP , Java et bien d'autres sont capables de travailler avec C, donc si vous corrigez les problèmes et implémentez vos propres wrappers, vous pouvez également écrire un bot avec leur aide.

Écrire un bot en C

Cette partie décrit les principes généraux de l'organisation interne des modules Starcraft.

Il existe 2 types de bots: module et client. Regardons un exemple d'écriture d'un module.

Le module est une bibliothèque dynamique. Le principe général du chargement des bibliothèques dynamiques peut être consulté ici . Le module devrait exporter 2 fonctions: newAIModule et gameInit .

gameInit est facile. Cette fonction est appelée pour passer un pointeur sur une partie en cours. Ce pointeur est très important, car il existe une variable statique globale dans les caractères génériques de BWAPI, qui est utilisée dans certaines sections du code. gameInit :

 DLLEXPORT void gameInit(void* game) { BWAPIC_setGame(game); } 

newAIModule est un peu plus compliqué. Il devrait renvoyer le pointeur vers une classe C ++, qui a une table de méthode virtuelle avec des noms comme onXXXXX qui sont appelés sur certains événements de jeu. Déclarons la structure du module:

 typedef struct ExampleAIModule { const AIModule_vtable* vtable_; const char* name; } ExampleAIModule; 

Le premier champ doit être un pointeur vers la table des méthodes (c'est une sorte de magie). Voici la newAIModule fonction newAIModule :

 DLLEXPORT void* newAIModule() { ExampleAIModule* const module = (ExampleAIModule*) malloc( sizeof(ExampleAIModule) ); module->name = "ExampleAIModule"; module->vtable_ = &module_vtable; return createAIModuleWrapper( (AIModule*) module ); } 

createAIModuleWrapper est une autre astuce magique qui transforme le pointeur C en pointeur vers la classe C ++ avec méthodes virtuelles fonctions des membres.

module_vtable est une variable statique sur la table des méthodes, les valeurs des méthodes sont remplies de pointeurs vers les fonctions globales:

 static AIModule_vtable module_vtable = { onStart, onEnd, onFrame, onSendText, onReceiveText, onPlayerLeft, onNukeDetect, onUnitDiscover, onUnitEvade, onUnitShow, onUnitHide, onUnitCreate, onUnitDestroy, onUnitMorph, onUnitRenegade, onSaveGame, onUnitComplete }; void onEnd(AIModule* module, bool isWinner) { } void onFrame(AIModule* module) {} void onSendText(AIModule* module, const char* text) {} void onReceiveText(AIModule* module, Player* player, const char* text) {} void onPlayerLeft(AIModule* module, Player* player) {} void onNukeDetect(AIModule* module, Position target) {} void onUnitDiscover(AIModule* module, Unit* unit) {} void onUnitEvade(AIModule* module, Unit* unit) {} void onUnitShow(AIModule* module, Unit* unit) {} void onUnitHide(AIModule* module, Unit* unit) {} void onUnitCreate(AIModule* module, Unit* unit) {} void onUnitDestroy(AIModule* module, Unit* unit) {} void onUnitMorph(AIModule* module, Unit* unit) {} void onUnitRenegade(AIModule* module, Unit* unit) {} void onSaveGame(AIModule* module, const char* gameName) {} void onUnitComplete(AIModule* module, Unit* unit) {} 

Si vous regardez le nom des fonctions et leurs signatures, il est clair dans quelles conditions et avec quels arguments elles doivent être appelées. Pour un exemple, j'ai rendu toutes les fonctions vides, sauf

 void onStart(AIModule* module) { ExampleAIModule* self = (ExampleAIModule*) module; Game* game = BWAPIC_getGame(); Game_sendText(game, "Hello from bwapi-c!"); Game_sendText(game, "My name is %s", self->name); } 

Cette fonction est appelée lorsque le jeu s'exécute. L'argument est un pointeur vers le module actuel. BWAPIC_getGame renvoie un pointeur global sur le jeu, que nous définissons à l'aide d'un appel à BWAPIC_setGame . Alors, montrons un exemple de travail de compilation croisée d'un module:

 bwapi-c/example$ tree . ├── BWAPIC.dll └── Dll.c 0 directories, 2 files bwapi-c/example$ i686-w64-mingw32-gcc -mabi=ms -shared -o Dll.dll Dll.c -I../include -L. -lBWAPIC bwapi-c/example$ cp Dll.dll ~/Starcraft/bwapi-data/ bwapi-c/example$ cd ~/Starcraft/bwapi-data/ Starcraft$ wine bwheadless.exe -e StarCraft.exe -l bwapi-data/BWAPI.dll --headful ... ... ... 

Appuyez sur les boutons et lancez le jeu. Plus d'informations sur la compilation et l'exécution peuvent être trouvées sur le site Web de BWAPI et dans BWAPI-C .

Le résultat du module:

Vous pouvez trouver un exemple un peu plus compliqué d'un module qui montre comment travailler avec les itérateurs, la gestion des unités, la recherche de minéraux et la sortie des statistiques dans bwapi-c / example / Dll.c.

bwapi-sys

Dans l'écosystème Rust, il existe une certaine façon de nommer les packages liés aux bibliothèques natives. Tout paquet foo-sys exécute deux fonctions importantes:

• liens avec la bibliothèque native libfoo;
• fournit des déclarations aux fonctions de la bibliothèque libfoo. Mais des déclarations seulement! Les abstractions de haut niveau ne sont pas fournies dans les caisses * -sys.

Pour que le package * -sys puisse se lier avec succès, vous devez dire à cargo de rechercher la bibliothèque native et / ou de construire la bibliothèque à partir des sources.

Pour que le package * -sys fournisse des déclarations, vous devez soit les écrire vous-même, soit les générer à l'aide de bindgen. Encore une fois bindgen. Tentative numéro deux =)

La génération de fixations est super simple:

 bindgen BWAPI.h -o lib.rs \ --opaque-type ".+_" \ --blacklist-type "std.*|__.+|.+_$|Game_v(Send|Print|Draw).*|va_list|.+_t$" \ --no-layout-tests \ --no-derive-debug \ --raw-line "#![allow(improper_ctypes, non_snake_case)]" \ -- -I../submodules/bwapi-c/include sed -i -r -- 's/.+\s+(.+)_;/pub struct \1;/' lib.rs 

BWAPI.h est un fichier contenant tous les en-têtes C de BWAPI-C.

Par exemple, bindgen a déjà généré de telles déclarations pour les fonctions ci-dessus:

 extern "C" { /// BWAPIC_setGame must be called from gameInit to initialize BWAPI::BroodwarPtr pub fn BWAPIC_setGame(game: *mut Game); } extern "C" { pub fn BWAPIC_getGame() -> *mut Game; } 

Il existe deux stratégies: stocker le code généré dans le référentiel et générer le code à la volée lors de la génération. Les deux approches ont leurs avantages et leurs inconvénients .

Heureux de vous rencontrer bwapi-sys ; un petit pas de plus vers notre objectif.

Vous souvenez-vous que plus tôt je parlais de multiplateforme? nlinker a rejoint le projet et mis en œuvre une stratégie astucieuse. Si l'hôte cible est Windows, téléchargez le BWAPIC déjà assemblé depuis GitHub. Et pour les cibles restantes, nous collectons BWAPI-C à partir des sources d'OpenBW (je vous en parlerai un peu plus tard).

bwapi-rs

Nous avons maintenant les liaisons et nous pouvons définir des abstractions de haut niveau. Nous avons deux types avec lesquels travailler: des valeurs pures et des pointeurs opaques.

Tout est simple avec des valeurs pures. Prenons l'exemple des couleurs. Nous devons le rendre facile à utiliser à partir du code Rust afin d'utiliser les couleurs de manière pratique et naturelle:

 game.draw_line(CoordinateType::Screen, (10, 20), (30, 40), Color::Red); ^^^ 

Ainsi, pour une utilisation pratique, il serait nécessaire de définir l'énumération avec des constantes C ++ mais également idiomatique pour Rust, et de définir des méthodes de conversion dans bwapi_sys :: Color en utilisant std :: convert :: From:

 // FFI version #[repr(C)] #[derive(Copy, Clone)] pub struct Color { pub color: ::std::os::raw::c_int, } // Idiomatic version #[derive(PartialEq, PartialOrd, Copy, Clone)] pub enum Color { Black = 0, Brown = 19, ... 

Pour votre commodité, vous pouvez utiliser la caisse enum-primitive-derive .

Il est également facile d'utiliser des pointeurs opaques. Utilisons le modèle Newtype :

 pub struct Player(*mut sys::Player); 

Cela signifie que Player est une sorte de structure avec un champ privé - un pointeur opaque brut de C. Et voici la façon dont vous pouvez définir la couleur Player :::

 impl Player { // so the method is declared Player::getColor in bwapi-sys //extern "C" { // pub fn Player_getColor(self_: *mut Player) -> Color; //} pub fn color(&self) -> Color { // bwapi_sys::Player_getColor - wrapper function from BWAPI-C // self.0 - opaque pointer let color = unsafe { bwapi_sys::Player_getColor(self.0) }; color.into() // cast bwapi_sys::Color -> Color } } 

Nous pouvons maintenant écrire notre premier bot en rouille!

Créer un bot dans Rust

Comme preuve de concept, le bot sera similaire à un pays bien connu: toute la tâche consiste à embaucher des travailleurs et à collecter des minéraux.

Commençons par les fonctions requises gameInit et newAIModule :

 #[no_mangle] pub unsafe extern "C" fn gameInit(game: *mut void) { bwapi_sys::BWAPIC_setGame(game as *mut bwapi_sys::Game); } #[no_mangle] pub unsafe extern "C" fn newAIModule() -> *mut void { let module = ExampleAIModule { name: String::from("ExampleAIModule") }; let result = wrap_handler(Box::new(module)); result } 

#[no_mangle] remplit la même fonction que l' extern "C" en C ++. A l'intérieur de wrap_handler toute la magie se produit, avec la substitution de la table de fonction virtuelle et de la classe C ++ "masquante".

Les définitions de la structure du module sont encore plus simples et plus sophistiquées qu'en C:

 struct ExampleAIModule { name: String, } 

Ajoutons quelques méthodes pour rendre les statistiques et donner des ordres:

 impl ExampleAIModule { fn draw_stat(&mut self) { let game = Game::get(); let message = format!("Frame {}", game.frame_count()); game.draw_text(CoordinateType::Screen, (10, 10), &message); } fn give_orders(&mut self) { let player = Game::get().self_player(); for unit in player.units() { match unit.get_type() { UnitType::Terran_SCV | UnitType::Zerg_Drone | UnitType::Protoss_Probe => { if !unit.is_idle() { continue; } if unit.is_carrying_gas() || unit.is_carrying_minerals() { unit.return_cargo(false); continue; } if let Some(mineral) = Game::get() .minerals() .min_by_key(|m| unit.distance_to(m)) { // WE REQUIRE MORE MINERALS unit.right_click(&mineral, false); } } UnitType::Terran_Command_Center => { unit.train(UnitType::Terran_SCV); } UnitType::Protoss_Nexus => { unit.train(UnitType::Protoss_Probe); } UnitType::Zerg_Hatchery | UnitType::Zerg_Lair | UnitType::Zerg_Hive => { unit.train(UnitType::Zerg_Drone); } _ => {} }; } } } 

Pour transformer le type ExampleAIModule en un véritable module, vous devez le faire répondre aux événements onXXXX . Pour ce faire, vous devez implémenter le type EventHandler, qui est un analogue de la table virtuelle AIModule_vtable de C:

 impl EventHandler for ExampleAIModule { fn on_start(&mut self) { Game::get().send_text(&format!("Hello from Rust! My name is {}", self.name)); } fn on_end(&mut self, _is_winner: bool) {} fn on_frame(&mut self) { self.draw_stat(); self.give_orders(); } fn on_send_text(&mut self, _text: &str) {} fn on_receive_text(&mut self, _player: &mut Player, _text: &str) {} fn on_player_left(&mut self, _player: &mut Player) {} fn on_nuke_detect(&mut self, _target: Position) {} fn on_unit_discover(&mut self, _unit: &mut Unit) {} fn on_unit_evade(&mut self, _unit: &mut Unit) {} fn on_unit_show(&mut self, _unit: &mut Unit) {} fn on_unit_hide(&mut self, _unit: &mut Unit) {} fn on_unit_create(&mut self, _unit: &mut Unit) {} fn on_unit_destroy(&mut self, _unit: &mut Unit) {} fn on_unit_morph(&mut self, _unit: &mut Unit) {} fn on_unit_renegade(&mut self, _unit: &mut Unit) {} fn on_save_game(&mut self, _game_name: &str) {} fn on_unit_complete(&mut self, _unit: &mut Unit) {} } 

La construction et l'exécution du module sont aussi simples que pour C:

 bwapi-rs$ cargo build --example dll --target=i686-pc-windows-gnu bwapi-rs$ cp ./target/i686-pc-windows-gnu/debug/examples/dll.dll ~/Starcraft/bwapi-data/Dll.dll bwapi-rs$ cd ~/Starcraft/bwapi-data/ Starcraft$ wine bwheadless.exe -e StarCraft.exe -l bwapi-data/BWAPI.dll --headful ... ... ... 

Et la vidéo de l'oeuvre:

Openbw

Ces gars sont allés encore plus loin. Ils ont décidé d'écrire une version open source de SC: BW! Et ils sont bons dans ce domaine. L'un de leurs objectifs était d'implémenter des images HD, mais SC: Remastered était en avance sur eux = (En ce moment, vous pouvez utiliser leur API pour écrire des bots (oui, également en C ++), mais la fonctionnalité la plus étonnante est la possibilité de visualiser rejoue directement dans votre navigateur .

Conclusion

Il y avait un problème non résolu avec l'implémentation: nous ne contrôlons pas que les références soient uniques, donc l'existence de &mut et & vers la même région entraînera un comportement indéfini lorsque l'objet est modifié. Une sorte de problème. Halt a essayé d'implémenter des liaisons idiomatiques, mais il n'a pas réussi à trouver une solution. De plus, si vous souhaitez terminer cette tâche, vous devez soigneusement "pelleter" l'API C ++ et mettre correctement les qualificatifs const .

J'ai vraiment aimé travailler sur ce projet, j'ai regardé les rediffusions 하루 종일 et profondément immergé dans l'atmosphère. Ce jeu a fait une 놀라운 dent dans un univers. Aucun jeu ne peut être 비교할 수 없다 par popularité avec SC: BW, et son impact sur 대한민국 정치 에게 était impensable. Les pro-gamers en Corée 아마도 sont aussi populaires que les 드라마 주연 배우 들 dorams coréens diffusant aux heures de grande écoute. 또한, 한국 에서 프로 게이머 라면 군대 의 특별한 육군 에 입대 할 수 수.

Vive StarCraft!

Les liens

• reddit
• bwapi-rs
• bwapi-sys
• bwapi-c
• bwapi
• openbw

Un grand merci à Steve Klabnik pour m'avoir aidé à lire l'article.