RealTimeEvents – Real-World Time Triggers (MZ)

This plugin reads the ACTUAL real-world clock and fires events when a

configured time of day arrives in real life. It is a 1:1 clock:

one real second = one game second, 24 real hours = 24 game hours.

(This is NOT a sped-up in-game day/night cycle.)

----------------------------------------------------------------------------

CORE CONCEPTS

----------------------------------------------------------------------------

1) TIMEZONE

   - "System Local" reads the player's own device clock (and follows their

     Daylight Saving automatically). Use this if you want each player's

     events tied to THEIR local time (e.g. a shop that opens at 6pm wherever

     the player lives).

   - "Fixed UTC Offset" reads one canonical zone for everyone. Use this for

     global/synchronized events (e.g. a world boss that appears at 20:00 JST

     for every player on Earth = Fixed offset +9).

2) STARTING POINT (offset)

   The "starting point" shifts the whole clock so any real moment can map to

   any clock time you like. Two ways to set it:

     - "Set Starting Point (Offset)" : add/subtract H:M:S from the clock.

     - "Set Starting Point (Anchor Now)" : "make right now read as 08:00".

   Combine timezone + starting point and the player can define any unique

   starting point that coincides with any timezone -- typically via an

   in-game options menu that calls these plugin commands.

3) TRIGGERS

   Each trigger is either:

     - POINT : at H:M:S it turns ON a Switch and/or runs a Common Event.

               (Repeats daily, or once ever.)

     - WINDOW: the Switch stays ON during a time range and OFF outside it

               (perfect for an "isNight" / "shopOpen" flag). The Common

               Event runs once each time the window is entered. A WINDOW

               trigger fully OWNS its Switch and will force it on/off.

   "Active Days" (optional) limits a trigger to certain weekdays.

   0=Sunday, 1=Monday ... 6=Saturday. Leave blank = every day.

   Wrap-around windows are supported: End 06:00 with Start 22:00 means

   10pm through 6am the next morning.

----------------------------------------------------------------------------

QUICK SETUP EXAMPLE

----------------------------------------------------------------------------

Goal: a "Night Market" that is open from 6:00 PM to 11:00 PM local time.

  - Add a Time Trigger:

      Name        : NightMarket

      Mode        : Window

      Start Hour  : 18   Start Minute : 0

      End Hour    : 23   End Minute   : 0

      Switch      : (pick a switch, e.g. #10 "MarketOpen")

      Common Event: (optional, runs when it opens)

  - In your map events, gate the market NPCs behind Switch #10.

Goal: a global event at exactly 20:00 Tokyo time for all players.

  - Timezone Mode = Fixed, Offset Hours = 9, Minutes = 0.

  - Add a POINT trigger at Hour 20, Minute 0 that runs a Common Event.

----------------------------------------------------------------------------

LETTING THE PLAYER CHOOSE (in-game menu pattern)

----------------------------------------------------------------------------

Build a simple event/menu with "Show Choices", then per choice call:

  - Plugin Command > Set Timezone (Fixed Offset)  [their region]

  - Plugin Command > Set Starting Point (Anchor Now) [their chosen time]

Everything persists in the save file.

----------------------------------------------------------------------------

SCRIPT HELPERS (for Conditional Branch > Script, or Control Variables > Script)

----------------------------------------------------------------------------

  RealTimeEvents.hour()            -> 0-23

  RealTimeEvents.minute()          -> 0-59

  RealTimeEvents.second()          -> 0-59

  RealTimeEvents.dayOfWeek()       -> 0 (Sun) - 6 (Sat)

  RealTimeEvents.secondsOfDay()    -> 0-86399

  RealTimeEvents.minutesOfDay()    -> 0-1439

  RealTimeEvents.timeString(true)  -> "18:30" (false = "6:30 PM")

  RealTimeEvents.isBetween(22,0,6,0) -> true if it's currently 10pm..6am

----------------------------------------------------------------------------

NOTES

----------------------------------------------------------------------------

- Trigger names must be UNIQUE.

- Triggers are checked while on the Map scene (Common Events need the map).

  Live variables also update on the map. If a POINT time passes during a

  menu/battle, "Catch Up Missed Triggers" will fire it when you return.

- Because this reads the device clock, a player can change their clock to

  game the timers. Use Fixed offset + server logic if you need it tamper-proof.

Free to use and edit in commercial and non-commercial projects.

FREQUENTLY ASKED QUESTIONS

Q: Is this a day/night cycle that speeds up time?

A: No. It's locked to the real clock 1:1. For an accelerated in-game day, use a

   different plugin.

Q: Does it work while the game is closed?

A: It reads the clock while the player is on the map. With "Catch Up Missed

   Triggers" ON, a time that passed while the game was closed fires when the

   player returns to the map.

Q: Do triggers fire during battles or menus?

A: Common Events run on the map, so a time reached mid-battle/menu is handled on

   return via catch-up. Switches update on the map.

Q: Can players cheat by changing their device clock?

A: Yes — any real-clock plugin can be gamed this way. For tamper-proof timing,

   validate against a server. For single-player flavor, quests, and shop hours,

   this is the standard approach.

Q: How do I show the time on screen?

A: Point the "Time String Variable" at a variable and show \V[n] in a message or

   HUD. Separate Hour/Minute/Second variables are also provided.

Q: Do half-hour timezones (India, etc.) work?

A: Yes. Set Fixed Offset Hours 5 and Minutes 30.

Q: A trigger fired twice or won't fire again — why?

A: Trigger names must be UNIQUE. To let a Point trigger fire again, use "Reset

   One Trigger" or set Repeat to Daily.

Q: Does it save and load correctly?

A: Yes. All runtime settings and per-trigger memory are stored in the save.

💬 Feedback, Support & Custom Development

Thank you for checking out this project! If you use this plugin, I'd greatly appreciate it if you could leave a review describing your experience. Your feedback helps improve future updates, assists other developers in making informed decisions, and supports continued development.

If you have any questions, bug reports, feature suggestions, or run into any problems while using this plugin, please don't hesitate to contact me.

I'm also available for custom RPG Maker plugin development. Whether you need a completely new plugin, modifications to an existing one, compatibility fixes, or help implementing a unique gameplay system, I'd be happy to discuss your project.

📧 Contact: rpgmakerplugins@protonmail.com

I do my best to respond as quickly as possible and look forward to helping you bring your ideas to life. Thank you for your support!