Mod development on Mac

[jayu]

 

Hello everyone, I have been learning how to mod the past two weeks, until I finally released my first mod Bear Trap and I think it would be useful for me to list the things I've learnt about modding on Mac, since I couldn't find many resources online. So, if you currently are or are going to attempt to develop a mod on Mac, please share here all of your tips! From what I could find, there's not many of us, so we should try to pool together all we know to make ours and future modders' life a bit easier.

Here is what I found so far, I will update this as I find out new things.

Content Mods

When zipping, do not select the directory and compress. This will compress it as a folder with your mod folder inside, instead of just its contents. The game will not be able to load the mod and will tell you it cannot find modinfo.json. What you should do instead is select all the contents of your mod folder at the same time and compress those.

IDE

I use Rider but VS Code should work perfectly fine too. Rider allows for hot-swapping code which is great for testing things like GUIs and small adjustments to non-static methods and parameters without restarting the game.

Project Setup

After following the setup instruction described here Setting up your Development Environment, I needed to slightly tweak the template to make it work. Since for some reason launching the Vintagestory unix executable with the --addModPath startup parameter didn't seem to work, I had to first set up a separate Vintage Story installation that I use only for modding (and set its location as the VINTAGE_STORY environment variable), then modify the launch configurations in launchSettings.json to copy the compiled mod to in the internal mods folder of the installation, and update it every time you change your code. 

Edit 29 October 2024: I updated this with a new simpler launch setting that works fine and does not require to move folders. It also allows to use the debugger! (finally)

{
  "profiles": {
    "Client": {
      "commandName": "Executable",
      "executablePath": "$(VINTAGE_STORY)/Vintagestory",
      "commandLineArgs": "--tracelog --addModPath \"$(ProjectDir)/bin/$(Configuration)/Mods\"",
      "workingDirectory": "$(VINTAGE_STORY)"
    },
    "Server": {
      "commandName": "Executable",
      "executablePath": "$(VINTAGE_STORY)/VintagestoryServer",
      "commandLineArgs": "--tracelog --addModPath \"$(ProjectDir)/bin/$(Configuration)/Mods\"",
      "workingDirectory": "$(VINTAGE_STORY)"
    }
  }
}

Edited October 30, 2024 by jayu
update with new info

[DimitrisZar]

Hey jayu, thanks for your very helpful guide for us Mac users!

I am facing an issue with content mods (not developing, just trying to use them for now, but I'd very much like to create some of my own) on a Apple silicon Mac. I can load mods like hudclock and zoombuttonreborn which don't really add any content to the game, but for content mods I only get the handbook entries and not any items at all.

I've tried your solution above for content mods regarding how to compress the files, but didn't notice any difference. I'd like to add that I've actually moved all my vintage story data from a Windows system to my mac after the support for Macs was re-established earlier this year, I've changed the filepaths in clientSettings.json etc, but it didn't fix the issue either. Do you happen to know whether it could be something else?

[jayu]

Honestly I heavily suggest a fresh install (be sure to download 1.19 and not 1.20 since some mods aren’t updated yet, or be aware of this fact if you get 1.20, it’s still in a release candidate phase) then you can move over your saves and settings if things seem to work.

You don’t even have to delete anything, you can easily keep two different installations (I do so for modding) so it doesn’t hurt to try it out, just download, install some mods and give it a go. (VintagestoryData folder is the same for all installations, but the game files will be different, this might not fix all problems, if so back up your VintagestoryData and let it generate a fresh one)

[DimitrisZar]

I can't thank you enough mate. I've been trying for months to make mods work and it never crossed my mind to regenerate the VintagestoryData dir. Mods work fine now! So, so grateful for your fast response, cheers!

[DimitrisZar]

Follow-up to say thanks again, as I've just managed to successfully run the vintagestory mod template on my Mac with Rider!

[Oofishy]

I am also trying to make a mod on Mac but I can’t figure out where on my computer the games default textures and code are, so I can’t override them, does anyone know where they are?

Edit: I figured it out! i found out that it is contained in the vintage story app, you have to right click the app in finder and click "show package contents" from there you can click assets and find everything you need

Edited January 7, 2025 by Oofishy
update

[Echo Weaver]

Wow, @jayu. This was magical. Thank you!

I also use Rider. It was so validating to see someone else talking about it here. 

Since I have a bunch of mods on my default installation, I added a "--dataPath" arg to point the game to a fresh folder with no mods. I guess the alternate option would be to uncheck all my mods before opening a world while testing, but it's a lot of mods.

Edited August 25, 2025 by Echo Weaver