john/McRogueFace
1
0
Fork 0
Code Issues 27 Pull requests Projects Releases Wiki Activity

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

Browse source 
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>
This commit is contained in:
John McCardle 2026-01-03 19:21:37 -05:00
commit 5d41292bf6
16 changed files with 440 additions and 262 deletions
Download patch file Download diff file Expand all files Collapse all files

42
src/GameEngine.cpp
View file

@ -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)
{
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);
}
// Note: manageTimer() removed in #173 - use Timer objects directly
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++;
}
}
}

2
src/GameEngine.h
View file

@ -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; }

73
src/McRFPy_API.cpp
View file

@ -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,
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.")
)},
// Note: setTimer and delTimer removed in #173 - use Timer objects instead
{"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
const char* name;
PyObject* callable;
int interval;
if (!PyArg_ParseTuple(args, "sOi", &name, &callable, &interval)) return NULL;
game->manageTimer(name, callable, interval);
Py_INCREF(Py_None);
return Py_None;
}
// #173: Get all timers as a tuple of Python Timer objects
PyObject* McRFPy_API::api_get_timers()
{
if (!game) {
return PyTuple_New(0);
}
PyObject* McRFPy_API::_delTimer(PyObject* self, PyObject* args) {
const char* name;
if (!PyArg_ParseTuple(args, "s", &name)) return NULL;
game->manageTimer(name, NULL, 0);
Py_INCREF(Py_None);
return Py_None;
// Count timers that have Python wrappers
std::vector<PyObject*> timer_objs;
for (auto& pair : game->timers) {
auto& timer = pair.second;
if (timer && timer->serial_number != 0) {
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

7
src/McRFPy_API.h
View file

@ -43,9 +43,7 @@ public:
// Internal - used by PySceneObject::activate()
static PyObject* _setScene(PyObject*, PyObject*);
// timer control
static PyObject* _setTimer(PyObject*, PyObject*);
static PyObject* _delTimer(PyObject*, PyObject*);
// Note: setTimer/delTimer removed in #173 - use Timer objects instead
// #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;

234
src/PyTimer.cpp
View file

@ -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
if (!PyArg_ParseTupleAndKeywords(args, kwds, "sOi|p", const_cast<char**>(kwlist),
&name, &callback, &interval, &once)) {
int once = 0; // Use int for bool parameter
int start = 1; // Default: start=True
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
self->data = std::make_shared<Timer>(callback, interval, current_time, (bool)once);
// Create the timer with start parameter
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
if (Resources::game) {
// Register with game engine only if starting
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)) {
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();
self->data->resume(current_time);
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,
MCRF_PROPERTY(active, "Whether the timer is active and not paused (bool, read-only). False if cancelled or paused."), NULL},
{"stopped", (getter)PyTimer::get_stopped, 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}
};

25
src/PyTimer.h
View file

@ -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"
" callback (callable): The callback function\n"
" stopped (bool): Whether timer is stopped (read-only)\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 to start from beginning\n\n"
" restart(): Reset timer and ensure it's running\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,

60
src/Timer.cpp
View file

@ -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
callback = std::make_shared<PyCallable>(Py_None);
// Start/resume the timer - clear stopped flag, reset progress
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;
}

23
src/Timer.h
View file

@ -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);

128
tests/unit/api_timer_test.py
View file

@ -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"""
print("Testing mcrfpy timer methods...")
"""Test Timer class API"""
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)
print("✓ setTimer() called successfully")
timer = mcrfpy.Timer("test_timer", simple_callback, 100)
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")
print("✓ delTimer() called successfully")
timer.stop()
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")
print("✓ delTimer() accepts non-existent timer names")
timer.start()
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(rt): pass
def callback3(rt): pass
mcrfpy.setTimer("timer1", callback1, 500)
mcrfpy.setTimer("timer2", callback2, 750)
mcrfpy.setTimer("timer3", callback3, 250)
def callback2(timer, runtime): pass
timer2 = mcrfpy.Timer("timer2", callback2, 500, start=False)
assert timer2.stopped == True, "Timer with start=False should be stopped"
print("✓ Timer with start=False created in stopped state")
timer2.start()
assert timer2.active == True, "Timer should be active after start()"
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")
mcrfpy.delTimer("timer2")
mcrfpy.delTimer("timer3")
print("✓ Multiple timers deleted successfully")
t1.stop()
t2.stop()
t3.stop()
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)

12
tests/unit/test_grid_cell_events.py
View file

@ -68,9 +68,7 @@ def test_cell_hover():
automation.moveTo(150, 150)
automation.moveTo(200, 200)
def check_hover(runtime):
mcrfpy.delTimer("check_hover")
def check_hover(timer, runtime):
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):
mcrfpy.delTimer("check_click")
def check_click(timer, runtime):
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__":

12
tests/unit/test_headless_click.py
View file

@ -36,9 +36,7 @@ def test_headless_click():
automation.click(150, 150)
# Give time for events to process
def check_results(runtime):
mcrfpy.delTimer("check_click") # Clean up timer
def check_results(timer, runtime):
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):
mcrfpy.delTimer("check_miss") # Clean up timer
def check_miss_results(timer, runtime):
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():

4
tests/unit/test_mouse_enter_exit.py
View file

@ -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():

12
tests/unit/test_on_move.py
View file

@ -57,9 +57,7 @@ def test_on_move_fires():
automation.moveTo(200, 200)
automation.moveTo(250, 250)
def check_results(runtime):
mcrfpy.delTimer("check_move")
def check_results(timer, runtime):
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):
mcrfpy.delTimer("check_outside")
def check_results(timer, runtime):
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():

8
tests/unit/test_step_function.py
View file

@ -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):
"""Timer callback - receives runtime in ms"""
def on_timer(timer, runtime):
"""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

34
tests/unit/test_timer_once.py
View file

@ -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
mcrfpy.setTimer("check", check_results, 500)
# Advance time using step() to let timers fire
# 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)

26
tests/unit/working_timer_test.py
View file

@ -23,20 +23,28 @@ caption = mcrfpy.Caption(pos=(150, 150),
caption.font_size = 24
ui.append(caption)
# Timer callback with correct signature
def timer_callback(runtime):
# Timer callback with new signature (timer, 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
mcrfpy.delTimer("success_timer")
# Stop timer and exit
timer.stop()
print("Exiting...")
mcrfpy.exit()
# Set timer
mcrfpy.setTimer("success_timer", timer_callback, 1000)
print("Timer set for 1 second. Game loop starting...")
# Create timer (new API)
success_timer = mcrfpy.Timer("success_timer", timer_callback, 1000, once=True)
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)