src/ai/api/ai_controller.hpp
branchnoai
changeset 9448 2a4c4340233d
parent 9444 fd27df7ca2a0
child 9520 f7cf8bea10db
equal deleted inserted replaced
9447:8f3c1bc72204 9448:2a4c4340233d
     5 #ifndef AI_CONTROLLER_HPP
     5 #ifndef AI_CONTROLLER_HPP
     6 #define AI_CONTROLLER_HPP
     6 #define AI_CONTROLLER_HPP
     7 
     7 
     8 #include "../../stdafx.h"
     8 #include "../../stdafx.h"
     9 
     9 
       
    10 /**
       
    11  * Class that handles the core of every AI. Each AI needs to extend this class
       
    12  *  in order to work. The OpenTTD core makes sure GetTick gets increased when
       
    13  *  needed.
       
    14  */
    10 class AIController {
    15 class AIController {
    11 private:
    16 private:
    12 	uint tick;
    17 	uint tick;
    13 
    18 
    14 public:
    19 public:
       
    20 	/**
       
    21 	 * Initializer of the AIController.
       
    22 	 */
    15 	AIController() :
    23 	AIController() :
    16 		tick(0)
    24 		tick(0)
    17 	{}
    25 	{}
    18 
    26 
       
    27 	/**
       
    28 	 * Destructor of the AIController.
       
    29 	 */
    19 	virtual ~AIController() { }
    30 	virtual ~AIController() { }
    20 
    31 
    21 	/**
    32 	/**
    22 	 * This function is called once to start the AI.
    33 	 * This function is called to start your AI. Your AI starts here. If you
       
    34 	 *   return from this function, your AI dies, so make sure that doesn't
       
    35 	 *   happen. It is okay to use while() {} loops, as long as you put a
       
    36 	 *   Sleep() in it to give the rest of the game time to do things. Also
       
    37 	 *   don't keep the system busy for too long, as people will consider
       
    38 	 *   that annoying.
       
    39 	 * @note Cannot be called from within your AI.
    23 	 */
    40 	 */
    24 	virtual void Start() = 0;
    41 	virtual void Start() = 0;
    25 
    42 
    26 	/**
    43 	/**
    27 	 * When this function is called, the AI must stop
    44 	 * When this function is called, the AI must stop as soon as possible.
    28 	 * as soon as possible. It may not call any function
    45 	 *   It may not call any function that might suspend, like DoCommand()
    29 	 * that might suspend, like DoCommand and Sleep.
    46 	 *   and Sleep().
    30 	 * @note This is only called when the AI is currently
    47 	 * @note Cannot be called from within your AI.
    31 	 *       in a suspended state.
       
    32 	 */
    48 	 */
    33 	virtual void Stop() = 0;
    49 	virtual void Stop() = 0;
    34 
    50 
    35 	/**
    51 	/**
    36 	 * Increase the internal ticker.
    52 	 * Increase the internal ticker. You should never call this yourself,
       
    53 	 *   as it is called by the OpenTTD system itself.
       
    54 	 * @note Cannot be called from within your AI.
    37 	 */
    55 	 */
    38 	void IncreaseTick() { this->tick++; }
    56 	void IncreaseTick() { this->tick++; }
    39 
    57 
    40 	/**
    58 	/**
    41 	 * Return the value of the ticker.
    59 	 * Find at which tick your AI currently is.
       
    60 	 * @return returns the current tick.
    42 	 */
    61 	 */
    43 	uint GetTick() { return this->tick; }
    62 	uint GetTick() { return this->tick; }
    44 
    63 
    45 	/**
    64 	/**
    46 	 * Sleep for X ticks. The code continues after this line when the X AI ticks
    65 	 * Sleep for X ticks. The code continues after this line when the X AI ticks
    47 	 *  are passed. Mind that an AI tick is different from in-game ticks and
    66 	 *   are passed. Mind that an AI tick is different from in-game ticks and
    48 	 *  differ per AI speed.
    67 	 *   differ per AI speed.
       
    68 	 * @param ticks the ticks to wait
       
    69 	 * @post the value of GetTick() will be changed exactly 'ticks' in value after
       
    70 	 *   calling this.
    49 	 */
    71 	 */
    50 	void Sleep(uint ticks);
    72 	void Sleep(uint ticks);
    51 };
    73 };
    52 
    74 
    53 #endif /* AI_CONTROLLER_HPP */
    75 #endif /* AI_CONTROLLER_HPP */