====== CADIARover ======

The CADIARover provides a flat 3D world (RobotSim) in which lives a robot rover, as well as middleware (Psyclone) for connecting the Rover to its brain/mind. Your goal is to code the rover's mind. 

=== RobotSim World ===

You can navigate manually in the 3D world using the mouse (yaw, pitch) the arrow keys (left right forward backward) and the page up / down keys (up down). The S key will display stats (basically the FPS), the V key displays the two sensor cones.

Rocks are spread randomly and come in two colors: yellow and green. Both add to the score when picked up and can be delivered to the bins (adds to the score too), but picking a green one consumes more energy.

The world is randomly populated by white objects - danger zones - that consume energy when crossed.

The world also feature four teleportation pods, very roughly arranged in a squarish form. When you enter one from the west or east you'll reappear on the teleporter located roughly at the same latitude. If you enter from the north or south, you will reappear in the teleporter located on the same longitude.

There are two (blue) bins in the world.

=== Rover ===

The rover moves like a tank. You can control the speed on the left and / or the right side. It is equipped with a basic autopilot: given an angle relatively to the rover's current heading and a distance, it will slow down then stop, rotate and eventually reach its destination in a straight line at a given speed. Autopilot can be canceled and resumed without losing its target.

The rover has two sensors, directed towards the front: a low resolution cone that gives you the relative angle and distance of an object (low accuracy), and a high resolution cone, narrower and shorter, that gives the type and color of an object. In addition, the rover can detect collisions with its hull, giving the same information as the high resolution sensor, on 360 degrees, but at distance 0.

The rover also reports periodically its current status: heading (low accuracy), wheel speed and ground speed. It will notify you when it reaches its destination in autopilot mode (more precisely, when the destination lies under a certain distance threshold). Finally, you will be notified when teleportation occurs.

The rover has a limited carrying capacity.

For the details see PsySpec.xml in the RobotSim directory.

===== Development =====

=== Settings ===

These values define the parameters that will be used in the final evaluation runs:

<parameter name="pickables_good" type="Integer" value="10"/>

<parameter name="pickables_bad" type="Integer" value="100"/>

<parameter name="danger_zones" type="Integer" value="10"/>

<parameter name="bin_collision_distance" type="Double" value="40"/>

<parameter name="pickable_good_collision_distance" type="Double" value="10"/>

<parameter name="pickable_bad_collision_distance" type="Double" value="10"/>

<parameter name="teleporter_collision_distance" type="Double" value="20"/>

<parameter name="danger_zone_collision_distance" type="Double" value="40"/>

<parameter name="landmark_collision_distance" type="Double" value="10"/>

<parameter name="speedModule" type="Double" value="0.2"/>

<parameter name="acceleration" type="Double" value="0.01"/><!--in [0,1] per ms2-->

<parameter name="deceleration" type="Double" value="0.01"/><!--in [0,1] per ms2-->

<parameter name="lowRes_aperture" type="Double" value="60"/>

<parameter name="lowRes_range" type="Double" value="300"/>

<parameter name="hiRes_aperture" type="Double" value="45"/>

<parameter name="hiRes_range" type="Double" value="160"/>

<parameter name="carrying_capacity" type="Integer" value="3"/>

<parameter name="autopilot_distance_threshold" type="Double" value="50"/>

<parameter name="energy_initial" type="Double" value="1000000000"/>

<parameter name="energy_per_pickable_good" type="Double" value="0"/><!--units gained per item-->

<parameter name="energy_per_pickable_bad" type="Double" value="0"/><!--units gained per item-->

<parameter name="energy_per_danger_zone" type="Double" value="2"/><!--units gained per crossing-->

<parameter name="energy_per_time_idle" type="Double" value="0.00001"/><!--units per ms-->

<parameter name="energy_per_time_move" type="Double" value="0.0001"/><!--units per ms-->

<parameter name="energy_per_landmark" type="Double" value="2"/><!--units gained per leaving a landmark-->

<parameter name="score_per_pickable_good" type="Double" value="100"/><!--gained per item-->

<parameter name="score_per_pickable_bad" type="Double" value="20"/><!--gained per item-->

<parameter name="score_per_delivery" type="Double" value="40"/><!--gained per item delivered in a bin-->

<parameter name="score_per_consumed_energy" type="Double" value="-30"/><!--per energy unit-->

<parameter name="time_limit" type="Integer" value="300000"/><!--in ms-->

<parameter name="max_landmarks" type="Integer" value="100"/>


=== Latest Update ===

{{public:t-622-arti-08-1:cadia.module.robotsim.3dworld.01.04.08.rar|}} - 01.04.08: dll

bug fix: the graphics for the sensors used the aperture values as the full angle instead of the half-angles
bug fix: energy consumption is now accounted for in the score.

NB: settings have been updated too by the game committee.

{{public:t-622-arti-08-1:cadia.module.robotsim.3dworld.31.03.08.rar|}} - 31.03.08: dll

bug fix: for ultra fast machines, frame period could be 0, yielding ground_speed #INF. 
when that's the case, the frame is now skipped

{{public:t-622-arti-08-1:cadia.module.robotsim.3dworld.36.03.08.rar|}} - 26.03.08: dll, PsySpec.xml

added robot.eof message: this indicates the end of receiving sensory messages (they begin after the status message).

{{public:t-622-arti-08-1:cadia.module.robotsim.3dworld.24.03.08.rar|}} - 24.03.08: dll
Bug fixes:
ids are now part of the hi/low res and collision messages - source code update available on svn: http://cadia.ru.is/svn/repos/software/Psyclone/CADIA/Modules/RobotSim/

{{public:t-622-arti-08-1:cadia.module.robotsim.3dworld.rar|}} - 07.03.2008: dll, RobotSim.material and PsySpec.xml

Bug fixes: 

- autopilot works better with fast computers

- autopilot retargets even if the trajectory is manually altered

- Psyclone does not complain anymore about perception messages

New features:

- added sin_angle in perception messages both low and hi resolution.

- objects have a unique ID; they will appear in HiRes sensors reports and LowRes too (in the latter case, only if a HiRes sensing occured first)

- the rover can leave landmarks - orange small cubes - (they have unique IDs too), for an energy cost (L key to leave one manually). Landmarks appear right under the rover: to be perceived, the rover has first to get away from it at least 2 x the collision distance (otherwise you would receive instantly collision messages).

- on simulation startup, a message "robot.start" is issued, with the starting time and time limit: you should wait for that message to start your code

- when the rover moves off the world limits it receives a message "robot.sensor.offLimit"

- perceptions occurring during the same frame have now the same time stamp: you can then group them by time stamp if you wish

NB1: to read parameters from the PsySpec file: messenger->getParameterX("Y","Z"); where X is Integer, Double or String, Y is the module name - in our case CADIA.Module.RobotSim.3DWorld - and Z is the parameter name as used in the file.

NB2: don't forget to update - besides the main dll - RobotSim.material and PsySpec.xml

-----

=== Environment ===
You need to set your command and path variables in Visual Studio:

  Command="$(PSYCLONE_DIR)\psyclone.exe"
  CommandArguments="spec=$(SolutionDir)\$(ProjectName)\PsySpec.xml"
  WorkingDirectory="$(SolutionDir)\release"

Also these environment variables need to be set:

  PSYCLONE_DIR = C:\AI_Class_Setup_Dir\Psyclone\psyclone1.1.7.CADIA.win32net05
  PSYCLONE_SDK_DIR = C:\AI_Class_Setup_Dir\Psyclone\psyclonesdk1.1.7.pbl.win32net05
  OGRE_HOME = C:\AI_Class_Setup_Dir\OgreSDK

Bjarni Þór Árnason has offered his own setup to those who are interested: http://www.steik.org/dump/AI_Class_Setup_Dir_Bjarni.rar (Notice: This is offered as-is with no guarantees or promises.)

=== C++ ===

You will code C++ Psyclone cranks, i.e. dll code to be executed as threads by the Psyclone middleware. The 3DWorld is one of them.

Pysclone modules send and receive messages -- reception of messages is dependent on their subscriptions (see Psyclone documentation in psyclone1.1.7.CADIA.win32\html) defined in the PsySpec file.

You can use the Test function defined in cranks.cpp in the RobotSim project as a template for creating a module. You can define as many cranks as you want.

Create a new visual studio solution getting most of the settings from the RobotSim.sln. By most, we mean everything but the settings relevant to Ogre. You can also duplicate the RobotSim.sln and 3DWorld.vcproj files - maybe requiring minor manual tweaking in a text editor.

Shall you start from scratch, you will have to include files from psyclone sdk \ Core Library \ include, and link against CoreLibrary.lib, Psapi.lib and IPHlpApix.lib, located in psyclone sdk \ Core Library. These are release builds; shall you run in debug mode, use the version of CoreLibrary under the debug directory.

In any case copy the files dll.* and cranks.* in your source directory, load them in your project, remove the Runtime crank, rename Test and code your own crank. Shall you need more cranks, define more functions on the same template. Copy also the PsySpec.xml with no change. Then add the specification of your own crank(s).

Note: a Psyclone module is a set of cranks. You can define more than one module, with more than one crank.

As for RobotSim.sln, setup the execution in the project properties, debugging section: that's how you'll start the application.

To stop: in debug mode, use the debugger stop button; in release mode, 3 times CTRL-C in the Psyclone shell window.