View source for Add "Run PICO-8 Cartridge" Quick Action to MacOS

==Overview==
While there are a lot of tools available within IDEs that make it easier to run a PICO-8 Cartridge directly from the development platform, there isn’t many instructions on the interwebs to make PICO-8 just be more friendly to MacOS in General:

'''Here is how you create a Quick Action, in MacOS Finder, to start PICO-8 Cartridges'''

=== Conditions ===
* I use a Macbook 12”, the model ''without'' the fans. When running Visual Studio Code, i can reach average core temps of up to 197-205 degrees. When you are writing lua, that’s just silly overhead.
* Sublime Text is nice, but I prefer BBEdit with its instant formatting tools.
* I’m running Bitbucket, and Sourcetree to run a git repo, so i definitely want to host my dev files separately from the default folder.
* Changing the default config file to point to my dev folder is all good and well, but i still have to change the folder and then run the file.

=== Requirements ===
* I want to run a PICO-8 cart directly from the Finder using a Quick Action

== Action Steps ==

=== Add Automator and PICO-8 to Input Monitoring ===
You must add the ability for PICO-8 and Automator to monitor inputs in the Operating system
* Go to '''System Preferences''' from your MacOS
* Select the '''Security & Privacy''' Option
* Go to the '''Privacy''' tab at the top of the Menu
* Select the lock in the bottom left hand corner to allow for edits to be made. ''Please Note: You must have root access to this Mac''
[[File:MacOS - Elevate Permissions in Security and Privacy.png|centre|thumb|304x304px]]
* After you Authenticate, select '''Input Monitoring''' from the Side Menu
* Drag the Icons for Automator and PICO-8 from your ''Finder->Applications'' Window into the '''Input Monitoring''' Window
[[File:MacOS - Drag App to Security and Privacy Tab.png|centre|thumb|196x196px]]
* Make sure the the Check box is enabled next to the Dragged Application
* '''You have now activated Input Monitoring for PICO and Automator'''

=== Create Workflow in Automator ===
Now we will create the proper steps to make a Quick Action in the MacOS.

''While creating a workflow in Automator usually adds the Quick Action automatically to Finder, I have found this to be not true in the latest version of the OS (Catalina 10.15). I have added the extra steps at the end to help those who do not automatically see this added in their OS.''
* Open '''Automator''' from the Applications Menu in Finder (Or using Spotlight)
* Select '''New''' from the Menu
* Select '''Quick Action''' from the ''Choose a type for your Document'' menu. Confirm by selecting '''Choose'''
[[File:MacOS - Automator - Quick Action Selection.png|centre|thumb|220x220px]]
* Enter the Following Information in the Next Section:
** Workflow Receives Current = '''files and folders'''
** in = '''Finder'''
** Color = '''your preference'''
** Image = Choose..
*** Use the Following File: [https://user-images.githubusercontent.com/11636003/52351439-0d808e80-2a2b-11e9-8963-3d2af5080ea3.png PICO-8 Icon]

* From the '''Actions''' side menu, type “script” in the Search Bar. Drag the option '''Run Shell Script''' to the workspace[[File:MacOS - Automator - Shell Script Action Drag.png|centre|thumb|333x333px]]
* From within the '''Run Shell Script''' dialog, use the following values:
** Shell = '''Bash''', '''zsh''', and many others will suffice.
** Pass Input = '''as arguments'''
** Script = ''this command:''
::: <pre class="p8sh">/Applications/PICO-8.app/Contents/MacOS/pico8 -run $*</pre>
* Verify that you see the same information in your screen
[[File:MacOS - Automator - Shell Script for PICO-8.png|centre|thumb|393x393px]]
* From Automator, select '''File - Save'''
* Name your File What ever Nomenclature you like. I chose '''Open Cart in PICO-8'''

'''From Here, you should be able to see a new Quick Action Item Available from the Finder'''
[[File:MacOS - Finder - New Quick Action for PICO-8.png|centre|thumb]]

=== Test Workflow in Automator (Optional) ===
If you want to run your workflow in Automator to make sure the process works, you simply need to pass a value to the Script Function
[[File:Automator with Testing Overlay.png|thumb|146x146px|centre]]
* From the '''Actions''' Sidebar Menu, Type “Get Specified Text” in Search
* Drag '''Get Specified Text''' into the Workspace above the '''Shell Script''' Function
* Enter the path of a known cart on your machine. An example would be:
:: <pre class="p8sh">/Users/MyMacUser/Library/Application Support/pico-8/carts/arkanoid.p8</pre>
* Select the '''Run''' button at the top of the window
* You should see PICO-8 the game you have referenced
{| class="article-table"
!
Where is my Quick Action?!?
|-
|I had the same issue...

Follow these next steps to ensure you can see the Quick Action in Finder. I found this was the way i need to follow for '''MacOS Catalina 10.15'''
|}

=== Export from Automator ===
* From Automator, select '''File - Export'''
* Save File to Desktop. Name your File What ever Nomenclature you like. I chose '''Open Cart in PICO-8'''

=== Install Workflow to Quick Actions ===
[[File:MacOS - Finder - Install PICO-8 Quick Action.png|thumb|220x220px]]
* From Desktop, double click the file you just created. A dialog will appear
* Select '''Install'''

'''From here, you should be able to see a new Quick Action Item Available from the Finder'''

== Resources ==
PICO-8 Icon - github Request - Created by really-need-an-api-key

https://github.com/numixproject/numix-core/issues/4761

“Use Quick Action workflows on Mac” - ''Automator User Guide'' - https://support.apple.com/guide/automator/use-quick-action-workflows-aut73234890a/mac

“Open anything in VS Code using a MacOS quick action” - ''Written by Jim Bennett'' - https://www.jimbobbennett.io/open-anything-in-vs-code-using-a-macos-quick-action/

[https://icons8.com/icons/set/visual-game-boy--v1%22 Visual Game Boy] icon by [https://icons8.com/ Icons8]

== Downloads ==
'''The TL;DR edition'''.

[https://drive.google.com/file/d/1bA3udoF-JoIQTocg010IvZeGZR8uEbaJ/view?usp=sharing MacOS Quick Action - Open PICO-8 Cart]

Use this file to create your own Quick Action on your machine. Might need some tweaking. Just use the instructions above in case you need assistance.

'''Prerequisite''': You must perform the steps outlined in the Add Automator and PICO-8 to Input Monitoring section in order to properly use this Quick Action. __FORCETOC__
[[Category:Pico-8 Information]]
[[Category:Tutorials]]
[[Category:Command]]