/* $Id$ */

/** @file ai_controler.hpp declaration of class for AIController class */

#ifndef AI_CONTROLLER_HPP
#define AI_CONTROLLER_HPP

#include "../../stdafx.h"

/**
 * Class that handles the core of every AI. Each AI needs to extend this class
 *  in order to work. The OpenTTD core makes sure GetTick gets increased when
 *  needed.
 */
class AIController {
private:
	uint tick;

public:
	/**
	 * Initializer of the AIController.
	 */
	AIController() :
		tick(0)
	{}

	/**
	 * Destructor of the AIController.
	 */
	virtual ~AIController() { }

	/**
	 * This function is called to start your AI. Your AI starts here. If you
	 *   return from this function, your AI dies, so make sure that doesn't
	 *   happen. It is okay to use while() {} loops, as long as you put a
	 *   Sleep() in it to give the rest of the game time to do things. Also
	 *   don't keep the system busy for too long, as people will consider
	 *   that annoying.
	 * @note Cannot be called from within your AI.
	 */
	virtual void Start() = 0;

	/**
	 * When this function is called, the AI must stop as soon as possible.
	 *   It may not call any function that might suspend, like DoCommand()
	 *   and Sleep().
	 * @note Cannot be called from within your AI.
	 */
	virtual void Stop() = 0;

	/**
	 * Increase the internal ticker. You should never call this yourself,
	 *   as it is called by the OpenTTD system itself.
	 * @note Cannot be called from within your AI.
	 */
	void IncreaseTick() { this->tick++; }

	/**
	 * Find at which tick your AI currently is.
	 * @return returns the current tick.
	 */
	uint GetTick() { return this->tick; }

	/**
	 * Sleep for X ticks. The code continues after this line when the X AI ticks
	 *   are passed. Mind that an AI tick is different from in-game ticks and
	 *   differ per AI speed.
	 * @param ticks the ticks to wait
	 * @post the value of GetTick() will be changed exactly 'ticks' in value after
	 *   calling this.
	 */
	void Sleep(uint ticks);
};

#endif /* AI_CONTROLLER_HPP */

/*
 * The next part of the code is outside of the multiple inclusions
 * protection. This is done because the Squirrel code needs the
 * AIController class declaration to make the Squirrel registration
 * functions. So in the first include DEFINE_SQUIRREL_CLASS is not
 * defined, but in the second one it will when included from the
 * Squirrel AI implementation.
 * All other instances that include this header twice must not have
 * set DEFINE_SQUIRREL_CLASS, so this part will not be included
 * twice under those circumstances.
 */

#ifdef DEFINE_SQUIRREL_CLASS
void SQAIControllerRegister(Squirrel *engine) {
	DefSQClass <AIControllerSquirrel> SQAIController("AIController");
	SQAIController.PreRegister(engine);
	SQAIController.DefSQMethod(engine, &AIControllerSquirrel::GetTick, "GetTick");
	SQAIController.DefSQMethod(engine, &AIControllerSquirrel::Sleep,   "Sleep");
	SQAIController.PostRegister(engine);
}
#endif /* DEFINE_SQUIRREL_CLASS */