@quenty/sunpositionutils 2.2.0 → 2.2.1-canary.283.715287b.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.2.1-canary.283.715287b.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sunpositionutils@2.2.0...@quenty/sunpositionutils@2.2.1-canary.283.715287b.0) (2022-08-16)
+
+**Note:** Version bump only for package @quenty/sunpositionutils
+
+
+
+
+
 # [2.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/sunpositionutils@2.1.1...@quenty/sunpositionutils@2.2.0) (2022-03-27)
 
 **Note:** Version bump only for package @quenty/sunpositionutils

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2021 Quenty
+Copyright (c) 2014-2022 Quenty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quenty/sunpositionutils",
-  "version": "2.2.0",
-  "description": "Utility to position the sun",
+  "version": "2.2.1-canary.283.715287b.0",
+  "description": "Utility to position the sun and to retrieve sun information specific to Roblox.",
   "keywords": [
     "Roblox",
     "Nevermore",
@@ -27,5 +27,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "501844bd6c3d3f765fd3032b997d8030bc963a1f"
+  "gitHead": "715287bf41b9be7160e69ec479cdc6c7d3ec5830"
 }

package/src/Shared/SunPositionUtils.lua

@@ -1,5 +1,10 @@
 --[=[
-	Utility to position the sun
+	Utility to position the sun and to retrieve sun information specific to Roblox.
+
+	Note this is not an accurate guess of where the sun would be on earth, but rather
+	the computation to compute where Roblox is rendering the sun given the lighting
+	properties set.
+
 	@class SunPositionUtils
 ]=]
 local SunPositionUtils = {}
@@ -8,31 +13,65 @@ local EARTH_TILT = 23.5
 local NORTH = Vector3.new(0, 0, -1)
 local ZAXIS = Vector3.new(0, 0, 1)
 
-function SunPositionUtils.getGeographicalLatitudeFromDirection(direction)
+--[=[
+	Gets the geographical latitude from a vector pointing at the sun.
+
+	@param direction Vector3
+	@return number
+]=]
+function SunPositionUtils.getGeographicalLatitudeFromDirection(direction: Vector3)
 	local angle = math.atan2(direction.z, math.sqrt(direction.x^2 + direction.y^2))
 	return angle/(math.pi*2)*360+EARTH_TILT
 end
 
 SunPositionUtils.getGeographicalLatitudeFromMoonDirection = SunPositionUtils.getGeographicalLatitudeFromDirection
 
-function SunPositionUtils.getClockTimeFromDirection(direction)
+--[=[
+	Gets the clock time for the given direction.
+
+	@param direction Vector3
+	@return number
+]=]
+function SunPositionUtils.getClockTimeFromDirection(direction: Vector3)
 	local altitude = math.atan2(-direction.y, -direction.x)
 
 	return (altitude/(math.pi*2)*24-6) % 24
 end
 
-function SunPositionUtils.getClockTimeFromMoonDirection(direction)
+--[=[
+	Gets the clock time from the given moon direction.
+
+	@param direction Vector3
+	@return number
+]=]
+function SunPositionUtils.getClockTimeFromMoonDirection(direction: Vector3)
 	local altitude = math.atan2(direction.y, direction.x)
 
 	return (altitude/(math.pi*2)*24-6) % 24
 end
 
-function SunPositionUtils.getDirection(azimuthRad, altitudeRad, north)
+--[=[
+	Gets the direction the sun should be facing given the azimuth and altitude
+
+	@param azimuthRad number
+	@param altitudeRad number
+	@param north Vector3?
+	@return number
+]=]
+function SunPositionUtils.getDirection(azimuthRad: number, altitudeRad: number, north: Vector3)
 	local cframe = (CFrame.Angles(0, azimuthRad, 0) * CFrame.Angles(altitudeRad, 0, 0))
 	return cframe:vectorToWorldSpace(north or NORTH)
 end
 
-function SunPositionUtils.getSunPosition(clockTime, geoLatitude)
+--[=[
+	Estimates the sun position given the clockTime and geographical latitude.
+
+	@param clockTime number
+	@param geoLatitude number
+	@return Vector3 -- Sun position
+	@return Vector3 -- Moon position
+]=]
+function SunPositionUtils.getSunPosition(clockTime: number, geoLatitude: number)
 	local seconds = clockTime*60*60
 	local DAY = 24 * 60 * 60
 	local YEAR = 365.2564 * DAY