redscript-mc 1.1.0 → 1.2.1

package/src/stdlib/timer.mcrs

@@ -1,51 +1,72 @@
-// Countdown timer helpers.
+// Timer utilities with an OOP-style API.
 //
-// The current compiler does not propagate string literals through user-defined
-// function calls yet, so the `name` parameter is a forward-compatible placeholder.
-// This module manages one timer slot backed by fake players on the `rs` objective.
+// Timer state is stored in scoreboard-backed runtime state. Because RedScript
+// does not yet support dynamic scoreboard player/objective names for impl
+// methods, this API currently uses a single shared runtime slot.
+//
+// The `_id` field is reserved for a future runtime-backed instance identifier.
+// Today it remains `0`, while persistence is shared across Timer values.
 
 struct Timer {
-    ticks: int,
-    active: int
-}
-
-fn timer_start(name: string, duration: int) {
-    scoreboard_set("timer_ticks", #rs, duration);
-    scoreboard_set("timer_active", #rs, 1);
+    _id: int,
+    _duration: int
 }
 
-fn timer_tick(name: string) -> int {
-    let active: int = scoreboard_get("timer_active", #rs);
-    let ticks: int = scoreboard_get("timer_ticks", #rs);
+impl Timer {
+    /// Create a new timer with the given duration in ticks.
+    fn new(duration: int) -> Timer {
+        scoreboard_set("timer_ticks", #rs, 0);
+        scoreboard_set("timer_active", #rs, 0);
+        return { _id: 0, _duration: duration };
+    }
 
-    if (active == 0) {
-        return 0;
+    /// Start or resume the timer.
+    fn start(self) {
+        scoreboard_set("timer_active", #rs, 1);
     }
 
-    if (ticks > 0) {
-        let next: int = ticks - 1;
-        scoreboard_set("timer_ticks", #rs, next);
+    /// Pause the timer.
+    fn pause(self) {
+        scoreboard_set("timer_active", #rs, 0);
+    }
 
-        if (next == 0) {
-            scoreboard_set("timer_active", #rs, 0);
-        }
+    /// Reset elapsed ticks back to zero.
+    fn reset(self) {
+        scoreboard_set("timer_ticks", #rs, 0);
+    }
 
-        return next;
+    /// Check whether the timer has reached its duration.
+    fn done(self) -> bool {
+        let ticks: int = scoreboard_get("timer_ticks", #rs);
+        return ticks >= self._duration;
     }
 
-    scoreboard_set("timer_active", #rs, 0);
-    return 0;
-}
+    /// Get elapsed ticks.
+    fn elapsed(self) -> int {
+        return scoreboard_get("timer_ticks", #rs);
+    }
 
-fn timer_done(name: string) -> int {
-    let active: int = scoreboard_get("timer_active", #rs);
-    let ticks: int = scoreboard_get("timer_ticks", #rs);
+    /// Get remaining ticks, clamped at zero.
+    fn remaining(self) -> int {
+        let ticks: int = scoreboard_get("timer_ticks", #rs);
+        let left: int = self._duration - ticks;
 
-    if (active == 0) {
-        if (ticks <= 0) {
-            return 1;
+        if (left > 0) {
+            return left;
         }
+
+        return 0;
     }
 
-    return 0;
+    /// Manually advance the timer by one tick when active.
+    fn tick(self) {
+        let active: int = scoreboard_get("timer_active", #rs);
+        let ticks: int = scoreboard_get("timer_ticks", #rs);
+
+        if (active == 1) {
+            if (ticks < self._duration) {
+                scoreboard_set("timer_ticks", #rs, ticks + 1);
+            }
+        }
+    }
 }