mirrors
/
OpenTTD
mirror of https://github.com/OpenTTD/OpenTTD.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

(svn r20271) -Doc: add doxygen comments to several items under src/ai/

This commit is contained in:
yexo 2010-07-31 22:16:34 +00:00
parent 5b20472ccb
commit 6d4900ed7c
11 changed files with 109 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/ai/ai.hpp
View File

@ -18,9 +18,12 @@
#include "../core/string_compare_type.hpp"
#include <map>
/** A list that maps AI names to their AIInfo object. */
typedef std::map<const char *, class AIInfo *, StringCompare> AIInfoList;
/**
* Main AI class. Contains all functions needed to start, stop, save and load AIs.
*/
class AI {
public:
/**
@ -121,18 +124,29 @@ public:
*/
static int GetStartNextTime();
/** Wrapper function for AIScanner::GetAIConsoleList */
static char *GetConsoleList(char *p, const char *last);
/** Wrapper function for AIScanner::GetAIInfoList */
static const AIInfoList *GetInfoList();
/** Wrapper function for AIScanner::GetUniqueAIInfoList */
static const AIInfoList *GetUniqueInfoList();
/** Wrapper function for AIScanner::FindInfo */
static AIInfo *FindInfo(const char *name, int version, bool force_exact_match);
/** Wrapper function for AIScanner::ImportLibrary */
static bool ImportLibrary(const char *library, const char *class_name, int version, HSQUIRRELVM vm);
/**
* Rescans all searchpaths for available AIs. If a used AI is no longer
* found it is removed from the config.
*/
static void Rescan();
#if defined(ENABLE_NETWORK)
/** Wrapper function for AIScanner::HasAI */
static bool HasAI(const struct ContentInfo *ci, bool md5sum);
#endif
private:
static uint frame_counter;
static class AIScanner *ai_scanner;
static uint frame_counter; //!< Tick counter for the AI code
static class AIScanner *ai_scanner; //!< AIScanner instance that is used to find AIs
};
#else /* ENABLE_AI */

1
src/ai/ai_config.cpp
View File

@ -48,7 +48,6 @@ void AIConfig::ChangeAI(const char *name, int version, bool force_exact_match, b
}
this->AddRandomDeviation();
}
}
AIConfig::AIConfig(const AIConfig *config)

29
src/ai/ai_config.hpp
View File

@ -18,8 +18,12 @@
#include "../core/string_compare_type.hpp"
#include "../company_type.h"
/**
* AI settings for one company slot.
*/
class AIConfig {
private:
/** List with name=>value pairs of all AI-specific settings */
typedef std::map<const char *, int, StringCompare> SettingValueList;
public:
@ -30,7 +34,14 @@ public:
config_list(NULL),
is_random_ai(false)
{}
/**
* Create a new AI config that is a copy of an existing config.
* @param config The object to copy.
*/
AIConfig(const AIConfig *config);
/** Delete an AI configuration. */
~AIConfig();
/**
@ -61,8 +72,10 @@ public:
*/
const AIConfigItemList *GetConfigList();
/* Where to get the config from, either default (depends on current game
* mode) or force either newgame or normal */
/**
* Where to get the config from, either default (depends on current game
* mode) or force either newgame or normal
*/
enum AISettingSource {
AISS_DEFAULT, ///< Get the AI config from the current game mode
AISS_FORCE_NEWGAME, ///< Get the newgame AI config
@ -131,12 +144,12 @@ public:
void SettingsToString(char *string, size_t size) const;
private:
const char *name;
int version;
class AIInfo *info;
SettingValueList settings;
AIConfigItemList *config_list;
bool is_random_ai;
const char *name; //!< Name of the AI
int version; //!< Version of the AI
class AIInfo *info; //!< AIInfo object for related to this AI version
SettingValueList settings; //!< List with all setting=>value pairs that are configure for this AI
AIConfigItemList *config_list; //!< List with all settings defined by this AI
bool is_random_ai; //!< True if the AI in this slot was randomly chosen.
};
#endif /* ENABLE_AI */

7
src/ai/ai_core.cpp
View File

@ -229,6 +229,13 @@
event->Release();
}
/**
* DoCommand callback function for all commands executed by AIs.
* @param result The result of the command.
* @param tile The tile on which the command was executed.
* @param p1 p1 as given to DoCommandPInternal.
* @param p2 p2 as given to DoCommandPInternal.
*/
void CcAI(const CommandCost &result, TileIndex tile, uint32 p1, uint32 p2)
{
AIObject::SetLastCommandRes(result.Succeeded());

4
src/ai/ai_gui.cpp
View File

@ -695,8 +695,8 @@ enum AIDebugWindowWidgets {
* Window with everything an AI prints via AILog.
*/
struct AIDebugWindow : public QueryStringBaseWindow {
static const int top_offset; ///< Offset of the text at the top of the #AID_WIDGET_LOG_PANEL.
static const int bottom_offset; ///< Offset of the text at the bottom of the #AID_WIDGET_LOG_PANEL.
static const int top_offset; ///< Offset of the text at the top of the ::AID_WIDGET_LOG_PANEL.
static const int bottom_offset; ///< Offset of the text at the bottom of the ::AID_WIDGET_LOG_PANEL.
static const unsigned int MAX_BREAK_STR_STRING_LENGTH = 256;

5
src/ai/ai_info.cpp
View File

@ -21,6 +21,7 @@
#include "../debug.h"
#include "../rev.h"
/** Configuration for AI start date, every AI has this setting. */
AIConfigItem _start_date_config = {
"start_date",
"The amount of days after the start of the last AI, this AI will start (give or take).",
@ -50,6 +51,10 @@ AILibrary::~AILibrary()
return 0;
}
/**
* Check if the API version provided by the AI is supported.
* @param api_version The API version as provided by the AI.
*/
static bool CheckAPIVersion(const char *api_version)
{
return strcmp(api_version, "0.7") == 0 || strcmp(api_version, "1.0") == 0 || strcmp(api_version, "1.1") == 0;

32
src/ai/ai_info.hpp
View File

@ -18,15 +18,17 @@
#include "../core/smallmap_type.hpp"
#include "../script/script_info.hpp"
/** Bitmask of flags for AI settings. */
enum AIConfigFlags {
AICONFIG_NONE = 0x0,
AICONFIG_NONE = 0x0, //!< No flags set.
AICONFIG_RANDOM = 0x1, //!< When randomizing the AI, pick any value between min_value and max_value when on custom difficulty setting.
AICONFIG_BOOLEAN = 0x2, //!< This value is a boolean (either 0 (false) or 1 (true) ).
AICONFIG_INGAME = 0x4, //!< This setting can be changed while the AI is running.
};
typedef SmallMap<int, char *> LabelMapping;
typedef SmallMap<int, char *> LabelMapping; //!< Map-type used to map the setting numbers to labels.
/** Info about a single AI setting. */
struct AIConfigItem {
const char *name; //!< The name of the configuration setting.
const char *description; //!< The description of the configuration setting.
@ -44,8 +46,9 @@ struct AIConfigItem {
extern AIConfigItem _start_date_config;
typedef std::list<AIConfigItem> AIConfigItemList;
typedef std::list<AIConfigItem> AIConfigItemList; //!< List of AIConfig items.
/** Base class that holds some basic information about AIs and AI libraries. */
class AIFileInfo : public ScriptFileInfo {
public:
/**
@ -54,9 +57,10 @@ public:
static SQInteger Constructor(HSQUIRRELVM vm, AIFileInfo *info);
protected:
class AIScanner *base;
class AIScanner *base; //!< AIScanner object that was used to scan this AI (library) info.
};
/** All static information from an AI like name, version, etc. */
class AIInfo : public AIFileInfo {
public:
static const char *GetClassName() { return "AIInfo"; }
@ -68,6 +72,10 @@ public:
* Create an AI, using this AIInfo as start-template.
*/
static SQInteger Constructor(HSQUIRRELVM vm);
/**
* Create a dummy-AI.
*/
static SQInteger DummyConstructor(HSQUIRRELVM vm);
/**
@ -116,12 +124,13 @@ public:
const char *GetAPIVersion() const { return this->api_version; }
private:
AIConfigItemList config_list;
int min_loadable_version;
bool use_as_random;
const char *api_version;
AIConfigItemList config_list; //!< List of settings from this AI.
int min_loadable_version; //!< The AI can load savegame data if the version is equal or greater than this.
bool use_as_random; //!< Should this AI be used when the user wants a "random AI"?
const char *api_version; //!< API version used by this AI.
};
/** All static information from an AI library like name, version, etc. */
class AILibrary : public AIFileInfo {
public:
AILibrary() : AIFileInfo(), category(NULL) {};
@ -132,6 +141,11 @@ public:
*/
static SQInteger Constructor(HSQUIRRELVM vm);
/**
* Import a library in the current AI. This function can be used by AIs
* by calling import.
* @param vm The squirrel vm of the calling AI.
*/
static SQInteger Import(HSQUIRRELVM vm);
/**
@ -140,7 +154,7 @@ public:
const char *GetCategory() const { return this->category; }
private:
const char *category;
const char *category; //!< The category this library is in.
};
#endif /* ENABLE_AI */

3
src/ai/ai_info_dummy.cpp
View File

@ -25,6 +25,7 @@
* to select manual. It is a fail-over in case no AIs are available.
*/
/** info.nut for the dummy AI. */
const SQChar _dummy_script_info[] = _SC(" \n\
class DummyAI extends AIInfo { \n\
function GetAuthor() { return \"OpenTTD NoAI Developers Team\"; } \n\
@ -39,6 +40,7 @@ class DummyAI extends AIInfo {
RegisterDummyAI(DummyAI()); \n\
");
/** Run the dummy info.nut. */
void AI_CreateAIInfoDummy(HSQUIRRELVM vm)
{
sq_pushroottable(vm);
@ -54,6 +56,7 @@ void AI_CreateAIInfoDummy(HSQUIRRELVM vm)
NOT_REACHED();
}
/** Run the dummy AI and let it generate an error message. */
void AI_CreateAIDummy(HSQUIRRELVM vm)
{
/* We want to translate the error message.

8
src/ai/ai_instance.cpp
View File

@ -87,6 +87,11 @@ AIStorage::~AIStorage()
if (log_data != NULL) AILog::FreeLogPointer();
}
/**
* Callback called by squirrel when an AI uses "print" and for error messages.
* @param error_msg Is this an error message?
* @param message The actual message text.
*/
static void PrintFunc(bool error_msg, const SQChar *message)
{
/* Convert to OpenTTD internal capable string */
@ -453,8 +458,9 @@ enum SQSaveLoadType {
SQSL_ARRAY_TABLE_END = 0xFF, ///< Marks the end of an array or table, no data follows.
};
static byte _ai_sl_byte;
static byte _ai_sl_byte; //!< Used as source/target by the AI saveload code to store/load a single byte.
/** SaveLoad array that saves/loads exactly one byte. */
static const SaveLoad _ai_byte[] = {
SLEG_VAR(_ai_sl_byte, SLE_UINT8),
SLE_END()

32
src/ai/ai_instance.hpp
View File

@ -29,12 +29,21 @@ public:
callback(callback)
{}
/**
* Get the amount ot ticks the AI should be suspended.
* @return The amount of AI ticks to suspend the AI.
*/
int GetSuspendTime() { return time; }
/**
* Get the callback to call when the AI can run again.
* @return The callback function to run.
*/
AISuspendCallbackProc *GetSuspendCallback() { return callback; }
private:
int time;
AISuspendCallbackProc *callback;
int time; //!< Amount of ticks to suspend the AI.
AISuspendCallbackProc *callback; //!< Callback function to call when the AI can run again.
};
/**
@ -52,6 +61,7 @@ private:
const char *msg;
};
/** Runtime information about an AI like a pointer to the squirrel vm and the current state. */
class AIInstance {
public:
friend class AIObject;
@ -145,16 +155,16 @@ public:
*/
void Suspend();
private:
class AIController *controller;
class AIStorage *storage;
class Squirrel *engine;
SQObject *instance;
class AIController *controller; //!< The AI main class.
class AIStorage *storage; //!< Some global information for each running AI.
class Squirrel *engine; //!< A wrapper around the squirrel vm.
SQObject *instance; //!< Squirrel-pointer to the AI main class.
bool is_started;
bool is_dead;
bool is_save_data_on_stack;
int suspend;
AISuspendCallbackProc *callback;
bool is_started; //!< Is the AIs constructor executed?
bool is_dead; //!< True if the AI has been stopped.
bool is_save_data_on_stack; //!< Is the save data still on the squirrel stack?
int suspend; //!< The amount of ticks to suspend this AI before it's allowed to continue.
AISuspendCallbackProc *callback; //!< Callback that should be called in the next tick the AI runs.
/**
* Register all API functions to the VM.

3
src/ai/ai_scanner.hpp
View File

@ -18,6 +18,9 @@
#include "ai.hpp"
#include <map>
/**
* Class that scans for available AIs.
*/
class AIScanner : public ScriptScanner {
public:
AIScanner();