From cf12bafb09c8e06fb288db9832387bf9b5ed9cc8 Mon Sep 17 00:00:00 2001 From: Petr Ohlidal Date: Sat, 26 Feb 2022 23:23:39 +0100 Subject: [PATCH] :angel: Added doc for callbacks and races. The angelscript documentation is now divided into 3 pseudo-modules: Game-to-script ^AngelScript^ Documents script functions (callbacks) invoked by the game. Script-to-game ^AngelScript^ Documents game functions which scripts can invoke to control it. Script-to-script ^AngelScript^ Documents built-in scripts. --- .../Game2Script/script_callbacks.h | 39 +++++++++++++++++++ doc/angelscript/{ => Script2Game}/BeamClass.h | 16 +++++--- doc/angelscript/{ => Script2Game}/CVarClass.h | 14 ++++--- .../{ => Script2Game}/ConsoleClass.h | 16 +++++--- .../{ => Script2Game}/InputEngineClass.h | 16 +++++--- .../{ => Script2Game}/LocalStorage.h | 16 +++++--- doc/angelscript/{ => Script2Game}/VehicleAI.h | 15 ++++--- doc/angelscript/{ => Script2Game}/game.h | 17 +++++--- .../{ => Script2Game}/global_functions.h | 23 +++++------ .../{races.as => Script2Script/races.as.h} | 15 +++++++ doc/angelscript/ScriptSideAPIs.h | 30 ++++++++++++++ 11 files changed, 166 insertions(+), 51 deletions(-) create mode 100644 doc/angelscript/Game2Script/script_callbacks.h rename doc/angelscript/{ => Script2Game}/BeamClass.h (89%) rename doc/angelscript/{ => Script2Game}/CVarClass.h (84%) rename doc/angelscript/{ => Script2Game}/ConsoleClass.h (82%) rename doc/angelscript/{ => Script2Game}/InputEngineClass.h (81%) rename doc/angelscript/{ => Script2Game}/LocalStorage.h (90%) rename doc/angelscript/{ => Script2Game}/VehicleAI.h (91%) rename doc/angelscript/{ => Script2Game}/game.h (98%) rename doc/angelscript/{ => Script2Game}/global_functions.h (96%) rename doc/angelscript/{races.as => Script2Script/races.as.h} (96%) create mode 100644 doc/angelscript/ScriptSideAPIs.h diff --git a/doc/angelscript/Game2Script/script_callbacks.h b/doc/angelscript/Game2Script/script_callbacks.h new file mode 100644 index 0000000000..2fe7f730ee --- /dev/null +++ b/doc/angelscript/Game2Script/script_callbacks.h @@ -0,0 +1,39 @@ + +namespace Game2Script { + +/** \addtogroup ScriptSideAPIs + * @{ + */ + +/** \addtogroup Game2Script + * @{ + */ + +/** Required; Script setup function - invoked once when script is loaded. +* If not present, the game will report error and abandon the script. +*/ +void main(); + +/** Optional; Script update function - invoked once every rendered frame. +* @param dt Elapsed time (delta time) in seconds. +*/ +void frameStep(float dt); + +/** Optional; Invoked if a registered event is triggered, see Script2Game::game::registerForEvent. +* @param event Event code. +* @param param Event-specific parameter, see docs for the event codes. +*/ +void eventCallback(Script2Game::scriptEvents event, int param); + +/** Optional; Invoked when a vehicle touches an eventbox which has no custom handler function. +* @param trigger_type Unused, always 0. +* @param inst Unique ID of the terrain object instance which created the eventbox. +* @param box Name of the eventbox as defined by the terrain object's ODEF file. +* @param nodeid Number of the node which triggered the event, or -1 if not known. +*/ +void defaultEventCallback(int trigger_type, string inst, string box, int nodeid); + +/** @}*/ //addtogroup Game2Script +/** @}*/ //addtogroup ScriptSideAPIs + +} // namespace Game2Script \ No newline at end of file diff --git a/doc/angelscript/BeamClass.h b/doc/angelscript/Script2Game/BeamClass.h similarity index 89% rename from doc/angelscript/BeamClass.h rename to doc/angelscript/Script2Game/BeamClass.h index 0b04eed12e..c3b46f4126 100644 --- a/doc/angelscript/BeamClass.h +++ b/doc/angelscript/Script2Game/BeamClass.h @@ -1,8 +1,13 @@ -namespace ScriptAPI { -/** \addtogroup ScriptAPI +/** \addtogroup ScriptSideAPIs * @{ - */ + */ + +/** \addtogroup Script2Game + * @{ + */ + +namespace Script2Game { /** * @brief Binding of RoR::Actor; a softbody-physics gameplay object, can be anything from soda can to space shuttle. @@ -189,6 +194,7 @@ class BeamClass Ogre::Vector3 getNodePosition(int nodeNumber); } -/** @}*/ //addtogroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs -} //namespace ScriptAPI +} //namespace Script2Game diff --git a/doc/angelscript/CVarClass.h b/doc/angelscript/Script2Game/CVarClass.h similarity index 84% rename from doc/angelscript/CVarClass.h rename to doc/angelscript/Script2Game/CVarClass.h index 760ea0fff1..7c932e419a 100644 --- a/doc/angelscript/CVarClass.h +++ b/doc/angelscript/Script2Game/CVarClass.h @@ -1,10 +1,13 @@ +/** \addtogroup ScriptSideAPIs + * @{ + */ -namespace ScriptAPI { - -/** \addtogroup ScriptAPI +/** \addtogroup Script2Game * @{ */ + +namespace Script2Game { /** * @brief Types and special attributes of cvars. @@ -40,6 +43,7 @@ class CVarClass std::string const& getName() const { return m_name; } }; -/** @}*/ //addtogroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs -} //namespace ScriptAPI +} //namespace Script2Game diff --git a/doc/angelscript/ConsoleClass.h b/doc/angelscript/Script2Game/ConsoleClass.h similarity index 82% rename from doc/angelscript/ConsoleClass.h rename to doc/angelscript/Script2Game/ConsoleClass.h index 034dbffcdc..fc7b75d806 100644 --- a/doc/angelscript/ConsoleClass.h +++ b/doc/angelscript/Script2Game/ConsoleClass.h @@ -1,8 +1,13 @@ -namespace ScriptAPI { -/** \addtogroup ScriptAPI +/** \addtogroup ScriptSideAPIs * @{ - */ + */ + +/** \addtogroup Script2Game + * @{ + */ + +namespace Script2Game { /** * @brief Binding of RoR::Console; provides console variables (cvars), usually defined in RoR.cfg file. @@ -38,6 +43,7 @@ class ConsoleClass CVar* cVarGet(std::string const& input_name, int flags); }; -/** @}*/ //addtogroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs -} //namespace ScriptAPI +} //namespace Script2Game diff --git a/doc/angelscript/InputEngineClass.h b/doc/angelscript/Script2Game/InputEngineClass.h similarity index 81% rename from doc/angelscript/InputEngineClass.h rename to doc/angelscript/Script2Game/InputEngineClass.h index d4eee727d2..645ebc0f8b 100644 --- a/doc/angelscript/InputEngineClass.h +++ b/doc/angelscript/Script2Game/InputEngineClass.h @@ -1,10 +1,13 @@ +/** \addtogroup ScriptSideAPIs + * @{ + */ -namespace ScriptAPI { - -/** \addtogroup ScriptAPI +/** \addtogroup Script2Game * @{ - */ + */ + +namespace Script2Game { /** * @brief Binding of RoR::InputEngine; Manages input devices, their configuration (input.map ...) and state. @@ -36,8 +39,9 @@ class InputEngineClass }; -/** @}*/ //addtogroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs -} //namespace ScriptAPI +} //namespace Script2Game diff --git a/doc/angelscript/LocalStorage.h b/doc/angelscript/Script2Game/LocalStorage.h similarity index 90% rename from doc/angelscript/LocalStorage.h rename to doc/angelscript/Script2Game/LocalStorage.h index 372cb3821f..283a0ca2b7 100644 --- a/doc/angelscript/LocalStorage.h +++ b/doc/angelscript/Script2Game/LocalStorage.h @@ -1,10 +1,13 @@ +/** \addtogroup ScriptSideAPIs + * @{ + */ -namespace ScriptAPI { - -/** \addtogroup ScriptAPI +/** \addtogroup Script2Game * @{ - */ + */ + +namespace Script2Game { /** * @brief Binding of LocalStorage; A class that allows your script to store data persistently. @@ -114,6 +117,7 @@ class LocalStorage void changeSection(const string section); }; -/** @}*/ //addtogroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs -} //namespace ScriptAPI +} //namespace Script2Game diff --git a/doc/angelscript/VehicleAI.h b/doc/angelscript/Script2Game/VehicleAI.h similarity index 91% rename from doc/angelscript/VehicleAI.h rename to doc/angelscript/Script2Game/VehicleAI.h index c60be3027a..80da0e72a8 100644 --- a/doc/angelscript/VehicleAI.h +++ b/doc/angelscript/Script2Game/VehicleAI.h @@ -27,12 +27,16 @@ @date 03/2016 */ -namespace ScriptAPI { - -/** \addtogroup ScriptAPI +/** \addtogroup ScriptSideAPIs * @{ */ +/** \addtogroup Script2Game + * @{ + */ + +namespace Script2Game { + /** * Enum with AI events */ @@ -98,6 +102,7 @@ class VehicleAI } -/** @}*/ //addtogroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs -} //namespace ScriptAPI +} //namespace ScriptSideAPIs diff --git a/doc/angelscript/game.h b/doc/angelscript/Script2Game/game.h similarity index 98% rename from doc/angelscript/game.h rename to doc/angelscript/Script2Game/game.h index dcfcc8edb0..167bf8b591 100644 --- a/doc/angelscript/game.h +++ b/doc/angelscript/Script2Game/game.h @@ -17,11 +17,15 @@ along with Rigs of Rods. If not, see . */ // created on 23th May 2011 by neorej16 -namespace ScriptAPI { - -/** \addtogroup ScriptAPI +/** \addtogroup ScriptSideAPIs * @{ - */ + */ + +/** \addtogroup Script2Game + * @{ + */ + +namespace Script2Game { /** * @brief Binding of RoR::GameScript; A general class that will provide you with general functions. @@ -454,6 +458,7 @@ class game void quitGame(); }; -/** @}*/ //defgroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs -} //namespace ScriptAPI +} //namespace Script2Game diff --git a/doc/angelscript/global_functions.h b/doc/angelscript/Script2Game/global_functions.h similarity index 96% rename from doc/angelscript/global_functions.h rename to doc/angelscript/Script2Game/global_functions.h index f1a18a527a..e759e12501 100644 --- a/doc/angelscript/global_functions.h +++ b/doc/angelscript/Script2Game/global_functions.h @@ -17,19 +17,15 @@ along with Rigs of Rods. If not, see . */ // created on 25th May 2011. -/** @defgroup ScriptAPI Script-side API - * @brief This pseudo-module documents features available to scripts. - * Unless otherwise noted, any script (terrain, custom, future enhancements) can access these features. - * @warning This is a pseudo-module; it doesn't exist in codebase, only in this documentation. - */ - - /** \addtogroup ScriptAPI +/** \addtogroup ScriptSideAPIs * @{ - */ + */ + +/** \addtogroup Script2Game + * @{ + */ -/** @brief Pseudo-namespace; it doesn't exist in code or script runtime, only in this documentation. - */ -namespace ScriptAPI { +namespace Script2Game { /** * This is an alias for game.log(string message). @@ -420,6 +416,7 @@ enum truckStates { TS_DELETED, //!< special used when truck pointer is 0 }; -} //namespace ScriptAPI +} // namespace Script2Game -/** @}*/ //addtogroup ScriptAPI +/** @}*/ //addtogroup Script2Game +/** @}*/ //addtogroup ScriptSideAPIs diff --git a/doc/angelscript/races.as b/doc/angelscript/Script2Script/races.as.h similarity index 96% rename from doc/angelscript/races.as rename to doc/angelscript/Script2Script/races.as.h index 13fc83cb10..a0df5228fb 100644 --- a/doc/angelscript/races.as +++ b/doc/angelscript/Script2Script/races.as.h @@ -4,6 +4,16 @@ * @author neorej16 */ +namespace Script2Script { + +/** \addtogroup ScriptSideAPIs + * @{ + */ + +/** \addtogroup Script2Script + * @{ + */ + /** * A function signature for the callback pointers. * When you need to use a RACE_EVENT_CALLBACK as parameter, then @@ -560,3 +570,8 @@ class racesManager { */ void loadRace(int raceID); } + +/** @}*/ //addtogroup Script2Script +/** @}*/ //addtogroup ScriptSideAPIs + +} // namespace Script2Script diff --git a/doc/angelscript/ScriptSideAPIs.h b/doc/angelscript/ScriptSideAPIs.h new file mode 100644 index 0000000000..22469e3e83 --- /dev/null +++ b/doc/angelscript/ScriptSideAPIs.h @@ -0,0 +1,30 @@ + +/// @defgroup ScriptSideAPIs Script-side APIs +/// ^AngelScript^ All features provided to/offered by scripting. + +/// @defgroup Game2Script Game-to-script +/// ^AngelScript^ Documents script functions (callbacks) invoked by the game. +/// @{ + +/// @brief Pseudo-namespace; it doesn't exist in code or script runtime, only in this documentation. +namespace Game2Script {} + +/// @} + +/// @defgroup Script2Game Script-to-game +/// ^AngelScript^ Documents game functions which scripts can invoke to control it. +/// @{ + +/// @brief Pseudo-namespace; it doesn't exist in code or script runtime, only in this documentation. +namespace Script2Game {} + +/// @} + +/// @defgroup Script2Script Script-to-script +/// ^AngelScript^ Documents built-in scripts. +/// @{ + +/// @brief Pseudo-namespace; it doesn't exist in code or script runtime, only in this documentation. +namespace Script2Script {} + +/// @}