diff --git a/Moose Development/Moose/Core/Settings.lua b/Moose Development/Moose/Core/Settings.lua index d5feee499..36047beb4 100644 --- a/Moose Development/Moose/Core/Settings.lua +++ b/Moose Development/Moose/Core/Settings.lua @@ -3,27 +3,18 @@ -- ![Banner Image](..\Presentations\SETTINGS\Dia1.JPG) -- -- ==== --- --- # Demo Missions --- --- ### [SETTINGS Demo Missions source code]() --- --- ### [SETTINGS Demo Missions, only for beta testers]() --- --- ### [ALL Demo Missions pack of the last release](https://github.com/FlightControl-Master/MOOSE_MISSIONS/releases) --- --- ==== --- --- # YouTube Channel --- --- ### [SETTINGS YouTube Channel]() --- +-- +-- The documentation of the SETTINGS class can be found further in this document. +-- -- === -- --- ### Author: **Sven Van de Velde (FlightControl)** +-- # **AUTHORS and CONTRIBUTIONS** +-- -- ### Contributions: -- --- ==== +-- ### Authors: +-- +-- * **FlightControl**: Design & Programming -- -- @module Settings @@ -38,6 +29,142 @@ --- # SETTINGS class, extends @{Base#BASE} -- +-- ![Banner Image](..\Presentations\SETTINGS\Dia1.JPG) +-- +-- === +-- +-- The SETTINGS class takes care of various settings that influence the behaviour of certain functionalities and classes within the MOOSE framework. +-- SETTINGS can work on 2 levels: +-- +-- - **Default settings**: A running mission has **Default settings**. +-- - **Player settings**: For each player its own **Player settings** can be defined, overriding the **Default settings**. +-- +-- So, when there isn't any **Player setting** defined for a player for a specific setting, or, the player cannot be identified, the **Default setting** will be used instead. +-- +-- ## \_SETTINGS object +-- +-- MOOSE defines by default a singleton object called **\_SETTINGS**. Use this object to modify all the **Default settings** for a running mission. +-- For each player, MOOSE will automatically allocate also a **player settings** object, and will expose a radio menu to allow the player to adapt the settings to his own preferences. +-- +-- ## SETTINGS Menu +-- +-- Settings can be adapted by the Players and by the Mission Administrator through **radio menus, which are automatically available in the mission**. +-- These menus can be found **on level F10 under "Settings"**. There are two kinds of menus generated by the system. +-- +-- ### Default settings menu +-- +-- A menu is created automatically per Command Center that allows to modify the **Default** settings. +-- So, when joining a CC unit, a menu will be available that allows to change the settings parameters **FOR ALL THE PLAYERS**! +-- Note that the **Default settings** will only be used when a player has not choosen its own settings. +-- +-- ### Player settings menu +-- +-- A menu is created automatically per Player Slot (group) that allows to modify the **Player** settings. +-- So, when joining a slot, a menu wil be available that allows to change the settings parameters **FOR THE PLAYER ONLY**! +-- Note that when a player has not chosen a specific setting, the **Default settings** will be used. +-- +-- ### Switch off the setting menus +-- +-- Of course, it may be requried not to show any setting menus. In this case, a method is available on the **\_SETTINGS object**. +-- Use @{#SETTINGS.SetPlayerMenuOff}() to hide the player menus, and use @{#SETTINGS.SetPlayerMenuOn}() show the player menus. +-- Note that when this method is used, any player already in a slot will not have its menus visibility changed. +-- The option will only have effect when a player enters a new slot or changes a slot. +-- +-- Example: +-- +-- _SETTINGS:SetPlayerMenuOff() -- will disable the player menus. +-- _SETTINGS:SetPlayerMenuOn() -- will enable the player menus. +-- -- But only when a player exits and reenters the slot these settings will have effect! +-- +-- +-- +-- +-- ## Setting Types +-- +-- There are different settings that are managed and applied within the MOOSE framework. +-- See below a comprehensive description of each. +-- +-- ### **A2G coordinates** display formatting +-- +-- Will customize which display format is used to indicate A2G coordinates in text as part of the Command Center communications. +-- +-- - A2G BR: [Bearing Range](https://en.wikipedia.org/wiki/Bearing_(navigation)). +-- - A2G MGRS: The [Military Grid Reference System](https://en.wikipedia.org/wiki/Military_Grid_Reference_System). The accuracy can also be adapted. +-- - A2G LL DMS: Lattitude Longitude [Degrees Minutes Seconds](https://en.wikipedia.org/wiki/Geographic_coordinate_conversion). The accuracy can also be adapted. +-- - A2G LL DDM: Lattitude Longitude [Decimal Degrees Minutes](https://en.wikipedia.org/wiki/Decimal_degrees). The accuracy can also be adapted. +-- +-- The settings can be changed by using the **Default settings menu** on the Command Center or the **Player settings menu** on the Player Slot. +-- +-- There are different methods that can be used to change the **System settings** using the \_SETTINGS object. +-- +-- - @{#SETTINGS.SetA2G_BR}(): Enable the BR display formatting by default. +-- - @{#SETTINGS.SetA2G_MGRS}(): Enable the MGRS display formatting by default. Use @{SETTINGS.SetMGRS_Accuracy}() to adapt the accuracy of the MGRS formatting. +-- - @{#SETTINGS.SetA2G_LL_DMS}(): Enable the LL DMS display formatting by default. Use @{SETTINGS.SetLL_Accuracy}() to adapt the accuracy of the Seconds formatting. +-- - @{#SETTINGS.SetA2G_LL_DDM}(): Enable the LL DDM display formatting by default. Use @{SETTINGS.SetLL_Accuracy}() to adapt the accuracy of the Seconds formatting. +-- +-- One additional note on BR. In a situation when a BR coordinate should be given, +-- but there isn't any player context (no player unit to reference from), the MGRS formatting will be applied! +-- +-- ### **A2A coordinates** formatting +-- +-- Will customize which display format is used to indicate A2A coordinates in text as part of the Command Center communications. +-- +-- - A2A BRAA: [Bearing Range Altitude Aspect](https://en.wikipedia.org/wiki/Bearing_(navigation)). +-- - A2A MGRS: The [Military Grid Reference System](https://en.wikipedia.org/wiki/Military_Grid_Reference_System). The accuracy can also be adapted. +-- - A2A LL DMS: Lattitude Longitude [Degrees Minutes Seconds](https://en.wikipedia.org/wiki/Geographic_coordinate_conversion). The accuracy can also be adapted. +-- - A2A LL DDM: Lattitude Longitude [Decimal Degrees and Minutes](https://en.wikipedia.org/wiki/Decimal_degrees). The accuracy can also be adapted. +-- - A2A BULLS: [Bullseye](http://falcon4.wikidot.com/concepts:bullseye). +-- +-- The settings can be changed by using the **Default settings menu** on the Command Center or the **Player settings menu** on the Player Slot. +-- +-- There are different methods that can be used to change the **System settings** using the \_SETTINGS object. +-- +-- - @{#SETTINGS.SetA2A_BRAA}(): Enable the BR display formatting by default. +-- - @{#SETTINGS.SetA2A_MGRS}(): Enable the MGRS display formatting by default. Use @{SETTINGS.SetMGRS_Accuracy}() to adapt the accuracy of the MGRS formatting. +-- - @{#SETTINGS.SetA2A_LL_DMS}(): Enable the LL DMS display formatting by default. Use @{SETTINGS.SetLL_Accuracy}() to adapt the accuracy of the Seconds formatting. +-- - @{#SETTINGS.SetA2A_LL_DDM}(): Enable the LL DDM display formatting by default. Use @{SETTINGS.SetLL_Accuracy}() to adapt the accuracy of the Seconds formatting. +-- - @{#SETTINGS.SetA2A_BULLS}(): Enable the BULLSeye display formatting by default. +-- +-- One additional note on BRAA. In a situation when a BRAA coordinate should be given, +-- but there isn't any player context (no player unit to reference from), the MGRS formatting will be applied! +-- +-- ### **Measurements** formatting +-- +-- Will customize the measurements system being used as part as part of the Command Center communications. +-- +-- - **Metrics** system: Applies the [Metrics system](https://en.wikipedia.org/wiki/Metric_system) ... +-- - **Imperial** system: Applies the [Imperial system](https://en.wikipedia.org/wiki/Imperial_units) ... +-- +-- The settings can be changed by using the **Default settings menu** on the Command Center or the **Player settings menu** on the Player Slot. +-- +-- There are different methods that can be used to change the **Default settings** using the \_SETTINGS object. +-- +-- - @{#SETTINGS.SetMetric}(): Enable the Metric system. +-- - @{#SETTINGS.SetImperial}(): Enable the Imperial system. +-- +-- ### **Message** display times +-- +-- There are various **Message Types** that will influence the duration how long a message will appear as part of the Command Center communications. +-- +-- - **Update** message: A short update message. +-- - **Information** message: Provides new information **while** executing a mission. +-- - **Briefing** message: Provides a complete briefing **before** executing a mission. +-- - **Overview report**: Provides a short report overview, the summary of the report. +-- - **Detailed report**: Provides a complete report. +-- +-- The settings can be changed by using the **Default settings menu** on the Command Center or the **Player settings menu** on the Player Slot. +-- +-- Each Message Type has specific timings that will be applied when the message is displayed. +-- The Settings Menu will provide for each Message Type a selection of proposed durations from which can be choosen. +-- So the player can choose its own amount of seconds how long a message should be displayed of a certain type. +-- Note that **Update** messages can be chosen not to be displayed at all! +-- +-- There are different methods that can be used to change the **System settings** using the \_SETTINGS object. +-- +-- - @{#SETTINGS.SetMessageTime}(): Define for a specific @{Message.MESSAGE.MessageType} the duration to be displayed in seconds. +-- - @{#SETTINGS.GetMessageTime}(): Retrieves for a specific @{Message.MESSAGE.MessageType} the duration to be displayed in seconds. +-- +-- === -- @field #SETTINGS SETTINGS = { ClassName = "SETTINGS", @@ -412,16 +539,24 @@ do -- SETTINGS return self end - --- Sets the player menus on, so that they will show to the players. + --- Sets the player menus on, so that the **Player setting menus** show up for the players. + -- But only when a player exits and reenters the slot these settings will have effect! + -- It is advised to use this method at the start of the mission. -- @param #SETTINGS self -- @return #SETTINGS + -- @usage + -- _SETTINGS:SetPlayerMenuOn() -- will enable the player menus. function SETTINGS:SetPlayerMenuOn() self.ShowPlayerMenu = true end - --- Sets the player menus off, so that they will hide from the players. + --- Sets the player menus off, so that the **Player setting menus** won't show up for the players. + -- But only when a player exits and reenters the slot these settings will have effect! + -- It is advised to use this method at the start of the mission. -- @param #SETTINGS self - -- @return #SETTINGS + -- @return #SETTINGS self + -- @usage + -- _SETTINGS:SetPlayerMenuOff() -- will disable the player menus. function SETTINGS:SetPlayerMenuOff() self.ShowPlayerMenu = false end @@ -431,7 +566,7 @@ do -- SETTINGS --- Updates the menu of the player seated in the PlayerUnit. -- @param #SETTINGS self -- @param Wrapper.Client#CLIENT PlayerUnit - -- @return #SETTINGS + -- @return #SETTINGS self function SETTINGS:SetPlayerMenu( PlayerUnit ) if _SETTINGS.ShowPlayerMenu == true then @@ -571,7 +706,7 @@ do -- SETTINGS --- Removes the player menu from the PlayerUnit. --- @param #SETTINGS self -- @param Wrapper.Client#CLIENT PlayerUnit - -- @return #SETTINGS + -- @return #SETTINGS self function SETTINGS:RemovePlayerMenu( PlayerUnit ) if self.PlayerMenu then