Add macOS bundle support + Assets

[MisutaaAsriel]

Motivation

Whilst installing Lovely is fairly simple, it is a bit inelegant to require launching from the installation directory as a script. Likewise, the script does not take into account the possibility that Balatro is installed in a different location.

Changes

1. Add an installer release and the appropriate assets:

• ./crates/resources-mac, which contains the unique launch script, unique application icon, and info.plist
• installer_lovely.sh script, which:
  • Creates an app bundle, Balatro + Mods.app, in the user's Applications folder and cd's to it.
  • Copies the icon to Contents/Resources/
  • Copies the info.plist to Contents/
  • Copies run_lovely.sh as run_lovely to Contents/MacOS/
  • Copies liblovely.dylib to Contents/MacOS/
  • Symlinks Balatro.app to Contents/MacOS/
    • This allows the launch script to need not remember where Balatro is installed
  • Marks Contents/MacOS/run_lovely as executable then signs it "ad-hoc" (locally) with codesign
    • This should prevent potential edge cases where Apple Silicon Macs will refuse to open the bundle
    • codesign is thankfully, as far as I know, a built-in system utility, no tools required
  • Removes install_lovely.sh and assets/ from game folder

2. Fixes GitHub Workflow

• Adds build-macos-bundle steps
• Fixes build-macos steps due to name changes in recent master
  • lovely-mac ➜ lovely-unix
  • run_lovely.sh ➜ run_lovely_macos.sh
• Adds bundle installer to release draft

3. Fixes run_lovely_macos.sh to check the launch directory of the script first for Balatro.app, followed by the default install directory. If it cannot be found, it outputs an error, rather than running a nonexistent binary.
4. Updates Read-Me

Has this been tested?

Yes!

• I tested this using GitHub Workflows, downloading the release artifact, and running the installer on my M2 MacBook Air

[MisutaaAsriel]

For reference here is what the icon looks like:

Motivation is a distinctive icon that separates the modded launcher from stock Balatro; Since it's "modded", I took inspiration from Apple Developer & Xcode apps, and similar developer app icons, turning the normal Balatro icon into a "blueprint" to indicate things changing under the hood. I also used the "tool icon" aesthetic, placing a Joker in the bottom right, within the guidelines of Apple design guidelines for modern macOS icons.

[ethangreen-dev]

Wow, excellent work. I have no way of testing this currently but let me search around for someone who can.

[ethangreen-dev]

Maybe renaming these to "Mac Installer" would be more attention-grabbing? Furthermore should these be reordered to make the mac installers come first?

[ethangreen-dev]

This step should explicitly mention the installer variant, not just any one of the mac releases. Some people won't get it otherwise.

[ethangreen-dev]

Your additions push back hard against my "make lovely as game-agnostic as much as possible", but I think that's moreso an indication that we need to adapt our installation experience to support the specific needs of individual games.

It's also not realistic to assume that lovely is being used in anything BUT Balatro, so I think this is all more than fine for now. Maybe we should revisit this problem at a later date to more a more generic Mac OS installer?

[MisutaaAsriel]

Your additions push back hard against my "make lovely as game-agnostic as much as possible", but I think that's moreso an indication that we need to adapt our installation experience to support the specific needs of individual games.

It's also not realistic to assume that lovely is being used in anything BUT Balatro, so I think this is all more than fine for now. Maybe we should revisit this problem at a later date to more a more generic Mac OS installer?

Current installation instructions seem targeted towards Balatro, to the point the scripts in the main repository pointed specifically to Balatro, even before my changes. If anything my changes laid groundwork for them to be more adaptable. Albeit they too are currently tailored to Balatro.

The main problem with adapting to other games, from a Mac perspective, is customizing the bundle(s) to a particular game. In theory you could read the values from the app bundle for a game that's being modded, including info from its info.plist, and its icns. This would bar further customizations, such as custom icons (unless the installation script gives the option for a user provided icon?).

My experience with multi-game modding is usually you have a "client" that can launch multiple games. Since lovely is a simple framework injection that seems aggressive, however. But it is something to think about, if plans are to expand beyond balatro; a front end to install mods and launch games would probably work better than creating a custom "+ Mods" bundle per game.

I'll play around with this in the coming week, and make some of the changes requested. I do appreciate you taking this seriously though. I have some ideas based on your feedback I can test.

One in particular is having the installer script run from any directory and having the user drag-and-drop the modded-to-be app into the terminal window to set up the launcher bundle. — This would at least make it game-agnostic enough to no longer rely on steam install directories or the game name. I'll need to confirm that I can read the relevant values from the plist however.

The motivation behind this PR was basically convenience; no having to browse game files constantly, run an "ugly" script, or differentiate between modded & unmodded games. But it is a very Mac user nitpick, I suppose, to want to have a clean app bundle instead of folders and scripts.

[ethangreen-dev]

Current installation instructions seem targeted towards Balatro, to the point the scripts in the main repository pointed specifically to Balatro, even before my changes. If anything my changes laid groundwork for them to be more adaptable. Albeit they too are currently tailored to Balatro.

Haha yep, the flaws are pretty obvious. I appreciate your input and I agree in that we can make some positive changes towards improving this in the future, but it's all going to feel "weird" with how minimal lovely is at the moment.

One in particular is having the installer script run from any directory and having the user drag-and-drop the modded-to-be app into the terminal window to set up the launcher bundle. — This would at least make it game-agnostic enough to no longer rely on steam install directories or the game name. I'll need to confirm that I can read the relevant values from the plist however.

Keep me posted on what you find out. If you can find out a generic way to do it then great, otherwise this PR is good as it is (barring the changes I previously requested). At the end of the day it comes down to providing as much of a "Mac"-like experience as we can, of which I think you've nailed.

[MisutaaAsriel]

The script is pretty hefty now, in comparison to before, haha, but in testing I haven't noticed any bugs, and I tried to account for any failures and fail safely at multiple points. I also heavily documented the script for ease of readability and understandability, and tried to be sure the individual steps were understandable by users.

Likewise, the readme has been overhauled for this new script, as has the workflow automation, which I also attempted to add a manual workflow trigger for, useful for testing.

As far as the icon I worked on, I figured the system could actually be extended in a way so that the script could ship with custom icons (at your discretion) for multiple games, based on your own criteria. As such, the icon was renamed to its internal application identifier and placed in the Icons folder of Resources (resources-mac). The script checks this folder when creating a modded application bundle to see if an icon named after the application identifier exists, and if so, uses that instead of the application's default icon.

Test Release ➜

Built using GitHub Workflow Automation

[WilsontheWolf]

Was able to get around to testing this. Some feedback:

• docs seem a bit unintutive. Putting in mods first is a bit backwards compared to the windows build and it's nice to run lovely first to make the mods folder for you.
  • The info about finding the bundle being after the section would probably work better using one of these boxes right after the step.
• ctrl + c reopens the menu after using any options. I would expect it to quit out idk what the general consensus is
• the modded bundle making didn't work if I first run the game using option one, ctrl c (to get back to the menu) and then select it
  
• The Use custom icon file? question confused me (I thought it meant to use its default custom icon and not for me to specify one). It did however handle it gracefully when I did not enter anyrthing in there.
• it would be nice to be able to pass a command line arg or env variable to not have to go to the menu and just run the game modded.

[WilsontheWolf]

Oh also what is the process of updating lovely when the user has already built an application bundle?

[MisutaaAsriel]

• docs seem a bit unintutive. Putting in mods first is a bit backwards compared to the windows build and it's nice to run lovely first to make the mods folder for you.

This was mainly to reduce the number of steps required and to prevent jumping around in the instructions. This also represents the ideal order the steps should be taken in, as the mods should ideally be installed before injecting.

However, maybe installing mods should be a separate section all together? With variations in path based on Windows, Linux & Mac. That might make more sense, separating injection steps themself from mod installation.

• The info about finding the bundle being after the section would probably work better using one of these boxes right after the step.

Oh I didn't even know this was a feature of GitHub. How lovely. Thank you.

• ctrl + c reopens the menu after using any options. I would expect it to quit out idk what the general consensus is
• the modded bundle making didn't work if I first run the game using option one, ctrl c (to get back to the menu) and then select it

Ah. Uh, I'm honestly going to have to look into how to handle that. This script uses Bash functions and a while loop, so what appears to be happening is ctrl + c is not exiting the script itself but the functions it is calling, as if the functions within the script are separate programs. I wasn't aware this was even an issue with functions.

For possible explanation on why it breaks, the global variables within the script are essentially "dirty" at this point, having not been cleared at the end of the process. I'm surprised it breaks so fantastically though. There's other cases where the bundle step exits early, where this doesn't happen.

So... I'm not sure what ctrl + c is doing so differently. Ideally ctrl + c would just kill the script though, not return to the menu where this can happen.

I will be honest, I don't get why you would ctrl + c the script when using the option to run. But if you're wanting to exit the script, I could adjust the run step to detach the process from the console so it can return to the main loop, or just exit altogether.

If you kill Balatro it returns to the menu. If you want to exit the script, just close the terminal window/tab.

• The Use custom icon file? question confused me (I thought it meant to use its default custom icon and not for me to specify one). It did however handle it gracefully when I did not enter anyrthing in there.

• it would be nice to be able to pass a command line arg or env variable to not have to go to the menu and just run the game modded.

I don't really see what you mean. That's what the bundle is for. Are you suggesting the script take on a more traditional cli like mode of operation? so instead of walking you through the steps, you run something like run_lovely /path/to/game.app [--run] [--bundle [/path/to/icon.icns]]?

Maybe the scope of this should be changed if so; I'm not sure what @ethangreen-dev would prefer; a user-friendly wizard? Or a traditional cli script with arguments?

The design philosophy with how I structured this script is heavily in the former, which means things like returning to the main menu when a process is completed (e.g. you run first just to see what it's like, then bundle after). Things someone unfamiliar with a CLI application would expect. (This is also why the ctrl + c oversight is, well, an oversight. I was operating with the idea in mind that you'd just… close the window. My bad.)

Oh also what is the process of updating lovely when the user has already built an application bundle?

It asks you if you want to overwrite the bundle. If Y it deletes the old one and regenerates it. If N it returns to the menu. The bundle is just a proxy that includes liblovely, a symlink to the game being injected into, and a script as its main executable that injects the library and launches the game.

I'll continue working on this. I got something good, but it needs more time in the oven.