summaryrefslogtreecommitdiff
path: root/src/script/api
diff options
context:
space:
mode:
Diffstat (limited to 'src/script/api')
-rw-r--r--src/script/api/Doxyfile_AI250
-rw-r--r--src/script/api/ai_changelog.hpp277
-rw-r--r--src/script/api/doxygen_filter.awk285
-rw-r--r--src/script/api/doxygen_filter.sh27
-rw-r--r--src/script/api/script_info_docs.hpp247
5 files changed, 1086 insertions, 0 deletions
diff --git a/src/script/api/Doxyfile_AI b/src/script/api/Doxyfile_AI
new file mode 100644
index 000000000..04c56db3a
--- /dev/null
+++ b/src/script/api/Doxyfile_AI
@@ -0,0 +1,250 @@
+# $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 = script_*.hpp \
+ ai_*.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 = "./doxygen_filter.sh AI"
+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_noai.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/script/api/ai_changelog.hpp b/src/script/api/ai_changelog.hpp
new file mode 100644
index 000000000..99d892497
--- /dev/null
+++ b/src/script/api/ai_changelog.hpp
@@ -0,0 +1,277 @@
+/* $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/script/api/doxygen_filter.awk b/src/script/api/doxygen_filter.awk
new file mode 100644
index 000000000..e15c8da39
--- /dev/null
+++ b/src/script/api/doxygen_filter.awk
@@ -0,0 +1,285 @@
+# $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/>.
+
+#
+# Awk script to automatically generate the code needed
+# to export the script APIs to Squirrel.
+#
+# Note that arrays are 1 based...
+#
+
+
+BEGIN {
+ cls = ""
+ api_selected = ""
+ cls_in_api = ""
+ cls_level = 0
+ skip_function_body = "false"
+ skip_function_par = 0
+ RS = "\r|\n"
+}
+
+{
+ gsub(/Script/, api)
+}
+
+{
+ if (skip_function_body == "true") {
+ input = $0
+ gsub(/[^{]/, "", input)
+ skip_function_par += length(input)
+ if (skip_function_par > 0) {
+ input = $0
+ gsub(/[^}]/, "", input)
+ skip_function_par -= length(input)
+ if (skip_function_par == 0) skip_function_body = "false"
+ }
+ }
+ if (skip_function_body == "true") next
+}
+
+/@file/ {
+ gsub(/script/, tolower(api))
+}
+
+/^([ ]*)\* @api/ {
+ if (api == "Script") {
+ api_selected = "true"
+ next
+ }
+
+ # By default, classes are not selected
+ if (cls_level == 0) api_selected = "false"
+
+ gsub("^([ ]*)", "", $0)
+ gsub("* @api ", "", $0)
+
+ if ($0 == "none") {
+ api_selected = "false"
+ } else if ($0 == "-all") {
+ api_selected = "false"
+ } else if (match($0, "-" tolower(api))) {
+ api_selected = "false"
+ } else if (match($0, tolower(api))) {
+ api_selected = "true"
+ }
+
+ next
+}
+
+# Ignore forward declarations of classes
+/^( *)class(.*);/ { next; }
+# We only want to have public functions exported for now
+/^( *)class/ {
+ if (cls_level == 0) {
+ if (api_selected == "") {
+ print "Class '"$2"' has no @api. It won't be published to any API." > "/dev/stderr"
+ api_selected = "false"
+ }
+ public = "false"
+ cls_param[0] = ""
+ cls_param[1] = 1
+ cls_param[2] = "x"
+ cls_in_api = api_selected
+ api_selected = ""
+ cls = $2
+
+ if (cls_in_api == "true") {
+ print comment_buffer
+ print
+ print "public:"
+ comment_buffer = ""
+ }
+ } else if (cls_level == 1) {
+ if (api_selected == "") api_selected = cls_in_api
+
+ if (api_selected == "true") {
+ print comment_buffer
+ print
+ print "public:"
+ comment_buffer = ""
+ }
+ api_selected = ""
+ } else {
+ print "Classes nested too deep" > "/dev/stderr"
+ exit 1
+ }
+ cls_level++
+ next
+}
+/^( *)public/ { if (cls_level == 1) comment_buffer = ""; public = "true"; next; }
+/^( *)protected/ { if (cls_level == 1) comment_buffer = ""; public = "false"; next; }
+/^( *)private/ { if (cls_level == 1) comment_buffer = ""; public = "false"; next; }
+
+# Ignore special doxygen blocks
+/^#ifndef DOXYGEN_API/ { doxygen_skip = "next"; next; }
+/^#ifdef DOXYGEN_API/ { doxygen_skip = "true"; next; }
+/^#endif \/\* DOXYGEN_API \*\// { doxygen_skip = "false"; next; }
+/^#else/ {
+ if (doxygen_skip == "next") {
+ doxygen_skip = "true";
+ } else {
+ doxygen_skip = "false";
+ }
+ next;
+}
+{ if (doxygen_skip == "true") next }
+
+/^#/ {
+ next
+}
+
+# Store comments
+/\/\*\*.*\*\// { comment_buffer = $0; comment = "false"; next; }
+/\/\*.*\*\// { comment_buffer = ""; comment = "false"; next; }
+/\/\*\*/ { comment_buffer = $0 "\n"; comment = "true"; next; }
+/\/\*/ { comment_buffer = ""; comment = "false"; next; }
+/\*\// { comment_buffer = comment_buffer $0; comment = "false"; next; }
+{
+ if (comment == "true" && !match($0, /@api/))
+ {
+ comment_buffer = comment_buffer $0 "\n"; next;
+ }
+}
+
+
+# We need to make specialized conversions for structs
+/^( *)struct/ {
+ comments_so_far = comment_buffer
+ comment_buffer = ""
+ cls_level++
+
+ # Check if we want to publish this struct
+ if (api_selected == "") api_selected = cls_in_api
+ if (api_selected == "false") {
+ api_selected = ""
+ next
+ }
+ api_selected = ""
+
+ if (public == "false") next
+
+ print comments_so_far
+ print $0
+
+ next
+}
+
+# We need to make specialized conversions for enums
+/^( *)enum/ {
+ comments_so_far = comment_buffer
+ comment_buffer = ""
+ cls_level++
+
+ # Check if we want to publish this enum
+ if (api_selected == "") api_selected = cls_in_api
+ if (api_selected == "false") {
+ api_selected = ""
+ next
+ }
+ api_selected = ""
+
+ if (public == "false") next
+
+ in_enum = "true"
+
+ print comments_so_far
+ print $0
+
+ next
+}
+
+# Maybe the end of the class, if so we can start with the Squirrel export pretty soon
+/};/ {
+ comment_buffer = ""
+ cls_level--
+ if (cls_level != 0) {
+ if (in_enum == "true") print
+ in_enum = "false"
+ next
+ }
+ if (cls == "") {
+ next
+ }
+ if (cls_in_api == "true") print
+ next;
+}
+
+# Empty/white lines
+/^([ ]*)$/ {
+ print $0
+
+ next
+}
+
+# Skip non-public functions
+{ if (public == "false") next }
+
+# Add enums
+{
+ if (in_enum == "true") {
+ print comment_buffer
+ comment_buffer = ""
+ print $0
+
+ # Check if this a special error enum
+ if (match(enums[enum_size], ".*::ErrorMessages") != 0) {
+ # syntax:
+ # enum ErrorMessages {
+ # ERR_SOME_ERROR, // [STR_ITEM1, STR_ITEM2, ...]
+ # }
+
+ ##TODO: don't print the STR_*
+ }
+ next
+ }
+}
+
+# Add a const (non-enum) value
+/^[ ]*static const \w+ \w+ = -?\(?\w*\)?\w+;/ {
+ if (api_selected == "") api_selected = cls_in_api
+ if (api_selected == "false") {
+ api_selected = ""
+ comment_buffer = ""
+ next
+ }
+ print comment_buffer
+ print $0
+ comment_buffer = ""
+ next
+}
+
+# Add a method to the list
+/^.*\(.*\).*$/ {
+ if (cls_level != 1) next
+ if (!match($0, ";")) {
+ gsub(/ :$/, ";")
+ skip_function_body = "true"
+ }
+ if (match($0, "~")) {
+ if (api_selected != "") {
+ print "Destructor for '"cls"' has @api. Tag ignored." > "/dev/stderr"
+ api_selected = ""
+ }
+ next
+ }
+
+ # Check if we want to publish this function
+ if (api_selected == "") api_selected = cls_in_api
+ if (api_selected == "false") {
+ api_selected = ""
+ comment_buffer = ""
+ next
+ }
+ api_selected = ""
+
+ print comment_buffer
+ print $0
+ comment_buffer = ""
+
+ next
+}
diff --git a/src/script/api/doxygen_filter.sh b/src/script/api/doxygen_filter.sh
new file mode 100644
index 000000000..fd8fca98b
--- /dev/null
+++ b/src/script/api/doxygen_filter.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# $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/>.
+
+# Set neutral locale so sort behaves the same everywhere
+LC_ALL=C
+export LC_ALL
+
+# We really need gawk for this!
+AWK=gawk
+
+${AWK} --version > /dev/null 2> /dev/null
+if [ "$?" != "0" ]; then
+ echo "This script needs gawk to run properly"
+ exit 1
+fi
+
+case $2 in
+ *ai_changelog.hpp) cat $2; exit 0;;
+esac
+
+${AWK} -v api=$1 -f doxygen_filter.awk $2
diff --git a/src/script/api/script_info_docs.hpp b/src/script/api/script_info_docs.hpp
new file mode 100644
index 000000000..28f2b53f0
--- /dev/null
+++ b/src/script/api/script_info_docs.hpp
@@ -0,0 +1,247 @@
+/* $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 script_info_docs.hpp Description of the functions an Script can/must provide in ScriptInfo. */
+
+/* This file exists purely for doxygen purposes. */
+
+/**
+ * 'Abstract' class of the Scripts use to register themselves.
+ *
+ * @note This class is not part of the API. It is purely to document what
+ * Scripts must or can implemented to provide information to OpenTTD to
+ * base configuring/starting/loading the Script on.
+ *
+ * @note The required functions are also needed for Script 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.
+ *
+ * @api ai
+ */
+class ScriptInfo {
+public:
+ /**
+ * Gets the author name to be shown in the 'Available Scripts' window.
+ *
+ * @return The author name of the Script.
+ * @note This function is required.
+ */
+ string GetAuthor();
+
+ /**
+ * Gets the Scripts name. This is shown in the 'Available Scripts' window
+ * and at all other places where the Script is mentioned, like the debug
+ * window or OpenTTD's help message. The name is used to uniquely
+ * identify an Script within OpenTTD and this name is used in savegames
+ * and the configuration file.
+ *
+ * @return The name of the Script.
+ * @note This function is required.
+ */
+ string GetName();
+
+ /**
+ * Gets a 4 ASCII character short name of the Script to uniquely
+ * identify it from other Scripts. 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 Script.
+ *
+ * The short name must consist of precisely four ASCII
+ * characters, or more precisely four non-zero bytes.
+ *
+ * @return The name of the Script.
+ * @note This function is required.
+ */
+ string GetShortName();
+
+ /**
+ * Gets the description to be shown in the 'Available Scripts' window.
+ *
+ * @return The description for the Script.
+ * @note This function is required.
+ */
+ string GetDescription();
+
+ /**
+ * Gets the version of the Script. This is a number to (in theory)
+ * uniquely identify the versions of an Script. Generally the
+ * 'instance' of an Script with the highest version is chosen to
+ * be loaded.
+ *
+ * When OpenTTD finds, during starting, a duplicate Script 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 Script.
+ * @note This function is required.
+ */
+ int GetVersion();
+
+ /**
+ * Gets the lowest version of the Script that OpenTTD can still load
+ * the savegame of. In other words, from which version until this
+ * version can the Script 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 Script.
+ *
+ * The intention of this is to give the user an idea how old the
+ * Script is and whether there might be a newer version.
+ *
+ * @return The development/release date for the Script.
+ * @note This function is required.
+ */
+ string GetDate();
+
+ /**
+ * Can this Script be used as random Script?
+ *
+ * The idea behind this function is to 'forbid' highly
+ * competitive or other special Scripts from running in games unless
+ * the user explicitly selects the Script to be loaded. This to
+ * try to prevent users from complaining that the Script is too
+ * aggressive or does not build profitable routes.
+ *
+ * If this function does not exist OpenTTD assumes the Script can
+ * be used as random Script. As such it will be randomly chosen.
+ *
+ * @return True if the Script can be used as random Script.
+ * @note This function is optional.
+ *
+ * @api -game
+ */
+ bool UseAsRandomAI();
+
+ /**
+ * Gets the name of main class of the Script so OpenTTD knows
+ * what class to instantiate.
+ *
+ * @return The class name of the Script.
+ * @note This function is required.
+ */
+ string CreateInstance();
+
+ /**
+ * Gets the API version this Script 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 Script 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 Script is compatible with.
+ * @note This function is optional.
+ */
+ string GetAPIVersion();
+
+ /**
+ * Gets the URL to be shown in the 'this Script has crashed' message
+ * and in the 'Available Scripts' window. If this function does not
+ * exist no URL will be shown.
+ *
+ * This function purely exists to redirect users of the Script to the
+ * right place on the internet to discuss the Script and report bugs
+ * of this Script.
+ *
+ * @return The URL to show.
+ * @note This function is optional.
+ */
+ string GetURL();
+
+ /**
+ * Gets the settings that OpenTTD shows in the "Script Parameters" window
+ * so the user can customize the Script. 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 Script settings. */
+ enum ScriptConfigFlags {
+ CONFIG_NONE, ///< Normal setting.
+ CONFIG_RANDOM, ///< When randomizing the Script, pick any value between min_value and max_value.
+ CONFIG_BOOLEAN, ///< This value is a boolean (either 0 (false) or 1 (true) ).
+ CONFIG_INGAME, ///< This setting can be changed while the Script is running.
+ CONFIG_DEVELOPER, ///< This setting will only be visible when the Script development tools are active.
+ };
+
+ /**
+ * Add a user configurable setting for this Script. 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 Scripts. 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 CONFIG_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 ScriptConfigFlags. Required.
+ *
+ * @note This is a function provided by OpenTTD, you don't have to
+ * include it in your Script 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 Script but should just call it from GetSettings.
+ */
+ void AddLabels(const char *setting_name, table value_names);
+};
generated by cgit v1.2.3-70-g09d2 (git 2.47.1) at 2024-12-24 05:02:47 +0000