User Install vs Project Executable

The default way of installing Usagi is to run the install script that makes the usagi command available across your computer’s user. That way from any folder, you can run usagi to interact with the engine. This is convenient for a few reasons:

• It’s easy to update the engine when there are bug fixes and new features, you just run usagi update once.
• If you use multiple operating systems, you install Usagi for each system and run the same command and it works without having to worry about the macOS executable vs the Linux executable.
• When you’re creating new projects with usagi init, the command is available no matter where you want to put your project.

But there are some downsides to be aware of with user installs of Usagi. Let’s say you make a game with Usagi v1. And then 5 years later, there’s Usagi v2 that comes out and some of the functions change. If you did usagi update and then ran your game, your game might have errors that you need to fix, which could be tedious. I don’t know what the future of Usagi will bring, so if you want to make sure your projects are resilient to changes in the engine, you can download the Usagi version that corresponds to your project and put the usagi executable in your project’s folder.

Also, if you have many Usagi projects and they rely upon different versions of the game engine, it can be useful to put the version you used for that game in your project’s folder.

All historical downloads of Usagi from v1.0.0 and onward are available at https://codeberg.org/brettchalupa/usagi/releases. If you made your game with Usagi v1.1.1, you’d find that release and download it. Decompress the archive and put the usagi (or usagi.exe) in your project’s folder. Then you’d run commands by referencing it locally, like ./usagi dev on Linux and macOS or .\usagi.exe dev on Windows. The ./ and .\ prefixes say: use the local, project executable instead of the usagi installed on the system. It’s referencing the file path.

Using a project executable is ideal if you’re only going to develop your games on a single operating system. Otherwise you’ll run into issues trying to use the macOS executable on Linux.

It’s ultimately your decision for how you want to install and interact with usagi. In summary, install Usagi for your user if you value easily and quickly accessing it. If you want the same Usagi version you made your game with to be present years down the line, put the usagi executable in your project’s folder.

If you use usagi init for your projects, look at the top of USAGI.md to see the version:

<!-- Generated by usagi 1.1.1. Run `usagi refresh` to update. -->

That can be an easy hint to see which version was used at the time of usagi init or usagi refresh.