Timer refactor: stopwatch-like semantics, mcrfpy.timers collection closes #173

Major Timer API improvements:
- Add `stopped` flag to Timer C++ class for proper state management
- Add `start()` method to restart stopped timers (preserves callback)
- Add `stop()` method that removes from engine but preserves callback
- Make `active` property read-write (True=start/resume, False=pause)
- Add `start=True` init parameter to create timers in stopped state
- Add `mcrfpy.timers` module-level collection (tuple of active timers)
- One-shot timers now set stopped=true instead of clearing callback
- Remove deprecated `setTimer()` and `delTimer()` module functions

Timer callbacks now receive (timer, runtime) instead of just (runtime).
Updated all tests to use new Timer API and callback signature.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/GameEngine.cpp

@@ -357,51 +357,35 @@ std::shared_ptr<Timer> GameEngine::getTimer(const std::string& name)
     return nullptr;
 }
 
-void GameEngine::manageTimer(std::string name, PyObject* target, int interval)
+// Note: manageTimer() removed in #173 - use Timer objects directly
-{
-    auto it = timers.find(name);
-
-    // #153 - In headless mode, use simulation_time instead of real-time clock
-    int now = headless ? simulation_time : runtime.getElapsedTime().asMilliseconds();
-
-    if (it != timers.end()) // overwrite existing
-    {
-        if (target == NULL || target == Py_None)
-        {
-            // Delete: Overwrite existing timer with one that calls None. This will be deleted in the next timer check
-            // see gitea issue #4: this allows for a timer to be deleted during its own call to itself
-            timers[name] = std::make_shared<Timer>(Py_None, 1000, now);
-            return;
-        }
-    }
-    if (target == NULL || target == Py_None)
-    {
-        std::cout << "Refusing to initialize timer to None. It's not an error, it's just pointless." << std::endl;
-        return;
-    }
-    timers[name] = std::make_shared<Timer>(target, interval, now);
-}
 
 void GameEngine::testTimers()
 {
-    int now = runtime.getElapsedTime().asMilliseconds();
+    int now = headless ? simulation_time : runtime.getElapsedTime().asMilliseconds();
     auto it = timers.begin();
     while (it != timers.end())
     {
         // Keep a local copy of the timer to prevent use-after-free.
-        // If the callback calls delTimer(), the map entry gets replaced,
+        // If the callback calls stop(), the timer may be marked for removal,
         // but we need the Timer object to survive until test() returns.
         auto timer = it->second;
-        timer->test(now);
 
-        // Remove timers that have been cancelled or are one-shot and fired.
+        // Skip stopped timers (they'll be removed below)
+        if (!timer->isStopped()) {
+            timer->test(now);
+        }
+
+        // Remove timers that have been stopped (including one-shot timers that fired).
+        // The stopped flag is the authoritative marker for "remove from map".
         // Note: Check it->second (current map value) in case callback replaced it.
-        if (!it->second->getCallback() || it->second->getCallback() == Py_None)
+        if (it->second->isStopped())
         {
             it = timers.erase(it);
         }
         else
+        {
             it++;
+        }
     }
 }
 

src/GameEngine.h

@@ -169,7 +169,7 @@ public:
     int getFrame() { return currentFrame; }
     float getFrameTime() { return frameTime; }
     sf::View getView() { return visible; }
-    void manageTimer(std::string, PyObject*, int);
+    // Note: manageTimer() removed in #173 - use Timer objects directly
     std::shared_ptr<Timer> getTimer(const std::string& name);
     void setWindowScale(float);
     bool isHeadless() const { return headless; }

src/McRFPy_API.cpp

@@ -24,6 +24,7 @@
 #include "GridLayers.h"
 #include "Resources.h"
 #include "PyScene.h"
+#include "PythonObjectCache.h"
 #include <filesystem>
 #include <cstring>
 #include <libtcod.h>
@@ -52,6 +53,10 @@ static PyObject* mcrfpy_module_getattr(PyObject* self, PyObject* args)
         return McRFPy_API::api_get_scenes();
     }
 
+    if (strcmp(name, "timers") == 0) {
+        return McRFPy_API::api_get_timers();
+    }
+
     if (strcmp(name, "default_transition") == 0) {
         return PyTransition::to_python(PyTransition::default_transition);
     }
@@ -80,6 +85,11 @@ static int mcrfpy_module_setattro(PyObject* self, PyObject* name, PyObject* valu
         return -1;
     }
 
+    if (strcmp(name_str, "timers") == 0) {
+        PyErr_SetString(PyExc_AttributeError, "'timers' is read-only");
+        return -1;
+    }
+
     if (strcmp(name_str, "default_transition") == 0) {
         TransitionType trans;
         if (!PyTransition::from_arg(value, &trans, nullptr)) {
@@ -138,26 +148,7 @@ static PyTypeObject McRFPyModuleType = {
 
 static PyMethodDef mcrfpyMethods[] = {
 
-    {"setTimer", McRFPy_API::_setTimer, METH_VARARGS,
+    // Note: setTimer and delTimer removed in #173 - use Timer objects instead
-     MCRF_FUNCTION(setTimer,
-         MCRF_SIG("(name: str, handler: callable, interval: int)", "None"),
-         MCRF_DESC("Create or update a recurring timer."),
-         MCRF_ARGS_START
-         MCRF_ARG("name", "Unique identifier for the timer")
-         MCRF_ARG("handler", "Function called with (runtime: float) parameter")
-         MCRF_ARG("interval", "Time between calls in milliseconds")
-         MCRF_RETURNS("None")
-         MCRF_NOTE("If a timer with this name exists, it will be replaced. The handler receives the total runtime in seconds as its argument.")
-     )},
-    {"delTimer", McRFPy_API::_delTimer, METH_VARARGS,
-     MCRF_FUNCTION(delTimer,
-         MCRF_SIG("(name: str)", "None"),
-         MCRF_DESC("Stop and remove a timer."),
-         MCRF_ARGS_START
-         MCRF_ARG("name", "Timer identifier to remove")
-         MCRF_RETURNS("None")
-         MCRF_NOTE("No error is raised if the timer doesn't exist.")
-     )},
     {"step", McRFPy_API::_step, METH_VARARGS,
      MCRF_FUNCTION(step,
          MCRF_SIG("(dt: float = None)", "float"),
@@ -883,22 +874,34 @@ PyObject* McRFPy_API::_setScene(PyObject* self, PyObject* args) {
     return Py_None;		
 }
 
-PyObject* McRFPy_API::_setTimer(PyObject* self, PyObject* args) { // TODO - compare with UIDrawable mouse & Scene Keyboard methods - inconsistent responsibility for incref/decref around mcrogueface
+// #173: Get all timers as a tuple of Python Timer objects
-    const char* name;
+PyObject* McRFPy_API::api_get_timers()
-    PyObject* callable;
+{
-    int interval;
+    if (!game) {
-	if (!PyArg_ParseTuple(args, "sOi", &name, &callable, &interval)) return NULL;
+        return PyTuple_New(0);
-    game->manageTimer(name, callable, interval);
+    }
-    Py_INCREF(Py_None);
-    return Py_None;
-}
 
-PyObject* McRFPy_API::_delTimer(PyObject* self, PyObject* args) {
+    // Count timers that have Python wrappers
-	const char* name;
+    std::vector<PyObject*> timer_objs;
-	if (!PyArg_ParseTuple(args, "s", &name)) return NULL;
+    for (auto& pair : game->timers) {
-    game->manageTimer(name, NULL, 0);
+        auto& timer = pair.second;
-    Py_INCREF(Py_None);
+        if (timer && timer->serial_number != 0) {
-    return Py_None;
+            PyObject* timer_obj = PythonObjectCache::getInstance().lookup(timer->serial_number);
+            if (timer_obj && timer_obj != Py_None) {
+                timer_objs.push_back(timer_obj);
+            }
+        }
+    }
+
+    PyObject* tuple = PyTuple_New(timer_objs.size());
+    if (!tuple) return NULL;
+
+    for (Py_ssize_t i = 0; i < static_cast<Py_ssize_t>(timer_objs.size()); i++) {
+        Py_INCREF(timer_objs[i]);
+        PyTuple_SET_ITEM(tuple, i, timer_objs[i]);
+    }
+
+    return tuple;
 }
 
 // #153 - Headless simulation control

src/McRFPy_API.h

@@ -43,9 +43,7 @@ public:
     // Internal - used by PySceneObject::activate()
     static PyObject* _setScene(PyObject*, PyObject*);
 
-    // timer control
+    // Note: setTimer/delTimer removed in #173 - use Timer objects instead
-    static PyObject* _setTimer(PyObject*, PyObject*);
-    static PyObject* _delTimer(PyObject*, PyObject*);
 
     // #153 - Headless simulation control
     static PyObject* _step(PyObject*, PyObject*);
@@ -88,6 +86,9 @@ public:
     static int api_set_current_scene(PyObject* value);
     static PyObject* api_get_scenes();
 
+    // #173: Module-level timer collection accessor
+    static PyObject* api_get_timers();
+
     // Exception handling - signal game loop to exit on unhandled Python exceptions
     static std::atomic<bool> exception_occurred;
     static std::atomic<int> exit_code;

src/PyTimer.cpp

@@ -10,13 +10,15 @@ PyObject* PyTimer::repr(PyObject* self) {
     PyTimerObject* timer = (PyTimerObject*)self;
     std::ostringstream oss;
     oss << "<Timer name='" << timer->name << "' ";
-    
+
     if (timer->data) {
         oss << "interval=" << timer->data->getInterval() << "ms ";
         if (timer->data->isOnce()) {
             oss << "once=True ";
         }
-        if (timer->data->isPaused()) {
+        if (timer->data->isStopped()) {
+            oss << "stopped";
+        } else if (timer->data->isPaused()) {
             oss << "paused";
             // Get current time to show remaining
             int current_time = 0;
@@ -25,15 +27,15 @@ PyObject* PyTimer::repr(PyObject* self) {
             }
             oss << " (remaining=" << timer->data->getRemaining(current_time) << "ms)";
         } else if (timer->data->isActive()) {
-            oss << "active";
+            oss << "running";
         } else {
-            oss << "cancelled";
+            oss << "inactive";
         }
     } else {
         oss << "uninitialized";
     }
     oss << ">";
-    
+
     return PyUnicode_FromString(oss.str().c_str());
 }
 
@@ -48,38 +50,39 @@ PyObject* PyTimer::pynew(PyTypeObject* type, PyObject* args, PyObject* kwds) {
 }
 
 int PyTimer::init(PyTimerObject* self, PyObject* args, PyObject* kwds) {
-    static const char* kwlist[] = {"name", "callback", "interval", "once", NULL};
+    static const char* kwlist[] = {"name", "callback", "interval", "once", "start", NULL};
     const char* name = nullptr;
     PyObject* callback = nullptr;
     int interval = 0;
-    int once = 0;  // Use int for bool parameter
+    int once = 0;      // Use int for bool parameter
-    
+    int start = 1;     // Default: start=True
-    if (!PyArg_ParseTupleAndKeywords(args, kwds, "sOi|p", const_cast<char**>(kwlist), 
+
-                                     &name, &callback, &interval, &once)) {
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "sOi|pp", const_cast<char**>(kwlist),
+                                     &name, &callback, &interval, &once, &start)) {
         return -1;
     }
-    
+
     if (!PyCallable_Check(callback)) {
         PyErr_SetString(PyExc_TypeError, "callback must be callable");
         return -1;
     }
-    
+
     if (interval <= 0) {
         PyErr_SetString(PyExc_ValueError, "interval must be positive");
         return -1;
     }
-    
+
     self->name = name;
-    
+
     // Get current time from game engine
     int current_time = 0;
     if (Resources::game) {
         current_time = Resources::game->runtime.getElapsedTime().asMilliseconds();
     }
-    
+
-    // Create the timer
+    // Create the timer with start parameter
-    self->data = std::make_shared<Timer>(callback, interval, current_time, (bool)once);
+    self->data = std::make_shared<Timer>(callback, interval, current_time, (bool)once, (bool)start);
-    
+
     // Register in Python object cache
     if (self->data->serial_number == 0) {
         self->data->serial_number = PythonObjectCache::getInstance().assignSerial();
@@ -89,12 +92,17 @@ int PyTimer::init(PyTimerObject* self, PyObject* args, PyObject* kwds) {
             Py_DECREF(weakref);  // Cache owns the reference now
         }
     }
-    
+
-    // Register with game engine
+    // Register with game engine only if starting
-    if (Resources::game) {
+    if (Resources::game && start) {
+        // If a timer with this name already exists, stop it first
+        auto it = Resources::game->timers.find(self->name);
+        if (it != Resources::game->timers.end() && it->second != self->data) {
+            it->second->stop();
+        }
         Resources::game->timers[self->name] = self->data;
     }
-    
+
     return 0;
 }
 
@@ -103,7 +111,7 @@ void PyTimer::dealloc(PyTimerObject* self) {
     if (self->weakreflist != nullptr) {
         PyObject_ClearWeakRefs((PyObject*)self);
     }
-    
+
     // Remove from game engine if still registered
     if (Resources::game && !self->name.empty()) {
         auto it = Resources::game->timers.find(self->name);
@@ -111,28 +119,71 @@ void PyTimer::dealloc(PyTimerObject* self) {
             Resources::game->timers.erase(it);
         }
     }
-    
+
     // Explicitly destroy std::string
     self->name.~basic_string();
-    
+
-    // Clear shared_ptr
+    // Clear shared_ptr - this is the only place that truly destroys the Timer
     self->data.reset();
-    
+
     Py_TYPE(self)->tp_free((PyObject*)self);
 }
 
 // Timer control methods
+PyObject* PyTimer::start(PyTimerObject* self, PyObject* Py_UNUSED(ignored)) {
+    if (!self->data) {
+        PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
+        return nullptr;
+    }
+
+    int current_time = 0;
+    if (Resources::game) {
+        current_time = Resources::game->runtime.getElapsedTime().asMilliseconds();
+
+        // If another timer has this name, stop it first
+        auto it = Resources::game->timers.find(self->name);
+        if (it != Resources::game->timers.end() && it->second != self->data) {
+            it->second->stop();
+        }
+
+        // Add to engine map
+        Resources::game->timers[self->name] = self->data;
+    }
+
+    self->data->start(current_time);
+    Py_RETURN_NONE;
+}
+
+PyObject* PyTimer::stop(PyTimerObject* self, PyObject* Py_UNUSED(ignored)) {
+    if (!self->data) {
+        PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
+        return nullptr;
+    }
+
+    // Remove from game engine map (but preserve the Timer data!)
+    if (Resources::game && !self->name.empty()) {
+        auto it = Resources::game->timers.find(self->name);
+        if (it != Resources::game->timers.end() && it->second == self->data) {
+            Resources::game->timers.erase(it);
+        }
+    }
+
+    self->data->stop();
+    // NOTE: We do NOT reset self->data here - the timer can be restarted
+    Py_RETURN_NONE;
+}
+
 PyObject* PyTimer::pause(PyTimerObject* self, PyObject* Py_UNUSED(ignored)) {
     if (!self->data) {
         PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
         return nullptr;
     }
-    
+
     int current_time = 0;
     if (Resources::game) {
         current_time = Resources::game->runtime.getElapsedTime().asMilliseconds();
     }
-    
+
     self->data->pause(current_time);
     Py_RETURN_NONE;
 }
@@ -142,32 +193,13 @@ PyObject* PyTimer::resume(PyTimerObject* self, PyObject* Py_UNUSED(ignored)) {
         PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
         return nullptr;
     }
-    
+
     int current_time = 0;
     if (Resources::game) {
         current_time = Resources::game->runtime.getElapsedTime().asMilliseconds();
     }
-    
-    self->data->resume(current_time);
-    Py_RETURN_NONE;
-}
 
-PyObject* PyTimer::cancel(PyTimerObject* self, PyObject* Py_UNUSED(ignored)) {
+    self->data->resume(current_time);
-    if (!self->data) {
-        PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
-        return nullptr;
-    }
-    
-    // Remove from game engine
-    if (Resources::game && !self->name.empty()) {
-        auto it = Resources::game->timers.find(self->name);
-        if (it != Resources::game->timers.end() && it->second == self->data) {
-            Resources::game->timers.erase(it);
-        }
-    }
-    
-    self->data->cancel();
-    self->data.reset();
     Py_RETURN_NONE;
 }
 
@@ -176,12 +208,23 @@ PyObject* PyTimer::restart(PyTimerObject* self, PyObject* Py_UNUSED(ignored)) {
         PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
         return nullptr;
     }
-    
+
     int current_time = 0;
     if (Resources::game) {
         current_time = Resources::game->runtime.getElapsedTime().asMilliseconds();
+
+        // Ensure timer is in engine map
+        auto it = Resources::game->timers.find(self->name);
+        if (it == Resources::game->timers.end()) {
+            // Timer was stopped, re-add it
+            Resources::game->timers[self->name] = self->data;
+        } else if (it->second != self->data) {
+            // Another timer has this name, stop it and replace
+            it->second->stop();
+            Resources::game->timers[self->name] = self->data;
+        }
     }
-    
+
     self->data->restart(current_time);
     Py_RETURN_NONE;
 }
@@ -240,14 +283,62 @@ PyObject* PyTimer::get_paused(PyTimerObject* self, void* closure) {
     return PyBool_FromLong(self->data->isPaused());
 }
 
+PyObject* PyTimer::get_stopped(PyTimerObject* self, void* closure) {
+    if (!self->data) {
+        return Py_True;  // Uninitialized is effectively stopped
+    }
+
+    return PyBool_FromLong(self->data->isStopped());
+}
+
 PyObject* PyTimer::get_active(PyTimerObject* self, void* closure) {
     if (!self->data) {
         return Py_False;
     }
-    
+
     return PyBool_FromLong(self->data->isActive());
 }
 
+int PyTimer::set_active(PyTimerObject* self, PyObject* value, void* closure) {
+    if (!self->data) {
+        PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
+        return -1;
+    }
+
+    bool want_active = PyObject_IsTrue(value);
+
+    int current_time = 0;
+    if (Resources::game) {
+        current_time = Resources::game->runtime.getElapsedTime().asMilliseconds();
+    }
+
+    if (want_active) {
+        if (self->data->isStopped()) {
+            // Reactivate a stopped timer
+            if (Resources::game) {
+                // Handle name collision
+                auto it = Resources::game->timers.find(self->name);
+                if (it != Resources::game->timers.end() && it->second != self->data) {
+                    it->second->stop();
+                }
+                Resources::game->timers[self->name] = self->data;
+            }
+            self->data->start(current_time);
+        } else if (self->data->isPaused()) {
+            // Resume from pause
+            self->data->resume(current_time);
+        }
+        // If already running, do nothing
+    } else {
+        // Setting active=False means pause
+        if (!self->data->isPaused() && !self->data->isStopped()) {
+            self->data->pause(current_time);
+        }
+    }
+
+    return 0;
+}
+
 PyObject* PyTimer::get_callback(PyTimerObject* self, void* closure) {
     if (!self->data) {
         PyErr_SetString(PyExc_RuntimeError, "Timer not initialized");
@@ -312,19 +403,35 @@ PyGetSetDef PyTimer::getsetters[] = {
     {"interval", (getter)PyTimer::get_interval, (setter)PyTimer::set_interval,
      MCRF_PROPERTY(interval, "Timer interval in milliseconds (int). Must be positive. Can be changed while timer is running."), NULL},
     {"remaining", (getter)PyTimer::get_remaining, NULL,
-     MCRF_PROPERTY(remaining, "Time remaining until next trigger in milliseconds (int, read-only). Preserved when timer is paused."), NULL},
+     MCRF_PROPERTY(remaining, "Time remaining until next trigger in milliseconds (int, read-only). Full interval when stopped."), NULL},
     {"paused", (getter)PyTimer::get_paused, NULL,
      MCRF_PROPERTY(paused, "Whether the timer is paused (bool, read-only). Paused timers preserve their remaining time."), NULL},
-    {"active", (getter)PyTimer::get_active, NULL,
+    {"stopped", (getter)PyTimer::get_stopped, NULL,
-     MCRF_PROPERTY(active, "Whether the timer is active and not paused (bool, read-only). False if cancelled or paused."), NULL},
+     MCRF_PROPERTY(stopped, "Whether the timer is stopped (bool, read-only). Stopped timers are not in the engine tick loop but preserve their callback."), NULL},
+    {"active", (getter)PyTimer::get_active, (setter)PyTimer::set_active,
+     MCRF_PROPERTY(active, "Running state (bool, read-write). True if running (not paused, not stopped). Set True to start/resume, False to pause."), NULL},
     {"callback", (getter)PyTimer::get_callback, (setter)PyTimer::set_callback,
-     MCRF_PROPERTY(callback, "The callback function to be called when timer fires (callable). Can be changed while timer is running."), NULL},
+     MCRF_PROPERTY(callback, "The callback function (callable). Preserved when stopped, allowing timer restart."), NULL},
     {"once", (getter)PyTimer::get_once, (setter)PyTimer::set_once,
-     MCRF_PROPERTY(once, "Whether the timer stops after firing once (bool). If False, timer repeats indefinitely."), NULL},
+     MCRF_PROPERTY(once, "Whether the timer stops after firing once (bool). One-shot timers can be restarted."), NULL},
     {NULL}
 };
 
 PyMethodDef PyTimer::methods[] = {
+    {"start", (PyCFunction)PyTimer::start, METH_NOARGS,
+     MCRF_METHOD(Timer, start,
+         MCRF_SIG("()", "None"),
+         MCRF_DESC("Start the timer, adding it to the engine tick loop."),
+         MCRF_RETURNS("None")
+         MCRF_NOTE("Resets progress and begins counting toward the next fire. If another timer has this name, it will be stopped.")
+     )},
+    {"stop", (PyCFunction)PyTimer::stop, METH_NOARGS,
+     MCRF_METHOD(Timer, stop,
+         MCRF_SIG("()", "None"),
+         MCRF_DESC("Stop the timer and remove it from the engine tick loop."),
+         MCRF_RETURNS("None")
+         MCRF_NOTE("The callback is preserved, so the timer can be restarted with start() or restart().")
+     )},
     {"pause", (PyCFunction)PyTimer::pause, METH_NOARGS,
      MCRF_METHOD(Timer, pause,
          MCRF_SIG("()", "None"),
@@ -339,19 +446,12 @@ PyMethodDef PyTimer::methods[] = {
          MCRF_RETURNS("None")
          MCRF_NOTE("Has no effect if the timer is not paused. Timer will fire after the remaining time elapses.")
      )},
-    {"cancel", (PyCFunction)PyTimer::cancel, METH_NOARGS,
-     MCRF_METHOD(Timer, cancel,
-         MCRF_SIG("()", "None"),
-         MCRF_DESC("Cancel the timer and remove it from the timer system."),
-         MCRF_RETURNS("None")
-         MCRF_NOTE("The timer will no longer fire and cannot be restarted. The callback will not be called again.")
-     )},
     {"restart", (PyCFunction)PyTimer::restart, METH_NOARGS,
      MCRF_METHOD(Timer, restart,
          MCRF_SIG("()", "None"),
-         MCRF_DESC("Restart the timer from the beginning."),
+         MCRF_DESC("Restart the timer from the beginning and ensure it's running."),
          MCRF_RETURNS("None")
-         MCRF_NOTE("Resets the timer to fire after a full interval from now, regardless of remaining time.")
+         MCRF_NOTE("Resets progress and adds timer to engine if stopped. Equivalent to stop() followed by start().")
      )},
     {NULL}
 };

src/PyTimer.h

@@ -23,9 +23,10 @@ public:
     static void dealloc(PyTimerObject* self);
     
     // Timer control methods
+    static PyObject* start(PyTimerObject* self, PyObject* Py_UNUSED(ignored));
+    static PyObject* stop(PyTimerObject* self, PyObject* Py_UNUSED(ignored));
     static PyObject* pause(PyTimerObject* self, PyObject* Py_UNUSED(ignored));
     static PyObject* resume(PyTimerObject* self, PyObject* Py_UNUSED(ignored));
-    static PyObject* cancel(PyTimerObject* self, PyObject* Py_UNUSED(ignored));
     static PyObject* restart(PyTimerObject* self, PyObject* Py_UNUSED(ignored));
     
     // Timer property getters
@@ -34,7 +35,9 @@ public:
     static int set_interval(PyTimerObject* self, PyObject* value, void* closure);
     static PyObject* get_remaining(PyTimerObject* self, void* closure);
     static PyObject* get_paused(PyTimerObject* self, void* closure);
+    static PyObject* get_stopped(PyTimerObject* self, void* closure);
     static PyObject* get_active(PyTimerObject* self, void* closure);
+    static int set_active(PyTimerObject* self, PyObject* value, void* closure);
     static PyObject* get_callback(PyTimerObject* self, void* closure);
     static int set_callback(PyTimerObject* self, PyObject* value, void* closure);
     static PyObject* get_once(PyTimerObject* self, void* closure);
@@ -53,35 +56,39 @@ namespace mcrfpydef {
         .tp_dealloc = (destructor)PyTimer::dealloc,
         .tp_repr = PyTimer::repr,
         .tp_flags = Py_TPFLAGS_DEFAULT,
-        .tp_doc = PyDoc_STR("Timer(name, callback, interval, once=False)\n\n"
+        .tp_doc = PyDoc_STR("Timer(name, callback, interval, once=False, start=True)\n\n"
                             "Create a timer that calls a function at regular intervals.\n\n"
                             "Args:\n"
                             "    name (str): Unique identifier for the timer\n"
                             "    callback (callable): Function to call - receives (timer, runtime) args\n"
                             "    interval (int): Time between calls in milliseconds\n"
-                            "    once (bool): If True, timer stops after first call. Default: False\n\n"
+                            "    once (bool): If True, timer stops after first call. Default: False\n"
+                            "    start (bool): If True, timer starts immediately. Default: True\n\n"
                             "Attributes:\n"
                             "    interval (int): Time between calls in milliseconds\n"
                             "    remaining (int): Time until next call in milliseconds (read-only)\n"
                             "    paused (bool): Whether timer is paused (read-only)\n"
-                            "    active (bool): Whether timer is active and not paused (read-only)\n"
+                            "    stopped (bool): Whether timer is stopped (read-only)\n"
-                            "    callback (callable): The callback function\n"
+                            "    active (bool): Running state (read-write). Set True to start, False to pause\n"
+                            "    callback (callable): The callback function (preserved when stopped)\n"
                             "    once (bool): Whether timer stops after firing once\n\n"
                             "Methods:\n"
+                            "    start(): Start the timer, adding to engine tick loop\n"
+                            "    stop(): Stop the timer (removes from engine, preserves callback)\n"
                             "    pause(): Pause the timer, preserving time remaining\n"
                             "    resume(): Resume a paused timer\n"
-                            "    cancel(): Stop and remove the timer\n"
+                            "    restart(): Reset timer and ensure it's running\n\n"
-                            "    restart(): Reset timer to start from beginning\n\n"
                             "Example:\n"
                             "    def on_timer(timer, runtime):\n"
                             "        print(f'Timer {timer} fired at {runtime}ms')\n"
                             "        if runtime > 5000:\n"
-                            "            timer.cancel()\n"
+                            "            timer.stop()  # Stop but can restart later\n"
                             "    \n"
                             "    timer = mcrfpy.Timer('my_timer', on_timer, 1000)\n"
                             "    timer.pause()  # Pause timer\n"
                             "    timer.resume() # Resume timer\n"
-                            "    timer.once = True  # Make it one-shot"),
+                            "    timer.stop()   # Stop completely\n"
+                            "    timer.start()  # Restart from beginning"),
         .tp_methods = PyTimer::methods,
         .tp_getset = PyTimer::getsetters,
         .tp_init = (initproc)PyTimer::init,

src/Timer.cpp

@@ -4,14 +4,14 @@
 #include "McRFPy_API.h"
 #include "GameEngine.h"
 
-Timer::Timer(PyObject* _target, int _interval, int now, bool _once)
+Timer::Timer(PyObject* _target, int _interval, int now, bool _once, bool _start)
 : callback(std::make_shared<PyCallable>(_target)), interval(_interval), last_ran(now),
-  paused(false), pause_start_time(0), total_paused_time(0), once(_once)
+  paused(false), pause_start_time(0), total_paused_time(0), once(_once), stopped(!_start)
 {}
 
 Timer::Timer()
 : callback(std::make_shared<PyCallable>(Py_None)), interval(0), last_ran(0),
-  paused(false), pause_start_time(0), total_paused_time(0), once(false)
+  paused(false), pause_start_time(0), total_paused_time(0), once(false), stopped(true)
 {}
 
 Timer::~Timer() {
@@ -22,24 +22,24 @@ Timer::~Timer() {
 
 bool Timer::hasElapsed(int now) const
 {
-    if (paused) return false;
+    if (paused || stopped) return false;
     return now >= last_ran + interval;
 }
 
 bool Timer::test(int now)
 {
-    if (!callback || callback->isNone()) return false;
+    if (!callback || callback->isNone() || stopped) return false;
-    
+
     if (hasElapsed(now))
     {
         last_ran = now;
-        
+
         // Get the PyTimer wrapper from cache to pass to callback
         PyObject* timer_obj = nullptr;
         if (serial_number != 0) {
             timer_obj = PythonObjectCache::getInstance().lookup(serial_number);
         }
-        
+
         // Build args: (timer, runtime) or just (runtime) if no wrapper found
         PyObject* args;
         if (timer_obj) {
@@ -48,10 +48,10 @@ bool Timer::test(int now)
             // Fallback to old behavior if no wrapper found
             args = Py_BuildValue("(i)", now);
         }
-        
+
         PyObject* retval = callback->call(args, NULL);
         Py_DECREF(args);
-        
+
         if (!retval)
         {
             std::cerr << "Timer callback raised an exception:" << std::endl;
@@ -63,16 +63,16 @@ bool Timer::test(int now)
                 McRFPy_API::signalPythonException();
             }
         } else if (retval != Py_None)
-        {   
+        {
             std::cout << "Timer returned a non-None value. It's not an error, it's just not being saved or used." << std::endl;
             Py_DECREF(retval);
         }
-        
+
-        // Handle one-shot timers
+        // Handle one-shot timers: stop but preserve callback for potential restart
         if (once) {
-            cancel();
+            stopped = true;  // Will be removed from map by testTimers(), but callback preserved
         }
-        
+
         return true;
     }
     return false;
@@ -101,23 +101,41 @@ void Timer::restart(int current_time)
 {
     last_ran = current_time;
     paused = false;
+    stopped = false;  // Ensure timer is running
     pause_start_time = 0;
     total_paused_time = 0;
 }
 
-void Timer::cancel()
+void Timer::start(int current_time)
 {
-    // Cancel by setting callback to None
+    // Start/resume the timer - clear stopped flag, reset progress
-    callback = std::make_shared<PyCallable>(Py_None);
+    stopped = false;
+    paused = false;
+    last_ran = current_time;
+    pause_start_time = 0;
+    total_paused_time = 0;
+}
+
+void Timer::stop()
+{
+    // Stop the timer - it will be removed from engine map, but callback is preserved
+    stopped = true;
+    paused = false;
+    pause_start_time = 0;
+    total_paused_time = 0;
 }
 
 bool Timer::isActive() const
 {
-    return callback && !callback->isNone() && !paused;
+    return callback && !callback->isNone() && !paused && !stopped;
 }
 
 int Timer::getRemaining(int current_time) const
 {
+    if (stopped) {
+        // When stopped, progress is reset - full interval remaining
+        return interval;
+    }
     if (paused) {
         // When paused, calculate time remaining from when it was paused
         int elapsed_when_paused = pause_start_time - last_ran;
@@ -129,6 +147,10 @@ int Timer::getRemaining(int current_time) const
 
 int Timer::getElapsed(int current_time) const
 {
+    if (stopped) {
+        // When stopped, progress is reset
+        return 0;
+    }
     if (paused) {
         return pause_start_time - last_ran;
     }

src/Timer.h

@@ -17,37 +17,42 @@ private:
     bool paused;
     int pause_start_time;
     int total_paused_time;
-    
+
     // One-shot timer support
     bool once;
+
+    // Stopped state: timer is not in engine map, but callback is preserved
+    bool stopped;
     
 public:
     uint64_t serial_number = 0;  // For Python object cache
-    
+
     Timer(); // for map to build
-    Timer(PyObject* target, int interval, int now, bool once = false);
+    Timer(PyObject* target, int interval, int now, bool once = false, bool start = true);
     ~Timer();
-    
+
     // Core timer functionality
     bool test(int now);
     bool hasElapsed(int now) const;
-    
+
     // Timer control methods
     void pause(int current_time);
     void resume(int current_time);
     void restart(int current_time);
-    void cancel();
+    void start(int current_time);   // Clear stopped flag, reset progress
-    
+    void stop();                     // Set stopped flag, preserve callback
+
     // Timer state queries
     bool isPaused() const { return paused; }
-    bool isActive() const;
+    bool isStopped() const { return stopped; }
+    bool isActive() const;  // Running: not paused AND not stopped AND has callback
     int getInterval() const { return interval; }
     void setInterval(int new_interval) { interval = new_interval; }
     int getRemaining(int current_time) const;
     int getElapsed(int current_time) const;
     bool isOnce() const { return once; }
     void setOnce(bool value) { once = value; }
-    
+
     // Callback management
     PyObject* getCallback();
     void setCallback(PyObject* new_callback);

tests/unit/api_timer_test.py

@@ -1,70 +1,126 @@
 #!/usr/bin/env python3
-"""Test for mcrfpy.setTimer() and delTimer() methods"""
+"""Test for mcrfpy.Timer class - replaces old setTimer/delTimer tests (#173)"""
 import mcrfpy
 import sys
 
 def test_timers():
-    """Test timer API methods"""
+    """Test Timer class API"""
-    print("Testing mcrfpy timer methods...")
+    print("Testing mcrfpy.Timer class...")
-    
+
     # Test 1: Create a simple timer
     try:
         call_count = [0]
-        def simple_callback(runtime):
+        def simple_callback(timer, runtime):
             call_count[0] += 1
             print(f"Timer callback called, count={call_count[0]}, runtime={runtime}")
-        
+
-        mcrfpy.setTimer("test_timer", simple_callback, 100)
+        timer = mcrfpy.Timer("test_timer", simple_callback, 100)
-        print("✓ setTimer() called successfully")
+        print("✓ Timer() created successfully")
+        print(f"  Timer repr: {timer}")
     except Exception as e:
-        print(f"✗ setTimer() failed: {e}")
+        print(f"✗ Timer() failed: {e}")
         print("FAIL")
         return
-    
+
-    # Test 2: Delete the timer
+    # Test 2: Stop the timer
     try:
-        mcrfpy.delTimer("test_timer")
+        timer.stop()
-        print("✓ delTimer() called successfully")
+        print("✓ timer.stop() called successfully")
+        assert timer.stopped == True, "Timer should be stopped"
+        print(f"  Timer after stop: {timer}")
     except Exception as e:
-        print(f"✗ delTimer() failed: {e}")
+        print(f"✗ timer.stop() failed: {e}")
         print("FAIL")
         return
-    
+
-    # Test 3: Delete non-existent timer (should not crash)
+    # Test 3: Restart the timer
     try:
-        mcrfpy.delTimer("nonexistent_timer")
+        timer.start()
-        print("✓ delTimer() accepts non-existent timer names")
+        print("✓ timer.start() called successfully")
+        assert timer.stopped == False, "Timer should not be stopped"
+        assert timer.active == True, "Timer should be active"
+        timer.stop()  # Clean up
     except Exception as e:
-        print(f"✗ delTimer() failed on non-existent timer: {e}")
+        print(f"✗ timer.start() failed: {e}")
         print("FAIL")
         return
-    
+
-    # Test 4: Create multiple timers
+    # Test 4: Create timer with start=False
     try:
-        def callback1(rt): pass
+        def callback2(timer, runtime): pass
-        def callback2(rt): pass
+        timer2 = mcrfpy.Timer("timer2", callback2, 500, start=False)
-        def callback3(rt): pass
+        assert timer2.stopped == True, "Timer with start=False should be stopped"
-        
+        print("✓ Timer with start=False created in stopped state")
-        mcrfpy.setTimer("timer1", callback1, 500)
+        timer2.start()
-        mcrfpy.setTimer("timer2", callback2, 750)
+        assert timer2.active == True, "Timer should be active after start()"
-        mcrfpy.setTimer("timer3", callback3, 250)
+        timer2.stop()
+    except Exception as e:
+        print(f"✗ Timer with start=False failed: {e}")
+        print("FAIL")
+        return
+
+    # Test 5: Create multiple timers
+    try:
+        def callback3(t, rt): pass
+
+        t1 = mcrfpy.Timer("multi1", callback3, 500)
+        t2 = mcrfpy.Timer("multi2", callback3, 750)
+        t3 = mcrfpy.Timer("multi3", callback3, 250)
         print("✓ Multiple timers created successfully")
-        
+
         # Clean up
-        mcrfpy.delTimer("timer1")
+        t1.stop()
-        mcrfpy.delTimer("timer2")
+        t2.stop()
-        mcrfpy.delTimer("timer3")
+        t3.stop()
-        print("✓ Multiple timers deleted successfully")
+        print("✓ Multiple timers stopped successfully")
     except Exception as e:
         print(f"✗ Multiple timer test failed: {e}")
         print("FAIL")
         return
-    
+
-    print("\nAll timer API tests passed")
+    # Test 6: mcrfpy.timers collection
+    try:
+        # Create a timer that's running
+        running_timer = mcrfpy.Timer("running_test", callback3, 1000)
+
+        timers = mcrfpy.timers
+        assert isinstance(timers, tuple), "mcrfpy.timers should be a tuple"
+        print(f"✓ mcrfpy.timers returns tuple with {len(timers)} timer(s)")
+
+        # Clean up
+        running_timer.stop()
+    except Exception as e:
+        print(f"✗ mcrfpy.timers test failed: {e}")
+        print("FAIL")
+        return
+
+    # Test 7: active property is read-write
+    try:
+        active_timer = mcrfpy.Timer("active_test", callback3, 1000)
+        assert active_timer.active == True, "New timer should be active"
+
+        active_timer.active = False  # Should pause
+        assert active_timer.paused == True, "Timer should be paused after active=False"
+
+        active_timer.active = True  # Should resume
+        assert active_timer.active == True, "Timer should be active after active=True"
+
+        active_timer.stop()
+        active_timer.active = True  # Should restart from stopped
+        assert active_timer.active == True, "Timer should restart from stopped via active=True"
+
+        active_timer.stop()
+        print("✓ active property is read-write")
+    except Exception as e:
+        print(f"✗ active property test failed: {e}")
+        print("FAIL")
+        return
+
+    print("\nAll Timer API tests passed")
     print("PASS")
 
 # Run the test
 test_timers()
 
 # Exit cleanly
-sys.exit(0)
+sys.exit(0)

tests/unit/test_grid_cell_events.py

@@ -68,9 +68,7 @@ def test_cell_hover():
     automation.moveTo(150, 150)
     automation.moveTo(200, 200)
 
-    def check_hover(runtime):
+    def check_hover(timer, runtime):
-        mcrfpy.delTimer("check_hover")
-
         print(f"  Enter events: {len(enter_events)}, Exit events: {len(exit_events)}")
         print(f"  Hovered cell: {grid.hovered_cell}")
 
@@ -82,7 +80,7 @@ def test_cell_hover():
         # Continue to click test
         test_cell_click()
 
-    mcrfpy.setTimer("check_hover", check_hover, 200)
+    mcrfpy.Timer("check_hover", check_hover, 200, once=True)
 
 
 def test_cell_click():
@@ -105,9 +103,7 @@ def test_cell_click():
 
     automation.click(200, 200)
 
-    def check_click(runtime):
+    def check_click(timer, runtime):
-        mcrfpy.delTimer("check_click")
-
         print(f"  Click events: {len(click_events)}")
 
         if len(click_events) >= 1:
@@ -118,7 +114,7 @@ def test_cell_click():
         print("\n=== All grid cell event tests passed! ===")
         sys.exit(0)
 
-    mcrfpy.setTimer("check_click", check_click, 200)
+    mcrfpy.Timer("check_click", check_click, 200, once=True)
 
 
 if __name__ == "__main__":

tests/unit/test_headless_click.py

@@ -36,9 +36,7 @@ def test_headless_click():
     automation.click(150, 150)
 
     # Give time for events to process
-    def check_results(runtime):
+    def check_results(timer, runtime):
-        mcrfpy.delTimer("check_click")  # Clean up timer
-
         if len(start_clicks) >= 1:
             print(f"  - Click received: {len(start_clicks)} click(s)")
             # Verify position
@@ -53,7 +51,7 @@ def test_headless_click():
             print(f"  - No clicks received: FAIL")
             sys.exit(1)
 
-    mcrfpy.setTimer("check_click", check_results, 200)
+    mcrfpy.Timer("check_click", check_results, 200, once=True)
 
 
 def test_click_miss():
@@ -84,9 +82,7 @@ def test_click_miss():
     print("  Clicking outside frame at (50, 50)...")
     automation.click(50, 50)
 
-    def check_miss_results(runtime):
+    def check_miss_results(timer, runtime):
-        mcrfpy.delTimer("check_miss")  # Clean up timer
-
         if miss_count[0] == 0:
             print("  - No click on miss: PASS")
             # Now run the main click test
@@ -95,7 +91,7 @@ def test_click_miss():
             print(f"  - Unexpected {miss_count[0]} click(s): FAIL")
             sys.exit(1)
 
-    mcrfpy.setTimer("check_miss", check_miss_results, 200)
+    mcrfpy.Timer("check_miss", check_miss_results, 200, once=True)
 
 
 def test_position_tracking():

tests/unit/test_mouse_enter_exit.py

@@ -153,7 +153,7 @@ def test_enter_exit_simulation():
     automation.moveTo(50, 50)
 
     # Give time for callbacks to execute
-    def check_results(runtime):
+    def check_results(timer, runtime):
         global enter_count, exit_count
 
         if enter_count >= 1 and exit_count >= 1:
@@ -166,7 +166,7 @@ def test_enter_exit_simulation():
             print("\n=== Basic Mouse Enter/Exit tests passed! ===")
             sys.exit(0)
 
-    mcrfpy.setTimer("check", check_results, 200)
+    mcrfpy.Timer("check", check_results, 200, once=True)
 
 
 def run_basic_tests():

tests/unit/test_on_move.py

@@ -57,9 +57,7 @@ def test_on_move_fires():
     automation.moveTo(200, 200)
     automation.moveTo(250, 250)
 
-    def check_results(runtime):
+    def check_results(timer, runtime):
-        mcrfpy.delTimer("check_move")
-
         if move_count[0] >= 2:
             print(f"  - on_move fired {move_count[0]} times: PASS")
             print(f"    Positions: {positions[:5]}...")
@@ -71,7 +69,7 @@ def test_on_move_fires():
             print("\n=== on_move basic tests passed! ===")
             sys.exit(0)
 
-    mcrfpy.setTimer("check_move", check_results, 200)
+    mcrfpy.Timer("check_move", check_results, 200, once=True)
 
 
 def test_on_move_not_outside():
@@ -99,9 +97,7 @@ def test_on_move_not_outside():
     automation.moveTo(60, 60)
     automation.moveTo(70, 70)
 
-    def check_results(runtime):
+    def check_results(timer, runtime):
-        mcrfpy.delTimer("check_outside")
-
         if move_count[0] == 0:
             print("  - No on_move outside bounds: PASS")
             # Chain to the firing test
@@ -110,7 +106,7 @@ def test_on_move_not_outside():
             print(f"  - Unexpected {move_count[0]} move(s) outside bounds: FAIL")
             sys.exit(1)
 
-    mcrfpy.setTimer("check_outside", check_results, 200)
+    mcrfpy.Timer("check_outside", check_results, 200, once=True)
 
 
 def test_all_types_have_on_move():

tests/unit/test_step_function.py

@@ -63,13 +63,13 @@ def run_tests():
     print("Test 5: Timer fires after step() advances past interval")
     timer_fired = [False]  # Use list for mutable closure
 
-    def on_timer(runtime):
+    def on_timer(timer, runtime):
-        """Timer callback - receives runtime in ms"""
+        """Timer callback - receives timer object and runtime in ms"""
         timer_fired[0] = True
         print(f"    Timer fired at simulation time={runtime}ms")
 
     # Set a timer for 500ms
-    mcrfpy.setTimer("test_timer", on_timer, 500)
+    test_timer = mcrfpy.Timer("test_timer", on_timer, 500)
 
     # Step 600ms - timer should fire (500ms interval + some buffer)
     dt = mcrfpy.step(0.6)
@@ -88,7 +88,7 @@ def run_tests():
         print("  Skipping timer test in windowed mode")
 
     # Clean up
-    mcrfpy.delTimer("test_timer")
+    test_timer.stop()
     print()
 
     # Test 6: Error handling - invalid argument type

tests/unit/test_timer_once.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """
 Test once=True timer functionality
+Uses mcrfpy.step() to advance time in headless mode.
 """
 import mcrfpy
 import sys
@@ -18,20 +19,8 @@ def repeat_callback(timer, runtime):
     repeat_count += 1
     print(f"Repeat timer fired! Count: {repeat_count}, Timer.once: {timer.once}")
 
-def check_results(runtime):
-    print(f"\nFinal results:")
-    print(f"Once timer fired {once_count} times (expected: 1)")
-    print(f"Repeat timer fired {repeat_count} times (expected: 3+)")
-    
-    if once_count == 1 and repeat_count >= 3:
-        print("PASS: Once timer fired exactly once, repeat timer fired multiple times")
-        sys.exit(0)
-    else:
-        print("FAIL: Timer behavior incorrect")
-        sys.exit(1)
-
 # Set up the scene
-test_scene = mcrfpy.Scene("test_scene") 
+test_scene = mcrfpy.Scene("test_scene")
 test_scene.activate()
 
 # Create timers
@@ -43,5 +32,20 @@ print("\nCreating repeat timer with once=False (default)...")
 repeat_timer = mcrfpy.Timer("repeat_timer", repeat_callback, 100)
 print(f"Timer: {repeat_timer}, once={repeat_timer.once}")
 
-# Check results after 500ms
+# Advance time using step() to let timers fire
-mcrfpy.setTimer("check", check_results, 500)
+# Step 600ms total - once timer (100ms) fires once, repeat timer fires ~6 times
+print("\nAdvancing time with step()...")
+for i in range(6):
+    mcrfpy.step(0.1)  # 100ms each
+
+# Check results
+print(f"\nFinal results:")
+print(f"Once timer fired {once_count} times (expected: 1)")
+print(f"Repeat timer fired {repeat_count} times (expected: 3+)")
+
+if once_count == 1 and repeat_count >= 3:
+    print("PASS: Once timer fired exactly once, repeat timer fired multiple times")
+    sys.exit(0)
+else:
+    print("FAIL: Timer behavior incorrect")
+    sys.exit(1)

tests/unit/working_timer_test.py

@@ -23,20 +23,28 @@ caption = mcrfpy.Caption(pos=(150, 150),
 caption.font_size = 24
 ui.append(caption)
 
-# Timer callback with correct signature
+# Timer callback with new signature (timer, runtime)
-def timer_callback(runtime):
+def timer_callback(timer, runtime):
     print(f"\n✓ Timer fired successfully at runtime: {runtime}")
-    
+
     # Take screenshot
     filename = f"timer_success_{int(runtime)}.png"
     result = automation.screenshot(filename)
     print(f"Screenshot saved: {filename} - Result: {result}")
-    
+
-    # Cancel timer and exit
+    # Stop timer and exit
-    mcrfpy.delTimer("success_timer")
+    timer.stop()
     print("Exiting...")
     mcrfpy.exit()
 
-# Set timer
+# Create timer (new API)
-mcrfpy.setTimer("success_timer", timer_callback, 1000)
+success_timer = mcrfpy.Timer("success_timer", timer_callback, 1000, once=True)
-print("Timer set for 1 second. Game loop starting...")
+print("Timer set for 1 second. Using step() to advance time...")
+
+# In headless mode, advance time manually
+for i in range(11):  # 1100ms total
+    mcrfpy.step(0.1)
+
+print("PASS")
+import sys
+sys.exit(0)