Improve weather documentation and prevent division by 0

See merge request OpenMW/openmw!4966

(cherry-picked from 8b2be21)

Author: uramer

CMakeLists.txt

@@ -82,7 +82,7 @@ message(STATUS "Configuring OpenMW...")
 set(OPENMW_VERSION_MAJOR 0)
 set(OPENMW_VERSION_MINOR 50)
 set(OPENMW_VERSION_RELEASE 0)
-set(OPENMW_LUA_API_REVISION 96)
+set(OPENMW_LUA_API_REVISION 97)
 set(OPENMW_POSTPROCESSING_API_REVISION 3)
 
 set(OPENMW_VERSION_COMMITHASH "")

apps/openmw/mwlua/weatherbindings.cpp

@@ -161,6 +161,8 @@ namespace MWLua
         weatherT["cloudsMaximumPercent"]
             = sol::property([](const MWWorld::Weather& w) { return w.mCloudsMaximumPercent; },
                 [](MWWorld::Weather& w, const FiniteFloat cloudsMaximumPercent) {
+                    if (cloudsMaximumPercent <= 0.f)
+                        throw std::runtime_error("Value must be greater than 0");
                     w.mCloudsMaximumPercent = cloudsMaximumPercent;
                 });
         weatherT["isStorm"] = sol::property([](const MWWorld::Weather& w) { return w.mIsStorm; },
@@ -172,7 +174,11 @@ namespace MWLua
         weatherT["rainSpeed"] = sol::property([](const MWWorld::Weather& w) { return w.mRainSpeed; },
             [](MWWorld::Weather& w, const FiniteFloat rainSpeed) { w.mRainSpeed = rainSpeed; });
         weatherT["rainEntranceSpeed"] = sol::property([](const MWWorld::Weather& w) { return w.mRainEntranceSpeed; },
-            [](MWWorld::Weather& w, const FiniteFloat rainEntranceSpeed) { w.mRainEntranceSpeed = rainEntranceSpeed; });
+            [](MWWorld::Weather& w, const FiniteFloat rainEntranceSpeed) {
+                if (rainEntranceSpeed <= 0.f)
+                    throw std::runtime_error("Value must be greater than 0");
+                w.mRainEntranceSpeed = rainEntranceSpeed;
+            });
         weatherT["rainEffect"] = sol::property(
             [](const MWWorld::Weather& w) -> sol::optional<std::string> {
                 if (w.mRainEffect.empty())

files/lua_api/openmw/core.lua

@@ -1305,24 +1305,24 @@
 -- Weather data
 -- @type WeatherRecord
 -- @field #string recordId
--- @field #number scriptId
--- @field #string name
--- @field #number windSpeed
+-- @field #number scriptId Read-only ID used in mwscript and dialogue
+-- @field #string name Read-only weather name
+-- @field #number windSpeed Affects the angle of falling rain
 -- @field #number cloudSpeed
 -- @field #string cloudTexture
--- @field #number cloudsMaximumPercent
--- @field #boolean isStorm
+-- @field #number cloudsMaximumPercent Affects the speed of weather transitions (0, 1]
+-- @field #boolean isStorm Controls whether the weather is considered a storm for animation and movement purposes
 -- @field openmw.util#Vector3 stormDirection
--- @field #number glareView
--- @field #number rainSpeed
--- @field #number rainEntranceSpeed
+-- @field #number glareView Strength of the sun glare [0, 1]
+-- @field #number rainSpeed The speed at which rain falls
+-- @field #number rainEntranceSpeed The number of seconds between rain particle batches being created
 -- @field #string rainEffect Will return nil if weather has no rainEffect
--- @field #number rainMaxRaindrops
--- @field #number rainDiameter
--- @field #number rainMaxHeight
--- @field #number rainMinHeight
+-- @field #number rainMaxRaindrops The maximum number of rain particle batches to create every rainEntranceSpeed
+-- @field #number rainDiameter The area around the player to spawn rain in
+-- @field #number rainMaxHeight The maximum height relative to the player to spawn rain at
+-- @field #number rainMinHeight The minimum height relative to the player to spawn rain at
 -- @field #string rainLoopSoundID
--- @field #table  thunderSoundID An array containing the recordIds of the thunder sounds
+-- @field #table thunderSoundID A read-only array containing the recordIds of the thunder sounds
 -- @field #string ambientLoopSoundID
 -- @field #string particleEffect Will return nil if weather has no particleEffect
 -- @field #number distantLandFogFactor