summaryrefslogtreecommitdiff
path: root/src/ai/api
diff options
context:
space:
mode:
authortruebrain <truebrain@openttd.org>2011-11-29 23:31:55 +0000
committertruebrain <truebrain@openttd.org>2011-11-29 23:31:55 +0000
commit0f9954ec1bfa95e487fa709cb64e01deb0e3cba8 (patch)
treeced3cb6f5a9d3206086f6ec4fb92f8cc35ec1d62 /src/ai/api
parent7158aaea3100fbae72c75645800592117375f897 (diff)
downloadopenttd-0f9954ec1bfa95e487fa709cb64e01deb0e3cba8.tar.xz
(svn r23374) -Add: Doxygen files for the NoAI API (Yexo)
Diffstat (limited to 'src/ai/api')
-rw-r--r--src/ai/api/Doxyfile250
-rw-r--r--src/ai/api/ai_changelog.hpp277
-rw-r--r--src/ai/api/ai_info_docs.hpp243
3 files changed, 0 insertions, 770 deletions
diff --git a/src/ai/api/Doxyfile b/src/ai/api/Doxyfile
deleted file mode 100644
index 9ce9684a3..000000000
--- a/src/ai/api/Doxyfile
+++ /dev/null
@@ -1,250 +0,0 @@
-# $Id$
-
-# This file is part of OpenTTD.
-# OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
-# OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-# See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
-
-# Doxyfile 1.5.4
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING = UTF-8
-PROJECT_NAME = "OpenTTD NoAI API "
-PROJECT_NUMBER =
-OUTPUT_DIRECTORY = ../../../docs/aidocs/
-CREATE_SUBDIRS = NO
-OUTPUT_LANGUAGE = English
-BRIEF_MEMBER_DESC = YES
-REPEAT_BRIEF = YES
-ABBREVIATE_BRIEF = "The $name class " \
- "The $name widget " \
- "The $name file " \
- is \
- provides \
- specifies \
- contains \
- represents \
- a \
- an \
- the
-ALWAYS_DETAILED_SEC = NO
-INLINE_INHERITED_MEMB = NO
-FULL_PATH_NAMES = YES
-STRIP_FROM_PATH = ./
-STRIP_FROM_INC_PATH =
-SHORT_NAMES = NO
-JAVADOC_AUTOBRIEF = YES
-QT_AUTOBRIEF = NO
-MULTILINE_CPP_IS_BRIEF = NO
-INHERIT_DOCS = YES
-SEPARATE_MEMBER_PAGES = NO
-TAB_SIZE = 2
-ALIASES =
-OPTIMIZE_OUTPUT_FOR_C = YES
-OPTIMIZE_OUTPUT_JAVA = NO
-BUILTIN_STL_SUPPORT = NO
-CPP_CLI_SUPPORT = NO
-SIP_SUPPORT = NO
-DISTRIBUTE_GROUP_DOC = NO
-SUBGROUPING = YES
-TYPEDEF_HIDES_STRUCT = NO
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL = NO
-EXTRACT_PRIVATE = NO
-EXTRACT_STATIC = YES
-EXTRACT_LOCAL_CLASSES = YES
-EXTRACT_LOCAL_METHODS = YES
-EXTRACT_ANON_NSPACES = NO
-HIDE_UNDOC_MEMBERS = NO
-HIDE_UNDOC_CLASSES = NO
-HIDE_FRIEND_COMPOUNDS = NO
-HIDE_IN_BODY_DOCS = YES
-INTERNAL_DOCS = YES
-CASE_SENSE_NAMES = YES
-HIDE_SCOPE_NAMES = NO
-SHOW_INCLUDE_FILES = NO
-INLINE_INFO = YES
-SORT_MEMBER_DOCS = YES
-SORT_BRIEF_DOCS = NO
-SORT_BY_SCOPE_NAME = NO
-GENERATE_TODOLIST = NO
-GENERATE_TESTLIST = NO
-GENERATE_BUGLIST = NO
-GENERATE_DEPRECATEDLIST= NO
-ENABLED_SECTIONS =
-MAX_INITIALIZER_LINES = 30
-SHOW_USED_FILES = NO
-SHOW_DIRECTORIES = NO
-FILE_VERSION_FILTER =
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET = NO
-WARNINGS = YES
-WARN_IF_UNDOCUMENTED = YES
-WARN_IF_DOC_ERROR = YES
-WARN_NO_PARAMDOC = YES
-WARN_FORMAT = "$file:$line: $text "
-WARN_LOGFILE =
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT = .
-INPUT_ENCODING = UTF-8
-FILE_PATTERNS = *.h \
- *.hpp
-RECURSIVE = YES
-EXCLUDE =
-EXCLUDE_SYMLINKS = NO
-EXCLUDE_PATTERNS =
-EXCLUDE_SYMBOLS = GetClassName DECLARE_ENUM_AS_BIT_SET DECLARE_POSTFIX_INCREMENT
-EXAMPLE_PATH =
-EXAMPLE_PATTERNS = *
-EXAMPLE_RECURSIVE = NO
-IMAGE_PATH =
-INPUT_FILTER =
-FILTER_PATTERNS =
-FILTER_SOURCE_FILES = NO
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER = NO
-INLINE_SOURCES = NO
-STRIP_CODE_COMMENTS = YES
-REFERENCED_BY_RELATION = NO
-REFERENCES_RELATION = NO
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS = NO
-VERBATIM_HEADERS = NO
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX = NO
-COLS_IN_ALPHA_INDEX = 5
-IGNORE_PREFIX =
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML = YES
-HTML_OUTPUT = html
-HTML_FILE_EXTENSION = .html
-HTML_HEADER =
-HTML_FOOTER =
-HTML_STYLESHEET =
-HTML_ALIGN_MEMBERS = YES
-GENERATE_HTMLHELP = NO
-HTML_DYNAMIC_SECTIONS = NO
-CHM_FILE =
-HHC_LOCATION =
-GENERATE_CHI = NO
-BINARY_TOC = NO
-TOC_EXPAND = NO
-DISABLE_INDEX = NO
-ENUM_VALUES_PER_LINE = 1
-GENERATE_TREEVIEW = NO
-TREEVIEW_WIDTH = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX = NO
-LATEX_OUTPUT = latex
-LATEX_CMD_NAME = latex
-MAKEINDEX_CMD_NAME = makeindex
-COMPACT_LATEX = NO
-PAPER_TYPE = a4wide
-EXTRA_PACKAGES =
-LATEX_HEADER =
-PDF_HYPERLINKS = NO
-USE_PDFLATEX = NO
-LATEX_BATCHMODE = NO
-LATEX_HIDE_INDICES = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF = NO
-RTF_OUTPUT = rtf
-COMPACT_RTF = NO
-RTF_HYPERLINKS = NO
-RTF_STYLESHEET_FILE =
-RTF_EXTENSIONS_FILE =
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN = NO
-MAN_OUTPUT = man
-MAN_EXTENSION = .3
-MAN_LINKS = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML = NO
-XML_OUTPUT = xml
-XML_SCHEMA =
-XML_DTD =
-XML_PROGRAMLISTING = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD = NO
-PERLMOD_LATEX = NO
-PERLMOD_PRETTY = YES
-PERLMOD_MAKEVAR_PREFIX =
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING = YES
-MACRO_EXPANSION = YES
-EXPAND_ONLY_PREDEF = YES
-SEARCH_INCLUDES = YES
-INCLUDE_PATH =
-INCLUDE_FILE_PATTERNS =
-PREDEFINED = DOXYGEN_API
-EXPAND_AS_DEFINED = DEF_COMMAND
-SKIP_FUNCTION_MACROS = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references
-#---------------------------------------------------------------------------
-TAGFILES =
-GENERATE_TAGFILE = openttd.tag
-ALLEXTERNALS = NO
-EXTERNAL_GROUPS = YES
-PERL_PATH = /usr/bin/perl
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS = YES
-MSCGEN_PATH =
-HIDE_UNDOC_RELATIONS = YES
-HAVE_DOT = NO
-CLASS_GRAPH = YES
-COLLABORATION_GRAPH = YES
-GROUP_GRAPHS = YES
-UML_LOOK = NO
-TEMPLATE_RELATIONS = NO
-INCLUDE_GRAPH = YES
-INCLUDED_BY_GRAPH = YES
-CALL_GRAPH = NO
-CALLER_GRAPH = NO
-GRAPHICAL_HIERARCHY = YES
-DIRECTORY_GRAPH = YES
-DOT_IMAGE_FORMAT = png
-DOT_PATH =
-DOTFILE_DIRS =
-DOT_GRAPH_MAX_NODES = 50
-MAX_DOT_GRAPH_DEPTH = 1000
-DOT_TRANSPARENT = NO
-DOT_MULTI_TARGETS = NO
-GENERATE_LEGEND = NO
-DOT_CLEANUP = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine
-#---------------------------------------------------------------------------
-SEARCHENGINE = NO
diff --git a/src/ai/api/ai_changelog.hpp b/src/ai/api/ai_changelog.hpp
deleted file mode 100644
index 99d892497..000000000
--- a/src/ai/api/ai_changelog.hpp
+++ /dev/null
@@ -1,277 +0,0 @@
-/* $Id$ */
-
-/*
- * This file is part of OpenTTD.
- * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
- * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
- */
-
-/**
- * @file ai_changelog.hpp Lists all changes / additions to the API.
- *
- * Only new / renamed / deleted api functions will be listed here. A list of
- * bug fixes can be found in the normal changelog. Note that removed API
- * functions may still be available if you return an older API version
- * in GetAPIVersion() in info.nut.
- *
- * \b 1.2.0
- *
- * 1.2.0 is not yet released. The following changes are not set in stone yet.
- *
- * API additions:
- *
- * \li AICargo::CT_AUTO_REFIT
- * \li AICargo::CT_NO_REFIT
- * \li AICargo::IsValidTownEffect
- * \li AICargoList_StationAccepting
- * \li AICompany::GetQuarterlyIncome
- * \li AICompany::GetQuarterlyExpenses
- * \li AICompany::GetQuarterlyCargoDelivered
- * \li AICompany::GetQuarterlyPerformanceRating
- * \li AICompany::GetQuarterlyCompanyValue
- * \li AIController::GetOpsTillSuspend
- * \li AIInfo::CONFIG_DEVELOPER
- * \li AIOrder::GetOrderRefit
- * \li AIOrder::IsRefitOrder
- * \li AIOrder::SetOrderRefit
- * \li AITown::GetCargoGoal
- * \li AITown::GetGrowthRate
- * \li AITown::GetLastMonthReceived
- * \li AITown::GetTownAuthority
- * \li AITownEffectList (to walk over all available town effects)
- * \li AIVehicle::ERR_VEHICLE_TOO_LONG in case vehicle length limit is reached
- *
- * API renames:
- * \li AITown::GetLastMonthTransported to AITown::GetLastMonthSupplied to better
- * reflect what it does.
- * \li AIInfo has all its configure settings renamed from AICONFIG to just CONFIG
- * like CONFIG_RANDOM.
- *
- * API removals:
- * \li AICompany::GetCompanyValue, use AICompany::GetQuarterlyCompanyValue instead.
- *
- * Other changes:
- * \li AITown::GetLastMonthProduction no longer has prerequisites based on town
- * effects.
- * \li AITown::GetLastMonthTransported no longer has prerequisites based on
- * town effects.
- * \li AITown::GetLastMonthTransportedPercentage no longer has prerequisites
- * based on town effects.
- *
- * \b 1.1.2
- *
- * No changes
- *
- * \b 1.1.1
- *
- * No changes
- *
- * \b 1.1.0
- *
- * API additions:
- * \li IsEnd for all lists.
- * \li AIEventTownFounded
- * \li AIIndustry::GetIndustryID
- * \li AIIndustryType::INDUSTRYTYPE_TOWN
- * \li AIIndustryType::INDUSTRYTYPE_UNKNOWN
- * \li AIOrder::IsVoidOrder
- * \li AIRail::GetName
- * \li AITown::IsCity
- *
- * API removals:
- * \li HasNext for all lists.
- * \li AIAbstractList, use AIList instead.
- * \li AIList::ChangeItem, use AIList::SetValue instead.
- * \li AIRail::ERR_NONUNIFORM_STATIONS_DISABLED, that error is never returned anymore.
- *
- * Other changes:
- * \li AIEngine::GetMaxTractiveEffort can be used for road vehicles.
- * \li AIEngine::GetPower can be used for road vehicles.
- * \li AIEngine::GetWeight can be used for road vehicles.
- * \li AIIndustry::IsCargoAccepted now returns CargoAcceptState instead of a boolean.
- * \li AIOrder::GetOrderFlags returns AIOrder::AIOF_INVALID for void orders as well.
- * \li AIRoad::BuildDriveThroughRoadStation now allows overbuilding.
- * \li AIRoad::BuildRoadStation now allows overbuilding.
- *
- * \b 1.0.5
- *
- * No changes
- *
- * \b 1.0.4
- *
- * No changes
- *
- * \b 1.0.3
- *
- * API additions:
- * \li AIRail::ERR_RAILTYPE_DISALLOWS_CROSSING
- *
- * \b 1.0.2
- *
- * Other changes:
- * \li AIBridge::GetPrice now returns the price of the bridge without the cost for the rail or road.
- *
- * \b 1.0.1
- *
- * API additions:
- * \li AIRail::GetMaxSpeed
- *
- * \b 1.0.0
- *
- * API additions:
- * \li AIBaseStation
- * \li AIEngine::IsBuildable
- * \li AIEventCompanyAskMerger
- * \li AIIndustry::GetLastMonthTransportedPercentage
- * \li AIInfo::AICONFIG_INGAME
- * \li AIMarine::GetBuildCost
- * \li AIOrder::AIOF_GOTO_NEAREST_DEPOT
- * \li AIOrder::GetStopLocation
- * \li AIOrder::SetStopLocation
- * \li AIRail::RemoveRailStationTileRectangle
- * \li AIRail::RemoveRailWaypointTileRectangle
- * \li AIRail::GetBuildCost
- * \li AIRoad::GetBuildCost
- * \li AISubsidy::SubsidyParticipantType
- * \li AISubsidy::GetSourceType
- * \li AISubsidy::GetSourceIndex
- * \li AISubsidy::GetDestinationType
- * \li AISubsidy::GetDestinationIndex
- * \li AITile::GetBuildCost
- * \li AITown::GetLastMonthTransportedPercentage
- * \li AIVehicleList_Depot
- * \li AIWaypoint::WaypointType
- * \li AIWaypoint::HasWaypointType
- * \li Some error messages to AIWaypoint
- *
- * API removals:
- * \li AIOrder::ChangeOrder, use AIOrder::SetOrderFlags instead
- * \li AIRail::RemoveRailStationTileRect, use AIRail::RemoveRailStationTileRectangle instead
- * \li AIRail::RemoveRailWaypoint, use AIRail::RemoveRailWaypointTileRectangle instead
- * \li AISign::GetMaxSignID, use AISignList instead
- * \li AIStation::ERR_STATION_TOO_LARGE, use AIError::ERR_STATION_TOO_SPREAD_OUT instead
- * \li AISubsidy::SourceIsTown, use AISubsidy::GetSourceType instead
- * \li AISubsidy::GetSource, use AISubsidy::GetSourceIndex instead
- * \li AISubsidy::DestinationIsTown, use AISubsidy::GetDestinationType instead
- * \li AISubsidy::GetDestination, use AISubsidy::GetDestinationIndex instead
- * \li AITile::GetHeight, use AITile::GetMinHeight/GetMaxHeight/GetCornerHeight instead
- * \li AITown::GetMaxProduction, use AITown::GetLastMonthProduction instead
- * \li AIVehicle::SkipToVehicleOrder, use AIOrder::SkipToOrder instead
- * \li AIWaypoint::WAYPOINT_INVALID, use AIBaseStation::STATION_INVALID instead
- *
- * Other changes:
- * \li The GetName / SetName / GetLocation functions were moved from AIStation
- * and AIWaypoint to AIBaseStation, but you can still use AIStation.GetName
- * as before
- * \li The GetConstructionDate function was moved from AIStation to
- * AIBaseStation, but can still be used as AIStation.GetConstructionDate
- * \li WaypointID was replaced by StationID. All WaypointIDs from previous
- * savegames are invalid. Use STATION_INVALID instead of WAYPOINT_INVALID
- * \li AIWaypointList constructor now needs a WaypointType similiar to AIStationList,
- * it can also handle buoys.
- * \li AIVehicleList_Station now also works for waypoints
- * \li Stations can be build over rail without signals that is in the right
- * direction for the to-be built station. It will also convert the rail if
- * the station's rail type supports the old type.
- * \li GetAPIVersion() was added as function to info.nut. If it does not exist
- * API version 0.7 is assumed. This function should return the major and
- * minor number of the stable version of the API the AI is written against.
- * For 0.7.2 that would be 0.7, for 1.1.3 it would be 1.1, etc.
- * \li The subsidy logic has changed. Subsidy is now awarded when cargo
- * originating from subsidy source is delivered to station that has subsidy
- * destination it its catchment area. One industry tile or one town house
- * is enough as long as station accepts the cargo. Awarded subsidies are no
- * longer bound to stations used for first delivery, any station can be
- * used for loading and unloading as long as cargo is transfered from
- * source to destination.
- * \li Make AIEngine:CanRefitCargo() not report refittability to mail by
- * default for aircraft. It is not necessarily true. This means that even
- * if the aircraft can carry mail (as secondary cargo) it does not return
- * true if the aircraft cannot carry it as its only cargo.
- * \li Improve behaviour of AIEngine::GetCargoType(), AIEventEnginePreview::GetCargoType()
- * and AIEngine::CanRefitCargo() for articulated vehicles. For
- * CanRefitCargo true is returned if at least one part can be refitted.
- * For GetCargoType the first most used cargo type is returned.
- * \li AIIndustryType::GetConstructionCost() now returns -1 if the industry is
- * neither buildable nor prospectable.
- * \li AIEngine::IsValidEngine will now return true if you have at least one
- * vehicle of that type in your company, regardless if it's still buildable
- * or not. AIEngine::IsBuildable returns only true when you can actually
- * build an engine.
- * \li AITile::GetCargoProduction will now return the number of producers,
- * including houses instead the number of producing tiles. This means that
- * also industries that do not have a tile within the radius, but where
- * the search bounding box and the industry's bounding box intersect, are
- * counted. Previously these industries (and their cargos), although they
- * produced cargo for a station at the given location, were not returned.
- * \li AIRail::BuildRail will now fail completely if there is an obstacle
- * between the begin and end, instead of building up to the obstacle and
- * returning that everything went okay.
- * \li Orders for buoys are now waypoint orders, i.e. instead of using the
- * station orders for buoys one has to use waypoint orders.
- * \li Autoreplaces can now also be set for the default group via AIGroup.
- *
- * \b 0.7.5
- *
- * No changes
- *
- * \b 0.7.4
- *
- * No changes
- *
- * \b 0.7.3
- *
- * API additions:
- * \li AIAbstractList::SORT_ASCENDING
- * \li AIAbstractList::SORT_DESCENDING
- * \li AIAirport::IsAirportInformationAvailable
- * \li AICompany::GetPresidentGender
- * \li AICompany::SetPresidentGender
- * \li AIEngine::GetDesignDate
- * \li AIStation::GetConstructionDate
- *
- * Other changes:
- * \li AIs are now killed when they execute a DoCommand or Sleep at a time
- * they are not allowed to do so.
- * \li When the API requests a string as parameter you can give every squirrel
- * type and it will be converted to a string
- * \li AIs can create subclasses of API classes and use API constants as part
- * of their own constants
- *
- * \b 0.7.2
- *
- * API additions:
- * \li AIVehicle::GetReliability
- *
- * Other changes:
- * \li DoCommands and sleeps in call, acall, pcall and valuators are disallowed
- *
- * \b 0.7.1
- *
- * API additions:
- * \li AIAirport::GetPrice
- * \li AIController::GetVersion
- * \li AIOrder::AIOF_DEPOT_FLAGS
- * \li AIOrder::AIOF_STOP_IN_DEPOT
- * \li AIOrder::IsCurrentOrderPartOfOrderList
- * \li AIOrder::IsGotoDepotOrder
- * \li AIOrder::IsGotoStationOrder
- * \li AIOrder::IsGotoWaypointOrder
- * \li AISignList
- * \li AITile::CORNER_[WSEN]
- * \li AITile::ERR_AREA_ALREADY_FLAT
- * \li AITile::ERR_EXCAVATION_WOULD_DAMAGE
- * \li AITile::GetCornerHeight
- * \li AITile::GetMaxHeight
- * \li AITile::GetMinHeight
- * \li AIVehicle::SendVehicleToDepotForServicing
- *
- * Other changes:
- * \li GetURL() was added as optional function to info.nut
- * \li UseAsRandomAI() was added as optional function to info.nut
- * \li A limit was introduced on the time the AI spends in the constructor and Load function
- *
- * \b 0.7.0
- * \li First stable release with the NoAI framework.
- */
diff --git a/src/ai/api/ai_info_docs.hpp b/src/ai/api/ai_info_docs.hpp
deleted file mode 100644
index 1f8f8b1fb..000000000
--- a/src/ai/api/ai_info_docs.hpp
+++ /dev/null
@@ -1,243 +0,0 @@
-/* $Id$ */
-
-/*
- * This file is part of OpenTTD.
- * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
- * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
- * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
- */
-
-/** @file ai_info_docs.hpp Description of the functions an AI can/must provide in AIInfo. */
-
-/* This file exists purely for doxygen purposes. */
-
-/**
- * 'Abstract' class of the class AIs/AI libraries use to register themselves.
- *
- * @note This class is not part of the API. It is purely to document what
- * AIs must or can implemented to provide information to OpenTTD to
- * base configuring/starting/loading the AI on.
- *
- * @note The required functions are also needed for AI Libraries. As such
- * the information here can be used for libraries, but the information
- * will not be shown in the GUI except for error/debug messages.
- */
-class AIInfo {
-public:
- /**
- * Gets the author name to be shown in the 'Available AIs' window.
- *
- * @return The author name of the AI.
- * @note This function is required.
- */
- string GetAuthor();
-
- /**
- * Gets the AIs name. This is shown in the 'Available AIs' window
- * and at all other places where the AI is mentioned, like the debug
- * window or OpenTTD's help message. The name is used to uniquely
- * identify an AI within OpenTTD and this name is used in savegames
- * and the configuration file.
- *
- * @return The name of the AI.
- * @note This function is required.
- */
- string GetName();
-
- /**
- * Gets a 4 ASCII character short name of the AI to uniquely
- * identify it from other AIs. The short name is primarily
- * used as unique identifier for the content system.
- * The content system uses besides the short name also the
- * MD5 checksum of all the source files to uniquely identify
- * a specific version of the AI.
- *
- * The short name must consist of precisely four ASCII
- * characters, or more precisely four non-zero bytes.
- *
- * @return The name of the AI.
- * @note This function is required.
- */
- string GetShortName();
-
- /**
- * Gets the description to be shown in the 'Available AIs' window.
- *
- * @return The description for the AI.
- * @note This function is required.
- */
- string GetDescription();
-
- /**
- * Gets the version of the AI. This is a number to (in theory)
- * uniquely identify the versions of an AI. Generally the
- * 'instance' of an AI with the highest version is chosen to
- * be loaded.
- *
- * When OpenTTD finds, during starting, a duplicate AI with the
- * same version number one is randomly chosen. So it is
- * important that this number is regularly updated/incremented.
- *
- * @return The version number of the AI.
- * @note This function is required.
- */
- int GetVersion();
-
- /**
- * Gets the lowest version of the AI that OpenTTD can still load
- * the savegame of. In other words, from which version until this
- * version can the AI load the savegames.
- *
- * If this function does not exist OpenTTD assumes it can only
- * load savegames of this version. As such it will not upgrade
- * to this version upon load.
- *
- * @return The lowest version number we load the savegame data.
- * @note This function is optional.
- */
- int MinVersionToLoad();
-
- /**
- * Gets the development/release date of the AI.
- *
- * The intention of this is to give the user an idea how old the
- * AI is and whether there might be a newer version.
- *
- * @return The development/release date for the AI.
- * @note This function is required.
- */
- string GetDate();
-
- /**
- * Can this AI be used as random AI?
- *
- * The idea behind this function is to 'forbid' highly
- * competitive or other special AIs from running in games unless
- * the user explicitly selects the AI to be loaded. This to
- * try to prevent users from complaining that the AI is too
- * aggressive or does not build profitable routes.
- *
- * If this function does not exist OpenTTD assumes the AI can
- * be used as random AI. As such it will be randomly chosen.
- *
- * @return True if the AI can be used as random AI.
- * @note This function is optional.
- */
- bool UseAsRandomAI();
-
- /**
- * Gets the name of main class of the AI so OpenTTD knows
- * what class to instantiate.
- *
- * @return The class name of the AI.
- * @note This function is required.
- */
- string CreateInstance();
-
- /**
- * Gets the API version this AI is written for. If this function
- * does not exist API compatability with version 0.7 is assumed.
- * If the function returns something OpenTTD does not understand,
- * for example a newer version or a string that is not a version,
- * the AI will not be loaded.
- *
- * Although in the future we might need to make a separate
- * compatability 'wrapper' for a specific version of OpenTTD, for
- * example '0.7.1', we will use only the major and minor number
- * and not the bugfix number as valid return for this function.
- *
- * Valid return values are:
- * - "0.7"
- * - "1.0"
- * - "1.1"
- * - "1.2"
- *
- * @return The version this AI is compatible with.
- * @note This function is optional.
- */
- string GetAPIVersion();
-
- /**
- * Gets the URL to be shown in the 'this AI has crashed' message
- * and in the 'Available AIs' window. If this function does not
- * exist no URL will be shown.
- *
- * This function purely exists to redirect users of the AI to the
- * right place on the internet to discuss the AI and report bugs
- * of this AI.
- *
- * @return The URL to show.
- * @note This function is optional.
- */
- string GetURL();
-
- /**
- * Gets the settings that OpenTTD shows in the "AI Parameters" window
- * so the user can customize the AI. This is a special function that
- * doesn't need to return anything. Instead you can call AddSetting
- * and AddLabels here.
- *
- * @note This function is optional.
- */
- void GetSettings();
-
- /** Miscellaneous flags for AI settings. */
- enum AIConfigFlags {
- AICONFIG_NONE, ///< Normal setting.
- AICONFIG_RANDOM, ///< When randomizing the AI, pick any value between min_value and max_value.
- AICONFIG_BOOLEAN, ///< This value is a boolean (either 0 (false) or 1 (true) ).
- AICONFIG_INGAME, ///< This setting can be changed while the AI is running.
- AICONFIG_AI_DEVELOPER, ///< This setting will only be visible when the ai development tools are active.
- };
-
- /**
- * Add a user configurable setting for this AI. You can call this
- * as many times as you have settings.
- * @param setting_description A table with all information about a
- * single setting. The table should have the following name/value pairs:
- * - name The name of the setting, this is used in openttd.cfg to
- * store the current configuration of AIs. Required.
- * - description A single line describing the setting. Required.
- * - min_value The minimum value of this setting. Required for integer
- * settings and not allowed for boolean settings.
- * - max_value The maximum value of this setting. Required for integer
- * settings and not allowed for boolean settings.
- * - easy_value The default value if the easy difficulty level
- * is selected. Required.
- * - medium_value The default value if the medium difficulty level
- * is selected. Required.
- * - hard_value The default value if the hard difficulty level
- * is selected. Required.
- * - custom_value The default value if the custom difficulty level
- * is selected. Required.
- * - random_deviation If this property has a nonzero value, then the
- * actual value of the setting in game will be
- * user_configured_value + random(-random_deviation, random_deviation).
- * Not allowed if the AICONFIG_RANDOM flag is set, otherwise optional.
- * - step_size The increase/decrease of the value every time the user
- * clicks one of the up/down arrow buttons. Optional, default is 1.
- * - flags Bitmask of some flags, see AIConfigFlags. Required.
- *
- * @note This is a function provided by OpenTTD, you don't have to
- * include it in your AI but should just call it from GetSettings.
- */
- void AddSetting(table setting_description);
-
- /**
- * Add labels for the values of a setting. Instead of a number the
- * user will see the corresponding name.
- * @param setting_name The name of the setting.
- * @param value_names A table that maps values to names. The first
- * character of every identifier is ignored and the rest should
- * be the an integer of the value you define a name for. The value
- * is a short description of that value.
- * To define labels for a setting named "competition_level" you could
- * for example call it like this:
- * AddLabels("competition_level", {_0 = "no competition", _1 = "some competition",
- * _2 = "a lot of competition"});
- *
- * @note This is a function provided by OpenTTD, you don't have to
- * include it in your AI but should just call it from GetSettings.
- */
- void AddLabels(const char *setting_name, table value_names);
-};