In order to understand why springboardvr-cli is reluctant to push "single files", we have to dig a little deeper.
The best case scenario for springboardvr-cli is when you have a "portable build" of your title, which is a folder that contains the title's executables and its resources.
By resources, I mean: sound effects, music, textures, levels, anything that isn't code.
Unity exports have the following structure, for example:
- UnityTitle/ - Title.exe - Data/ - level0 - level1 - etc.
It's called a portable build because if you have that folder on your disk, you can just run the executable, and the title will work. No extra steps needed.
If you're already using Unity, Unreal Engine 4, Godot Engine, or any other engine that exports a similar folder structure, you can stop reading here: Good job, you did it! Just push that folder and get a nice beverage of your choice.
If you try to push a .zip using springboardvr-cli, it will treat it just like a folder.
So it will decompress it on-the-fly, then apply its own compression while uploading.
There's really no upside to pushing a .zip instead of a folder, since the result is exactly the same. It's just a convenience if all you have is a .zip of a portable build of your title - saves you the time to decompress it yourself.
I lied: there is one situation where pushing a .zip would save you. If you're pushing, for example, a macOS build of your title from a version of Windows that does not support symbolic links. But that's about it.
When you push successive versions of your title using springboardvr-cli, it attempts to create "patch" files, that are used to upgrade from one version to the next using as little bandwidth as possible.
If each build of your title is around 500MB, but you only make a few changes every version, the patches may be around 1MB. So if a user is ten versions behind, they only have to download 10MB to update, not 500MB. So far so good (great, even!)
But compression can take two builds that look a lot alike, and make them look completely different. The numbers often look as follows:
How is that possible? When comparing both uncompressed versions, the changes were very localized and easily encoded in a series of instructions to upgrade from one version to another - which makes up a patch file.
But the compressed versions don't have much in common - the changes had a cascading effect and changed many other parts of the compressed file - and as a result, it's much longer to describe "how to go from compressed file 1 to compressed file 2", than it is to describe for their uncompressed counterparts.
TL;DR it's much better to push the uncompressed version:
All-in-one executables are almost like portable builds, except instead of being a folder, they're a single executable file.
Executables have a "data" section where anything that isn't code can be stored. All-in-one executables use that section to store all the resources needed by the title, often in compressed form.
When the all-in-one executable is started, it either:
If the resources are stored in compressed form, then patches to upgrade from one version of the title to the next will be unnecessarily large (see "Diffing & patching" above).
If they're not compressed, then the situation is almost as good as with a real portable build.
Almost as good, because every file "modified" by a patch is duplicated on disk when upgrading (so that if the upgrade fails, a working version of the title remains). In a single file scenario, if the file is 2GB, then an additional 2GB on disk will be used on every upgrade. That's far from optimal!
In short, installers are the absolute worst.
So, not only are patches between installer versions large (see "Diffing & patching" above), but they're also useless!
Since the installer file is not the "final form" of the title (it's not playable), it's useless trying to patch it from one version to the next.
In fact, the installer is removed by SpringboardVR after installation, so even there was a way to patch it efficiently, it wouldn't.
Besides, installers bring a host of other problems:
Your players may not have administrative rights on their gaming computer! They shouldn't be needed to play your title.
And finally, all installers have various failure conditions that aren't just "your disk is full".
For example, MSIs (microsoft installer packages) like to fail when the title was already installed before on this computer. Even if all files have been removed since. Air installers are even more specific about what state a computer should be in before it will deem it worthy of having your title installed to it.
That said, there are actual reasons to distribute your title or application as an installer.
These problems are addressed in part by SpringboardVR:
However, the app should be optional - there should be a good way for users to download and run your title even without using SpringboardVR.
For now, install instructions can be added to your SpringboardVR page to help get your users up and running.
In the future, we could imagine the SpringboardVR backend generating installers directly for each title, so that they can be properly installed without SpringboardVR.
This would re-use the information included in the app manifest, and would require absolutely no effort on your part. In the meantime, the easy way to handle non-tech-savvy users is to direct them to SpringboardVR.
If you've read all this, but you have your reasons, you can still pass a single file to springboardvr-cli push and it'll work transparently.
springboardvr-cli will behave as if you had created a folder and put your single file in it. The upload will work as usual for users of SpringboardVR (although diffs might be unusually large, if your single file is compressed or just has high entropy).