Version 0.19.0

Hey everyone, it's been a while since I last put an update on here. I've moved residences between this update and the last one, and encountered several problems with my internet connection, which all dug into my development time. However, now the new update is here. This one is focused on timed code and events. To put it simply, you can trigger both events and code on a delay. Want to give players limited time to solve a puzzle, trigger effects a certain amount of time after one another, or implement a live day/night cycle for your game? This update gives you the tools to do so.

However, before I start, I need to give a major warning: Ren'py version 8.1 introduced a bug that broke the functionality of the retain_after_load function. Because the pink engine relies heavily on this function, the pink engine should currently not be used on any ren'py version after 8.0.3. Save games will not load properly. I've informed the ren'py developer about this issue, and hope to see it solved with the next release.

Now, on to the content!

Timed Code and Events

• First off, there is a new global variable in the ren'py store that will be created at the start of every game. This is the otm_timer. This is the central timer for all OTM maps. It has two counters on it: otm_timer.time will give you the current game time in seconds (so the amount of seconds you've had an OTM map up without the timer being paused), otm_timer.raw_time will also give you the current game time in seconds, but will increase when you increment the timer. This way you can track gametime. All timed code and events make use of otm_timer.time.
• To add a timed event to the timer, use otm_timer.add_timed_event(time, event, event_id (optional), *args, **kwargs).
  
  • The time is the total game time at which the event needs to be triggered in seconds. So if you want to have an event occur in ten seconds, pass otm_timer.time + 10 as an argument. 
    
  • The event is the label of the event to be called. Note that all timed event calls are indeed calls, not jumps.
  • By giving an event_id, you attach an ID to the timer. That way, you have a reference for the remove_timed_event, remaining_time and exists functions. 
  • The args and kwargs will be passed on to the event when it is called.
• To add timed code to to the timer, use otm_timer.add_timed_code(time, code, code_id (optional))
  
  • The time is once again the total game time in seconds, as it is for events
  • The code is the code string to be executed. This needs to be valid python code, called in the context of the tiled_map.py file. So if you want to reference any renpy store variables, you need to explicitly call renpy.store, rather than just use the name.
  • code_id is the same as event_id, attaching a unique name to the timer for the purpose of other functions
• To increment the value of the timer, use otm_timer.increment(seconds). This will increase the current value of otm_timer.time by the given amount of seconds, thus bringing all timed code and events closer.
• To pause the OTM timer, use otm_timer.pause(). Otm_timer.time will not increase as long as the game is paused. There are also configuration options for automatically pausing during certain types of events. These are pink_otm_pause_timer_on_static_event, pink_otm_pause_timer_on_dynamic_event and pink_otm_pause_timer_on_continuing_event, all found in pink_config.rpy. 
• To unpause the OTM timer, use otm_timer.unpause().
• To remove timed code, use otm_timer.remove_timed_code(code_id). This way, you can prevent scheduled code from ever occurring.
• To remove a timed event, use otm_timer.remove_timed_event(event_id). This way, you can prevent a scheduled event call from ever occurring.
• To see the remaining time on a timed code or event, use the function otm_timer.remaining_time(code_id). This function will work for both codes and events. Good for dramatic countdowns, or have NPCs give reactions as a certain event comes closer.
• To check if a timer exists, use the function otm_timer.exists(code_id). This function will work for both code and events. It will return True if an timer with that code or event ID exists, False otherwise. 

Timed code and events are demonstrated in the new test rooms A25-27. 

Other stuff

• We do have one other piece of functionality that's been added to the pink engine this sprint. One of the users on our discord requested a function that would cause an NPC to start pursuing a target once a certain variable had been flipped, and teleport back to its starting position once that variable had been unflipped. This function is now available in standard_events.rpy, and is called pink_otm_pursuit_and_reset. You can check test room E32 for a demonstration.

A Merry Christmas (or other assorted wintery holidays) to all of you who read this, and may the next update take less long than this one.