Merge PR #5387 (soloturn-moon-phases) into merge-train

Author: soloturn

engine-tests/src/test/java/org/terasology/engine/world/sun/DefaultCelestialSystemTest.java

@@ -0,0 +1,73 @@
+// Copyright 2021 The Terasology Foundation
+// SPDX-License-Identifier: Apache-2.0
+package org.terasology.engine.world.sun;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.terasology.engine.entitySystem.entity.EntityManager;
+import org.terasology.engine.world.WorldProvider;
+import org.terasology.engine.world.time.WorldTime;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * See #94: getMoonPhase() is a hook other systems (rendering, gameplay, a future calendar) can key off
+ * without each needing their own day-counting logic, based on the same day counter getSunPosAngle()
+ * already uses.
+ */
+public class DefaultCelestialSystemTest {
+
+    private static final float MOON_CYCLE_DAYS = 29.53f;
+    private static final float EPSILON = 1e-4f;
+
+    private WorldTime worldTime;
+    private DefaultCelestialSystem celestialSystem;
+
+    @BeforeEach
+    public void setup() {
+        CelestialModel model = mock(CelestialModel.class);
+        WorldProvider worldProvider = mock(WorldProvider.class);
+        EntityManager entityManager = mock(EntityManager.class);
+        worldTime = mock(WorldTime.class);
+        when(worldProvider.getTime()).thenReturn(worldTime);
+
+        celestialSystem = new DefaultCelestialSystem(model, worldProvider, entityManager);
+    }
+
+    private void setDays(float days) {
+        when(worldTime.getDays()).thenReturn(days);
+    }
+
+    @Test
+    public void newMoonAtDayZero() {
+        setDays(0f);
+        assertEquals(0f, celestialSystem.getMoonPhase(), EPSILON);
+    }
+
+    @Test
+    public void fullMoonHalfwayThroughTheCycle() {
+        setDays(MOON_CYCLE_DAYS / 2f);
+        assertEquals(0.5f, celestialSystem.getMoonPhase(), EPSILON);
+    }
+
+    @Test
+    public void phaseWrapsAroundAfterACompleteCycle() {
+        setDays(MOON_CYCLE_DAYS + MOON_CYCLE_DAYS / 4f);
+        assertEquals(0.25f, celestialSystem.getMoonPhase(), EPSILON);
+    }
+
+    @Test
+    public void phaseWrapsAroundAfterManyCycles() {
+        setDays(MOON_CYCLE_DAYS * 100 + MOON_CYCLE_DAYS * 0.75f);
+        assertEquals(0.75f, celestialSystem.getMoonPhase(), EPSILON);
+    }
+
+    @Test
+    public void phaseStaysInRangeWhenSunIsHalted() {
+        setDays(1000f);
+        celestialSystem.toggleSunHalting(MOON_CYCLE_DAYS / 4f);
+        assertEquals(0.25f, celestialSystem.getMoonPhase(), EPSILON);
+    }
+}

engine/src/main/java/org/terasology/engine/rendering/backdrop/BackdropProvider.java

@@ -28,4 +28,6 @@ public interface BackdropProvider {
 
     Vector3f getSunDirection(boolean moonlightFlip);
 
+    float getMoonPhase();
+
 }

engine/src/main/java/org/terasology/engine/rendering/backdrop/Skysphere.java

@@ -70,4 +70,9 @@ public Vector3f getSunDirection(boolean moonlightFlip) {
 
         return sunDirection;
     }
+
+    @Override
+    public float getMoonPhase() {
+        return celSystem.getMoonPhase();
+    }
 }

engine/src/main/java/org/terasology/engine/world/sun/CelestialSystem.java

@@ -24,4 +24,12 @@ public interface CelestialSystem {
      * @return Whether the sun is currently halted or not
      */
     boolean isSunHalted();
+
+    /**
+     * @return the current phase of the moon, as a value in [0, 1) where 0 (and the limit at 1) is new
+     * moon and 0.5 is full moon. Intended as a hook for anything wanting to key off the moon's phase -
+     * rendering, gameplay, a future astronomical/calendar system - without needing its own day-counting
+     * logic. See #94.
+     */
+    float getMoonPhase();
 }

engine/src/main/java/org/terasology/engine/world/sun/DefaultCelestialSystem.java

@@ -21,6 +21,12 @@
  */
 public class DefaultCelestialSystem extends BaseComponentSystem implements CelestialSystem, UpdateSubscriberSystem {
 
+    /**
+     * Length of a full lunar cycle, in game days. Defaults to the real-world synodic month so a
+     * calendar built on top of this lines up with familiar phase names/timing.
+     */
+    private static final float MOON_CYCLE_DAYS = 29.53f;
+
     private final WorldTime worldTime;
 
     private long lastUpdate;
@@ -56,13 +62,7 @@ public void update(float delta) {
 
     @Override
     public float getSunPosAngle() {
-        float days;
-        if (isSunHalted()) {
-            days = haltedTime;
-        } else {
-            days = getWorldTime().getDays();
-        }
-        return  model.getSunPosAngle(days);
+        return model.getSunPosAngle(getCurrentDays());
     }
 
     @Override
@@ -75,6 +75,18 @@ public void toggleSunHalting(float timeInDays) {
         haltSunPosition = !haltSunPosition;
         haltedTime = timeInDays;
     }
+
+    @Override
+    public float getMoonPhase() {
+        float phase = getCurrentDays() % MOON_CYCLE_DAYS / MOON_CYCLE_DAYS;
+        // getCurrentDays() is expected to always be non-negative, but guard against a negative
+        // result from a halted/rewound time anyway rather than return an out-of-range phase.
+        return phase < 0 ? phase + 1 : phase;
+    }
+
+    private float getCurrentDays() {
+        return isSunHalted() ? haltedTime : getWorldTime().getDays();
+    }
     /**
      * Updates the game perception of the time of day via launching a new OnMiddayEvent(),
      * OnDuskEvent(), OnMidnightEvent(), or OnDawnEvent() based on the time of day when