UG_RRobots 1.2

data/config/rrobots.yml

@@ -0,0 +1,15 @@
+--- !ruby/object:Configuration 
+battlefield: 
+  :height: 800
+  :width: 800
+bullets: 
+  :speed: 30
+game: 
+  :timeout: 50000
+robots: 
+  :energy_max: 100
+toolboxes: 
+  :energy_heal_points: 20
+  :with_toolboxes: false
+  :life_time: 200
+  :spawning_chances: 100

data/doc/manual.rdoc

@@ -0,0 +1,126 @@
+= RRobots v0.2.2
+
+== Presentation
+
+First there was CRobots, followed by PRobots and many others, recently
+(well also years ago) Robocode emerged and finally this is RRobots bringing
+all the fun to the ruby community.
+
+== What is he talking about?
+
+RRobots is a simulation environment for robots, these robots have a scanner
+and a gun, can move forward and backwards and are entirely controlled by
+ruby scripts. All robots are equal (well at the moment, maybe this will 
+change) except for the ai.
+
+== A simple robot script
+
+<code>
+require 'robot'
+class NervousDuck
+  include Robot
+  def tick events
+    turn_radar 1 if time == 0
+    turn_gun 30 if time < 3
+    accelerate 1
+    turn 2
+    fire 3 unless events['robot_scanned'].empty? 
+  end
+end
+</code>
+
+
+all you need to implement is the tick method which should accept a hash
+of events occured turing the last tick.
+
+
+== API RRobots Fork
+
+By including Robot you get all this methods to controll your bot:
+
+- *battlefield_height*    the height of the battlefield
+- *battlefield_width*     the width of the battlefield
+- *energy*                your remaining energy (if this drops below 0 you are dead)
+- *gun_heading*           the heading of your gun, 0 pointing east, 90 pointing, north, 180 pointing west, 270 pointing south
+- *gun_heat*              your gun heat, if this is above 0 you can't shoot
+- *heading*               your robots heading, 0 pointing east, 90 pointing north, 180 pointing west, 270 pointing south
+- *size*                  your robots radius, if x <= size you hit the left wall
+- *radar_heading*         the heading of your radar, 0 pointing east, 90 pointing north, 180 pointing west, 270 pointing south
+- *time*                  ticks since match start
+- *speed*                 your speed (-8/8)
+- *x*                     your x coordinate, 0...battlefield_width
+- *y*                     your y coordinate, 0...battlefield_height
+- *accelerate*(_param_)   accelerate (max speed is 8, max accelerate is 1/-1, negativ speed means moving backwards)
+- *stop*                  accelerates negativ if moving forward (and vice versa), may take 8 ticks to stop (and you have to call it every tick)
+- *fire*(_power_)         fires a bullet in the direction of your gun, power is 0.1 - 3, this power will heat your gun
+- *turn*(_degrees_)       turns the robot (and the gun and the radar), max 10 degrees per tick
+- *turn_gun*(_degrees_)   turns the gun (and the radar), max 30 degrees per tick
+- *turn_radar*(_degrees_) turns the radar, max 60 degrees per tick
+- *dead*                  true if you are dead
+- *say*(_msg_)             shows msg above the robot on screen
+- *broadcast*(_msg_)       broadcasts msg to all bots (they recieve 'broadcasts' events with the msg and rough direction)
+
+These methods are intentionally of very basic nature, you are free to
+unleash the whole power of ruby to create higher level functions.
+(e.g. move_to, fire_at and so on)
+
+Some words of explanation: The gun is mounted on the body, if you turn
+the body the gun will follow. In a simmilar way the radar is mounted on
+the gun. The radar scans everything it sweeps over in a single tick (100 
+degrees if you turn your body, gun and radar in the same direction) but
+will report only the distance of scanned robots, not the angle. If you 
+want more precission you have to turn your radar slower.
+UG RRobots Fork introduce toolboxes, toolboxes could spawn during a match and if a robot run over it, the toolbox heal it of a default value of 20 energy point.
+Toolboxes could be scan separatly of the robots (events keys scanned_toolboxes)
+The toolbox mode is optionnal 
+
+RRobots is implemented in pure ruby using a tk ui and should run on all
+platforms that have ruby and tk. (until now it's tested on windows, OS X
+and several linux distributions)
+
+=== To start a match call:
+
+<pre>
+ruby rrobots.rb [resolution] [#match] [-nogui] [-speed=<N>] [-with-toolboxes] [-timeout=<N>] <FirstRobotClassName[.rb]> <SecondRobotClassName[.rb]> <...>
+	  
+  [resolution] (optional) should be of the form 640x480 or 800*600. 
+    default is 800x800
+  [match] (optional) to replay a match, put the match# here, including 
+    the #sign.
+  [-nogui] (optional) run the match without the gui, for highest possible 
+    speed.(ignores speed value if present)
+  [-speed=<N>] (optional, defaults to 1) updates GUI after every N ticks.  
+    The higher the N, the faster the match will play.
+  [-timeout=<N>] (optional, default 50000) number of ticks a match will 
+    last at most.
+  [-ignore-config] (optional) to ignore the config file YAML present in the path.
+  [-write-config] (optional) to write the config in YAML in a file in the path.
+  [-with-toolboxes] (optional) to accept the spawning of healing toolboxes (randomly).
+</pre>
+  
+the names of the rb files have to match the class names of the robots (up to 8 robots)
+
+e.g. 
+  'ruby rrobots.rb SittingDuck NervousDuck'
+or 
+  'ruby rrobots.rb 600x600 #1234567890 SittingDuck NervousDuck'
+
+=== If you want to run a tournament call:
+
+<pre>
+ruby tournament.rb [-timeout=<N>] [-matches=<N>] [-with-toolboxes] (-dir=<Directory> | <RobotClassName[.rb]>+)
+
+  [-timeout=<N>] (optional, default 10000) number of ticks a match 
+    will last at most.
+  [-matches=<N>] (optional, default 2) how many times each robot 
+    fights every other robot.
+  -dir=<Directory> All .rb files from that directory will be 
+    matched against each other.
+  [-ignore-config] (optional) to ignore the config file YAML present in the path.
+  [-with-toolboxes] (optional) to accept the spawning of healing toolboxes (randomly). 
+</pre>
+
+
+the names of the rb files have to match the class names of the robots.
+Each robot is matched against each other 1on1. The results are available 
+as yaml or html files.

data/doc/manual_fr.rdoc

@@ -0,0 +1,129 @@
+= UG RRobots Fork
+
+== Version 
+
+- UG RRobots  Fork v1.0
+- fork of RRobots v0.2.2
+
+Au début il y avait CRobots (Version C), suivit par PRobots (Pascal) et beaucoup d'autres, récemment (quelques années quand même) Robocode à fait son apparition (version Java) et maintenant il y a RRobots qui apporte le fun à la communauté Ruby
+Cette Variante du programme initilale de Simon Kröger, http://rubyforge.org/projects/rrobots, apporte de nouvelles fonctionnalitées
+ 
+== De quoi parle-t-on ? 
+
+UG RRobots est une simulation de champs de bataille pour Robots Virtuels
+Chaque Robots possède un Radar et un Canon
+Les robots peuvent bouger vers l'avant et l'arrière et son entièrement contrôlés par des scripts en Ruby
+Tous les robots ont les même caractéristiques, et tant que le joueur n'a pas codé son Intelligence le robot est un objet inerte.
+
+== Un exemple de script rudimentaire 
+
+=== il pourrait ressembler à ceci :
+
+<code language="ruby">
+require 'robot'
+class NervousDuck
+   include Robot
+  def tick events
+    turn_radar 1 if time == 0
+    turn_gun 30 if time < 3
+    accelerate 1
+    turn 2
+    fire 3 unless events['robot_scanned'].empty? 
+  end
+end
+</code>
+
+*Précaution* : le fichier d'un robot doit avoir le même nom que la Classe du Robot (son nom), par exemple ici NervousDuck.rb
+
+== API RRobots 
+
+La seule méthode à implémenter au minimum pour animer votre robot est la méthode *tick* qui a pour paramètre *events*, un hachage des événements qui sont survenus pendant le dernier 'tick'.
+Un tick est une opération atomique pour tout les éléments du jeu.
+ 
+En incluant le module Ruby Robot vous récupérez les méthodes indispensable pour piloter votre robot :
+
+- *battlefield_height* : la longueur du champ de bataille 
+- *battlefield_width* : la largeur du champ de bataille
+- *energy* : la quantité d'énergie restante (si elle tombe à 0 votre robot meure )
+- *gun_heading* : l'orientation de votre canon, EST : 0 / NORD : 90 / OUEST : 180 / SUD : 270)
+- *gun_heat* : l'indicateur de surchauffe du canon, quand il re-descent à 0, vous pouvez tirer de nouveau
+- *heading* : l'orientation de votre robot, EST : 0 / NORD : 90 / OUEST : 180 / SUD : 270)
+- *size* : le rayon de votre robot, si x <= size vous heurtez le mur gauche
+- *radar_heading* : l'orientation de votre radar, EST : 0 / NORD : 90 / OUEST : 180 / SUD : 270)     
+- *time* : le nombre de 'tick' depuis le début du round.
+- *speed* : votre vitesse (-8/8)
+- *x* : votre abscisse X, dans l'intervalle 0...battlefield_width
+- *y* :  votre ordonné Y, dans l'intervalle 0...battlefield_height
+- *accelerate*(_param_) : définit l'accélération  (la vitesse max est  -8/8, l'acceleration max est 1/-1, une vitesse négative signifie reculer
+- *stop* : réduit votre vitesse à 0, l'opération prend 1 ticks par point de vitesse, positif ou négatif
+- *fire*(_power_) : lance un boulet de canon dans le sens de votre canon, la puissance va de 0,1 à 3 (plus la puissance est grande plus le temps de surchauffe est grand)
+- *turn*(_degrés_)* : tourne votre robot et donc votre canon et votre radar (max 10 degrés par tick)       
+- *turn_gun*(_degres_) : tourne votre canon et donc votre radar (max 30 degrés par tick)  
+- *turn_radar*(_degres_) : tourne votre radar (max 60 degrés par tick) 
+- *dead* : renvoie vrai si vous êtes mort
+
+* *say*(_msg_) : affiche un message sur l'écran en mode GUI/TK au dessus de votre robot.
+* *broadcast*(_msg_) : envoie un message à tous les robots sur le champs de bataille, une clef '*broadcast*' est ajouté au hachage '*events*' avec le message
+
+Cette liste de méthode est volontairement réduite et basique, à la charge du joueur créer ses propres méthodes de haut niveau grace à la puissance de Ruby.
+(exemple : move_to, fire_at, etc...)
+
+=== Quelques mots d'explication :
+
+- Le canon est monté sur le corps du robot, donc si vous bougez le robot le canon suit.
+Pareil pour le radar, qui se trouve sur le canon.
+
+- Le radar scan tout se qui trouve sur le rayon de déplacement cumulé du robot, du canon et du radar lui même (mouvement relatif du radar) sur un '*tick*' donné, mais ne renvoi que la distance vers le/les objets scannés (clef *scanned_robots* avec la distance en valeur pour les robots, et clef scanned_toolboxes avec la distance en valeur pour les boites à outils) ceci fait donc un angles d'incertitude maximum de 100°, pour pouvoir être précis il faut bouger votre radar plus doucement.
+
+- UG RRobots Fork introduit les boites à outils, elle sont donc détectables par le radar, lorsqu'un robot passe sur l'une d'elle, il récupère des points d'energie (20 par défaut).
+Les boites à outils apparaissent de façon aléatoire et reste pour une durée définie ( 200 ticks par défaut), chaque tick elle ont la même chance (faible) d'apparaître (1 sur 100 par défaut)
+
+UG RRobots Fork comme la version d'origine est implémenté en Ruby pur avec une Interface Graphique TK et peut tourner sur de nombreuses plateformes qui possèdent Ruby et TK, le moteur du jeu en lui même peu très bien se passer de TK.
+UG RRobots Fork à été testé sur Windows, la plus part des distributions Linux, FreeBSD et Windows
+
+== Utilisation du moteur de match simple 
+
+<pre>
+  ruby rrobots.rb [resolution] [#match] [-nogui] [-speed=<N>] [-timeout=<N>] [-with-toolboxes] <RobotClassName[.rb]> <RobotClassName[.rb]> <...>
+	  
+  [resolution] (optionel) doit être de la forme 640x480 ou 800*600. 
+    800x800 par défaut
+  [match] (optionel) pour rejouer un match, préciser un numéro de match , avec le signe 
+    # devant.
+  [-nogui] (optionel) lance le match sans GUI/TK, ignore -speed
+  [-with-toolboxes] (optionel) active l'apparition de boite à outils et leurs détections.
+  [-speed=<N>] (optionel, défaut 1) rafraîchit la  GUI après N ticks.  
+    Plus N est grand, plus le match s'affichera vite.
+  [-timeout=<N>] (optionel, defaut 50000) nombre de ticks maximum d'un match
+  [-ignore-config] (optional) pour ignorer la config au format YAML dan un fichier dans le path.
+  [-write-config] (optional) pour ecrire la config au format YAML dan un fichier dans le path.
+</pre>
+
+* le fichier d'un robot doit avoir le même nom que la Classe du Robot
+* (jusqu'à 8 robots)
+
+exemple :
+
+  ruby rrobots.rb SittingDuck NervousDuck'
+
+ou 
+
+  ruby rrobots.rb 600x600 #1234567890 SittingDuck NervousDuck'
+
+== Utilisation du moteur de tournoi :
+
+Pas besoin de TK 
+
+<pre>
+  ruby tournament.rb [-timeout=<N>] [-matches=<N>] (-dir=<Directory> | <RobotClassName[.rb]>+)
+
+  [-timeout=<N>] (optionel, defaut 50000) nombre de ticks maximum d'un match
+  [-with-toolboxes] (optionel) active l'apparition de boite à outils et leurs détections.
+  [-matches=<N>] (optionel, defaut 2) nombre de rounds par match entre deux robots
+  -dir=<Directory> tout les fichiers .rb dans le répertoire seront considérents comme des robots concurents 
+  [-ignore-config] (optional) pour ignorer la config au format YAML dan un fichier dans le path.
+</pre>
+
+- le fichier d'un robot doit avoir le même nom que la Classe du Robot
+- les robots s'affrontes un contre un
+- les resultats son disponible au formats YAML et HTML