Single files

In order to understand why springboardvr-cli is reluctant to push "single files", we have to dig a little deeper.

Portable builds

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.

Zipped portable builds

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.

Diffing and patching portable builds

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:

• We have two builds, each build is 500MB uncompressed
• A patch from one uncompressed build to the other is 1MB
• When compressed, each build is around 230MB
• A patch from one compressed build to the other is 150MB

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:

• SpringboardVR will compress each build individually, and those will be used for first-time installations, and direct downloads from the website
• small patches will be used to upgrade from one version to the next

All-in-one executables

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:

• uses a temporary folder to extract all the resource files needed by the title

or, it

• has a privileged relationship with the title, and can extract individual resources on-demand, whenever the title needs them

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!

Installers

In short, installers are the absolute worst.

• Unlike portable builds, there are extra steps between downloading and playing
• Like all-in-one executables, they store the title's resources (and executable!) in compressed form

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:

• Some installers require the Administrator password to proceed

Your players may not have administrative rights on their gaming computer! They shouldn't be needed to play your title.

• Some installers have an interface that cannot be hidden (ie. they have no silent mode)
• Some installers do not let users pick the install location

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.

Where installers shine

That said, there are actual reasons to distribute your title or application as an installer.

• Your title requires some packages to be installed in order to run correctly
• You want to create a shortcut on the desktop and in the start menu
• You want to associate some file types with your application
• You want to create some registry entries
• etc.

These problems are addressed in part by SpringboardVR:

• You can include an app manifest, listing prerequisites that SpringboardVR should install before first launching your title
• Automatic shortcut creation is on its way
• File associations and registry entries could also be handled by the app, via entries in the manifest

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.

I still really want to push a single file though

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).