MacOS Minecraft Timer for (Technically Inclined) Parents

Java does not play well with Apple’s Screen TimeJava does not play well with Apple’s Screen Time

UPDATE 29th of August 2022: I have created a GitHub repository under the MIT License for this.

IF YOU ARE A PARENT and your family has at least one or two Apple devices, one of them being a MacBook, you most likely have Minecraft installed on it. And suppose you are a parent who manages the time your kids spend on these devices using Apple’s Screen Time functionality. In that case, you probably know that using Minecraft on a MacBook doesn’t get included in the list of apps you can monitor. This is because Minecraft runs on Java, and Java is omitted from that list. The most probable reason is that Java is an old, not entirely secure technology that is not included natively in the Apple ecosystem. Request for being able to monitor Minecraft has been aired. Still, it is deemed not worthy of recognition by Mojang, and Apple, I guess, is in the same boat.

So that leaves us, parents, to figure this out ourselves. Enter my very crude attempt to at least go in that direction. I have created a script that, utilizing macOS functionalities, will periodically check to see if Java (and Minecraft) is running. After a given time, it will issue a warning saying that the pre-determined time is up. Now, I am not, and I repeat, not a macOS/Shell programmer, so this is a crude, limited and probably even a poor attempt to partially solve this issue. So if you are going to use it, use it with caution and at your own risk, etcetera. Also, please feel free to build upon it if you share your improvements with others. And I should mention that you will need to be a tad knowledgeable about fiddling with macOS files, permissions and so on if you want to give this a shot. Also, if you start adding this to a MacBook with multiple users, one of them being your kid’s account, you will probably run into file permission issues.

It has only been created and tested on macOS Monterey 12.5.1. Basically, I have just thrown it out here for grabs. I, unfortunately, do not have time to try it on other macOS platforms, make a friendly installer etc.

This is how it works: The main script (here called MinecraftTimer.sh) will have to reside somewhere on the system where the kids usually don’t look. In this example, I placed it in the /usr/local/bin/ folder. This script needs to be executable, so in macOS Terminal, you need to do this by this command:

% chmod 755 /usr/local/bin/MinecraftTimer.sh

You can also test the script on your version of macOS via Terminal to see if any issues pop up.

A launchd file (or .plist file - a kind of Mac XML file) can be triggered whenever the current user logs in and start using the Mac. And this can in turn trigger a script like the MinecraftTimer.sh script. This .plist file is placed in the ~/Library/LaunchAgents/ folder (the current user’s LaunchAgents folder). It can be re-triggered periodically, so that is what this one does, launching, in turn, our MinecraftTimer.sh script every 60 seconds. Then this script saves a preference file (in the /tmp/ directory) which it uses to keep time throughout the day — even if Minecraft quits and then gets relaunched later. If this preference or log file is before midnight on the current day, it creates a fresh one, so the timer is resetting every day.

A warning is triggered just before the allotted time ends, asking the gamer to please save and quit unless they have permission to continue. I have not included a quit-and-disable-Java” command in the script. This is because I believe in communicating with my kids regarding their limits, not being forceful unless I absolutely have to. Still, you can modify this if you know how.

Below is the main Shell script, which should be placed in the /usr/local/bin/ folder. If you put it elsewhere, you will need to change the path to the location in the XML/launchd file below. Note that you can change the allowed time by changing the MAX_TIME=60 variable to any minutes you want. Say, for two hours, it will be MAX_TIME=120 and so on.


# set max time for java/Minecraft to run in minutes
CURRENT_TIME=$(date +%s)

# check to see if java is running
if (ps aux | grep java | grep -v grep > /dev/null)

    # check to see if our log file exist
    # if not, we create it
    if !(test -f "$LOGFILE")
        # it is not there, so let us create a new temporary file
        LOGFILE=$(mktemp /tmp/minecraft-timer-log.txt)
        # check to see if the file is from yesterday
        LOG_CREATION_DATE=$(stat -f %B $LOGFILE)
        MIDNIGHT=$(($CURRENT_TIME - ($CURRENT_TIME % 86400)))
            # delete old log file
            rm $LOGFILE
            # create a fresh log file
            LOGFILE=$(mktemp /tmp/minecraft-timer-log.txt)
    # read the timestamp from log file, if it exsist
    # see if we have something
    if (test -z "$TEST_LOG")
        # no timestamp found, so we set it to the current time
        echo "LOG_DATESTAMP=$(date +%s)" > "$LOGFILE"
        echo "LOG_TIMER"="0" >> "$LOGFILE"
        echo "LAST_SESSION_TIMER"="0" >> "$LOGFILE"
        # timestamp found
        source $LOGFILE

        # append current time to the timestamp        

        # check if we have spent too much time
        if !(($TOTAL_TIME_SPENT >= $MAX_TIME))
            # are we close to one minute until time limit then issue a warning
            # give it two minutes if the launch interval is 60 seconds
            if (($TOTAL_TIME_SPENT >= $WARNING_TIME))
                # time is up - issuing warning
                osascript -e 'set theDialogText to "Time is up for Minecraft today! Save and quit now, unless you have premission from your parents to continue."
                display dialog theDialogText with icon caution'
        # write new timer value in our log file
        sed -i -e "s/LOG_TIMER=.*/LOG_TIMER=${TIME_DIFF_MINS}/" $LOGFILE
    # if java is not running, and if we have a log file present
    # we need to create a new timestamp in the log so that we can 
    # continue our timer from when java was closed
    if (test -f "$LOGFILE")
        # read the file
        source $LOGFILE

        # add LOG_TIMER (current session) to the LAST_SESSION

        # reset LOG_TIMER so that it does not constantly get added to the LAST_SESSION
        sed -i -e "s/LOG_TIMER=.*/LOG_TIMER=0/" $LOGFILE

        # write new timestamp value in our log file

And here is the launchd file that should be placed in the ~/Library/LaunchAgents/ folder. Name it something unique like com.your_name.MinecraftTimer.plist. If you like, you can change the StartInterval to something different. The 60 stands for 60 seconds, so the script above gets executed every minute.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">


Minecraft macOS Screen Time Coding

Previous post
Today’s Tittilating Treasures 🖼 Visit today’s image iOS Can Stop VPNs From Working as Expected—and Expose Your Data https://t.co/8eziaOGYza
Next post
Today’s Tittilating Treasures 🖼 Visit today’s image The Algorithm Giveth and Taketh Away https://t.co/B3Wkq77Ywe