Mac Installation Guide

Thanks to b0bbyd1g1ts#0157 for writing this guide!

Harebrained Scheme’s (HBS) BattleTech already plays natively on Linux, Windows and MacOS, but you can also play the BattleTech Advanced 3062 mod on a Mac natively as well!

These steps were tested on a base installation of macOS Catalina (10.15) and macOS BigSur (11.0) and assumes nothing else is installed to start with.

IMPORTANT: This guide does not cover how to install the HBS BATTLETECH base game (also called the “Vanilla” game) but that should be pretty easy if you buy it from Steam or GOG (follow the HBS link above which links to the Steam and GOG BATTLETECH pages).

ALSO IMPORTANT: Corgi Perf Fixes is incompatible with Mac installations. When the installer asks you to select BTA Configuration Options (see the Run The BTA 3062 Installer with Wine64 section on this page) make sure to uncheck the Performance Patching Options box.

The DLC is not required but in my opinion is highly recommend - go ahead and get them all right away, it’s worth it. Especially the Heavy Metal DLC which you can have problems with BTA3062 if you do not have it!

Prerequisites

1. The base HBS BATTLETECH game installed and working (DLC installed as well)
2. A way to generate the BTA game files which will populate the “Mods” folder
   • this can be your Mac using Wine to run the installer, or
   • you can use a 2nd computer running either Linux or Windows (or a VM of either) to run the BTA installer, make the Mods directory and copy it over to your Mac

Installation Using A 2nd Non-Mac Computer

(Mac-only with no 2nd computer installation instructions are available below)

Installation can be made easier if you have an extra Windows or Linux PC, or a VM of either available to be used to generate the Mods files on.

If you have access to a Windows or Linux machine (or can run one with Steam/GoG in a VM) you can download and run the BTA installer following the Windows install guide inside those environments and just copy over the “Mods” directory it creates over to your Mac and place it in the game’s folder.

• In Steam or GOG (look at the “properties” of the game and inspect the “local files”) - this is how you can find where the game is installed in both Linux, Windows and in macOS.
  • This is typically cd ~/Library/Application\ Support/Steam/steamapps/common/BATTLETECH/BattleTech.app/Contents/Resources/Mods/ModTek for Steam on Mac
    • Note that the "\" in the directory is required because of the space in Application Support, it escapes the space.

IMPORTANT: The BTA installer will not run without the game installed so you’ll need to do that as well but it doesn’t have to play the game well or at all. It just has to be installed on this extra PC/VM so that the BTA 3062 installer can run and make a “Mods” folder for you.

• The advantage is the simplicity but the requirement is that you have 2 computers and they both can’t be Macs.
• The Mods folder will be several GiB large after the installer expands all its files to it
• Requires a minimum ~30 GiB (~11 GiB x2.5 uncompressed) free storage space to install
• Remember, Mac apps act like folders.
  • When you navigate from Applications → to the BATTLETECH folder where the app sits, right-click the BattleTech.app container and choose “show files” this will take you into the application where we want to be… or use the command line to navigate into the BattleTech.app container and issue a open . which will open a Finder window from that location.
  • Your end results should look something like this:

Patching BattleTech.exe with ModTek

The next part requires you to use Mono. If you need to install Mono, head over to their site and (at least as of 5/2021) click the Download Mono 6.12.0 (Stable channel) button and install with all default options.

If you installed Mono be sure to close your terminal and reopen it after installation is complete so you have access to the program from the command line!

Once the Mods directory has been deposited in the BTA root folder open command line, navigate into the Mods/ModTek directory, and issue the following:

Commands: (Note: Enter each line and hit return/enter before doing the next line)

cd ~/Library/Application\ Support/Steam/steamapps/common/BATTLETECH/BattleTech.app/Contents/Resources/Mods/ModTek
mono ModTekInjector.exe

Output:

ModTek Injector
---------------

Assembly-CSharp.dll backed up to Assembly-CSharp.dll.orig
Injecting Assembly-CSharp.dll with ModTek.Injection.LoadModTek at BattleTech.Main.Start
Writing back to Assembly-CSharp.dll...
Injection complete!

Create Sym Link

Go up one directory to the BATTLETECH root directory (where the Mods folder is) and create a sym link for the alternate name of the Data folder using this command:

ln -s Data BattleTech_Data

Finally, start the game through Steam or GoG (not through the BTA launcher) and voila you can play BTA3062! You're done! The remainder of the instructions are for the MAC-only install.

MAC-Only Installation Instructions (No 2nd Computer)

If you’re going to run the installer and generate the BTA files from within your Mac environment (no 2nd computer) you will need:

1. Homebrew package manager to install the prerequisite GNU packages
2. Wine to be able to run the BTA Installer

Homebrew Installation

Website: [https://brew.sh/]

Open your macOS terminal app and paste the following:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The script explains what it will do and then pauses before it does it. It will ask for your password (sudo), this is to install the package and its dependencies.

(Homebrew’s installation may take a while, it took me 10 minutes on a Mac running in a qemu VM)

Wine Installation

Website: [https://github.com/Gcenx/wine-on-mac]

Notes:

• Wine is not yet officially supported on Mac Catalina or higher (as of May 2021)
  • Wine 5.0 was the last wine-stable release from WineHQ that worked on mac prior to Catalina (Mojave, for example)
  • macOS Catalina dropped 32-bit support, therefore we must always issue the wine64 command rather than wine
• We’re going to use the wine-crossover package (from Gcenx on Github), which is version 5.0 with enhancements for quality of life
  • I had issues with the other Wine options (wine-stable, staging, devel) that WineHQ provides as of the writing of this doc in April of 2021
    • wine-crossover worked as expected on macOS Catalina and BigSur.

Install the Gcentx wine-crossover package with these commands:

brew tap gcenx/wine
brew install --cask --no-quarantine wine-crossover

The Wine website states that Mac’s Gatekeeper “must not be set to block unsigned packages”. The installation itself will print a line stating “Gatekeeper has been disabled for this Cask” - I personally have not run into trouble with Gatekeeper on any of the steps in this procedure by not explicitly disabling it, although I did have to allow “Terminal” to have accessibility privileges, but consider disabling it if you have issues running or installing Wine.

Test your Wine installation by issuing a wine64 --version command from the terminal, it should tell you what version was installed and you should be able to run it from any directory. wine64 notepad for instance should bring up the Windows notepad program on your Mac. Close it after you've tested that it opens.

Note: It takes a long time the first time Wine runs as it build the .wine prefix

Run winecfg once to bring up the Wine control panel, click the “drives” tab and check the back to “show dot files” - this will let you navigate your Linux/BSD style file system from a Windows (Wine) dialog box and be able to see folders that start with a dot (.)

Change nothing else and click OK when done.

Symlink the BTA 3062 macOS executable to BattleTech.exe

Commands: (Note: Enter each line and hit return/enter before doing the next line)

cd ~/Library/Application\ Support/Steam/steamapps/common/BATTLETECH/BattleTech.app/Contents/Resources/
ln -s ../MacOS/BattleTech BattleTech.exe
ln -s Data BattleTech_Data

Doing this is necessary for the BTA installer and the symlinks for the folders are to maintain compatibility with any mods that strictly reference the Windows names and locations.

Run the BTA 3062 Installer with Wine64

Download the latest BTA installer here. Create a directory in your Downloads folder named “BTA_installer” and expand the contents of the downloaded zip file to it.

Run the installer with the following command: wine64 ~/Downloads/BTA_installer/BTAdvancedLauncher.exe

One the installer is loaded, click “Browse” to choose the “Install Target” and navigate through the folder structure in the dialog box.

• The root of your Mac is mapped as the “Z:” drive in Wine, therefore a typical path for a Steam installation would be: Z:\Users\<your_username>\Library\Application Support\Steam\steamapps\common\BATTLETECH\BattleTech.app\Contents\Resources\Mods
  • You may need to right-click the whitespace in this window and create a new folder called “Mods”

The “workspace” directory (caches) is also important if you’ve ever downloaded the project before. You can leverage those offline files and only have to download those that have changed since the last download if you keep the workspace after you’ve downloaded all of it.

If you do not already have the caches downloaded, pick a spot for them to go (Z:\Users<your_username>\Downloads\BTA-workspace, create the folder if it doesn't exist) and make that selection for the “Checkout workplace” - if you do, have the cache already downloaded, choose that location here as it will significantly cut down the total time spent.

After setting the path to “Mods” and to the checkout space, click on “Set Preferences” and browse again to where your BattleTech.exe symlink is in the root of the BTA folder:

• For Steam: Z:\Users\<your_username>\Library\Application Support\Steam\steamapps\common\BATTLETECH\BattleTech.app\Contents\Resources\BattleTech.exe

IMPORTANT: You will not be able to confirm this choice unless there is a BattleTech.exe in that directory. The symlink we made to the macOS executable will work.

Click “Ok” through the next few warnings about there being no config and a new config will be made, and make the following selections:

• Do not select the DLC content if you do not own the DLC or don’t have it installed!
• Stick with MultiThreading.
• Uncheck the "Performance Patching Options". Corgi Perf Fixes are incompatible with Mac will break the main game screen, you cannot click on buttons to start the game with the performance fixes installed on Mac! (If you manage to get it working on your build please let us know how.)
• And finally, choose the "Old Fire for Linux Users" option.

Click “Ok” to confirm, the last prompt will say that the Mod directory will be wiped - proceed and the creation of the Mods directory will take several minutes to complete.

Patch the BattleTech executable with ModTek

BTA 3062 uses ModTek, not the HBS native mod loader. It’s faster and better.

Patching the BattleTech executable can be manually by going to Mods/Modtek/ and issuing a mono ModTekInjector.exe

The next part requires you to use Mono. If you need to install Mono, head over to their site and (at least as of 5/2021) click the Download Mono 6.12.0 (Stable channel) button and install with all default options.

If you installed Mono be sure to close your terminal and reopen it after installation is complete so you have access to the program from the command line!

Commands: (Note: Enter each line and hit return/enter before doing the next line)

cd ~/Library/Application\ Support/Steam/steamapps/common/BATTLETECH/BattleTech.app/Contents/Resources/Mods/ModTek
mono ModTekInjector.exe

Output:

ModTek Injector
---------------

Assembly-CSharp.dll backed up to Assembly-CSharp.dll.orig
Injecting Assembly-CSharp.dll with ModTek.Injection.LoadModTek at BattleTech.Main.Start
Writing back to Assembly-CSharp.dll...
Injection complete!

When it’s done you can start the game normally from Steam or GoG and you should see a “ModTek” mod loader screen for the first time. Have fun playing BTA3062 on your Mac!