summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/ai/ai.hpp20
-rw-r--r--src/ai/ai_config.cpp1
-rw-r--r--src/ai/ai_config.hpp29
-rw-r--r--src/ai/ai_core.cpp7
-rw-r--r--src/ai/ai_gui.cpp4
-rw-r--r--src/ai/ai_info.cpp5
-rw-r--r--src/ai/ai_info.hpp32
-rw-r--r--src/ai/ai_info_dummy.cpp3
-rw-r--r--src/ai/ai_instance.cpp8
-rw-r--r--src/ai/ai_instance.hpp34
-rw-r--r--src/ai/ai_scanner.hpp3
11 files changed, 110 insertions, 36 deletions
diff --git a/src/ai/ai.hpp b/src/ai/ai.hpp
index ef0f6fc18..387812993 100644
--- a/src/ai/ai.hpp
+++ b/src/ai/ai.hpp
@@ -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 */
diff --git a/src/ai/ai_config.cpp b/src/ai/ai_config.cpp
index aab8b1f18..1c50a1d01 100644
--- a/src/ai/ai_config.cpp
+++ b/src/ai/ai_config.cpp
@@ -48,7 +48,6 @@ void AIConfig::ChangeAI(const char *name, int version, bool force_exact_match, b
}
this->AddRandomDeviation();
}
-
}
AIConfig::AIConfig(const AIConfig *config)
diff --git a/src/ai/ai_config.hpp b/src/ai/ai_config.hpp
index 98e98263c..c5b7c7482 100644
--- a/src/ai/ai_config.hpp
+++ b/src/ai/ai_config.hpp
@@ -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 */
diff --git a/src/ai/ai_core.cpp b/src/ai/ai_core.cpp
index ab950ef06..b6c072500 100644
--- a/src/ai/ai_core.cpp
+++ b/src/ai/ai_core.cpp
@@ -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());
diff --git a/src/ai/ai_gui.cpp b/src/ai/ai_gui.cpp
index e3f4c53bf..5a404b9d7 100644
--- a/src/ai/ai_gui.cpp
+++ b/src/ai/ai_gui.cpp
@@ -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;
diff --git a/src/ai/ai_info.cpp b/src/ai/ai_info.cpp
index 29abb7e15..5ccd934fd 100644
--- a/src/ai/ai_info.cpp
+++ b/src/ai/ai_info.cpp
@@ -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;
diff --git a/src/ai/ai_info.hpp b/src/ai/ai_info.hpp
index 9ef6e3df1..2f6edad01 100644
--- a/src/ai/ai_info.hpp
+++ b/src/ai/ai_info.hpp
@@ -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 */
diff --git a/src/ai/ai_info_dummy.cpp b/src/ai/ai_info_dummy.cpp
index f38832310..f706110f7 100644
--- a/src/ai/ai_info_dummy.cpp
+++ b/src/ai/ai_info_dummy.cpp
@@ -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.
diff --git a/src/ai/ai_instance.cpp b/src/ai/ai_instance.cpp
index 4a0924995..a1dc69d07 100644
--- a/src/ai/ai_instance.cpp
+++ b/src/ai/ai_instance.cpp
@@ -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()
diff --git a/src/ai/ai_instance.hpp b/src/ai/ai_instance.hpp
index f046aa86c..8d838f057 100644
--- a/src/ai/ai_instance.hpp
+++ b/src/ai/ai_instance.hpp
@@ -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;
-
- bool is_started;
- bool is_dead;
- bool is_save_data_on_stack;
- int suspend;
- AISuspendCallbackProc *callback;
+ 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; //!< 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.
diff --git a/src/ai/ai_scanner.hpp b/src/ai/ai_scanner.hpp
index 3a4fdc034..f88555699 100644
--- a/src/ai/ai_scanner.hpp
+++ b/src/ai/ai_scanner.hpp
@@ -18,6 +18,9 @@
#include "ai.hpp"
#include <map>
+/**
+ * Class that scans for available AIs.
+ */
class AIScanner : public ScriptScanner {
public:
AIScanner();
generated by cgit v1.2.3-54-g00ecf (git 2.44.0) at 2024-07-06 13:04:07 +0000