XVLauncher - Setup Guide and Customization 1.0.0

Hello!

As one of the developers of XVLauncher, I’m really sorry it took all this time to get a tutorial for its use down for the community. Following you will find all the info you might need to get your project up and ready for XVLauncher.

But first, what’s XVLauncher?
XVLauncher is an open source launcher that handles the download, installation and update process of Windows apps in a way as user-friendly as possible. It being designed to work with RPG Maker games, it works great for distributing games, but it can also be used for any kind of application that works with an executable.

XVLauncher was developed by sasso-effe and xZekro51

For more information and more documentation, you can visit our github page:
https://github.com/sasso-effe/XVLauncher


Now let’s begin!

First and foremost, let’s list what you’ll need:

• a Github account,
• a Gitlab account,
• any kind of Git Client (in this tutorial we’ll work with Github Desktop),
• a C# editing tool and a WPF editing application (in this tutorial we’ll use Visual Studio 2019)

Optional:

• a Server (VPS is not needed);
• a MySQL database;

XVLauncher uses those to save diagnostics (how many people downloaded the launcher, what error they get) and to implement some neat features (updating the background image on the go), however they are not needed and are just optional. You can use XVLauncher even without a Server and a MySQL database.

In this tutorial we’ll see how to implement the basic version, so no server and no image update. A follow-up tutorial on that matter will come soon (I hope :’D).

Now, after we’ve made sure that we have all the things we need, we can start working on the implementation. Go to the repository on Github and press the button “Use this template”, this should clone the repository to your workspace and let you work without hindrances.



When the repository has finished generating, you’re gonna have to clone it into your system. To do so, you can simply open Github Desktop and go to File > Clone Repository. If you set up Github Desktop properly, it should show up here.
Once your repository has been cloned, it’s time to open Visual Studio. Head to the folder where you cloned the Repository and open the file XVLauncher.sln. If you don’t know where you cloned the repository, simply go to Repository > Show in Explorer in Github Desktop and the folder should open.



Now that we’ve opened the project containing XVLauncher, it’s time to start setting up our project repositories.
For this tutorial, I’ll be using vanilla Essentials, but as said before, it should work with any kind of application.

I won’t be explaining how to set up your own repository, but know that this will work whether your repository is set to private or public, so don’t worry about that.

Now we need to create a Release branch on our Github repository. Why we need this will be explained later. For now, go in Github Desktop’s branch section of your project repository, then press “New Branch” and name it Release (with a capital “R”, the branch name will be important in this section so bear it in mind). After the branch is created, press “Push” and push your changes to your Github repository.



Now it’s time to import our repository to Gitlab. We just need to open Gitlab, click on “New Project”, then choose “Import Project” and then press on the Github button. We will now have a list of repositories we can import.
We want to import the project repository. When the import process is complete, we will need to apply some more tweaks to the repository to make it work as we need to.

Navigate to the bar on the left and press on Settings > Repository. We want to set our default branch to “Release” and set it as the only protected branch.



Also we need to make sure that the repository visibility is set to “Public”. To do so, go to Settings > General > Visibility, Project features and permissions and set it to public.

After that is done, proceed and delete the main branch from the Gitlab repository. To do so, go to Repository > Branches and press on the trash can near the main branch.


Good! Now that this is done, we can set up our local git repository to push changes to both Github and Gitlab Release branches. This means that you’ll just have to work on your github repository and won’t have to worry about Gitlab. Keep in mind that the files in the Release branch will be the ones the final user will get on its own machine, so bear this in mind.

To start, head back to our project folder, and open the hidden folder ".git". Now you’ll need to open the config file with any text file editor, in this tutorial we’ll be using Visual Studio Code.

You should have something that looks like this:

What we need to do is add all the informations about the Gitlab repository. We need to tell the config file to push the “Release” changes to both Github and Gitlab, but keep the others for the Github repository. This means we need something like this:

GITHUB_HTTPS_CLONE is the clone URL we can find in our Github repo, and should look like this: https://github.com/xZekro51/VanillaEssentialsTutorial.git

Meanwhile, as you can imagine, GITLAB_HTTPS_CLONE is the clone URL we can find in our Gitlab repo, and should look like this: https://gitlab.com/xZekro51/VanillaEssentialsTutorial.git

The final result should be something along these lines:

NOTE: if you’re using Git LFS you don’t need to edit those parts, just add the segment that allows it for the Gitlab repository.

Congrats! Now your repository Release branch is up and ready. Be careful, you’ll most likely get an error when trying to push to the Release branch from Github Desktop. This is normal, as a workaround, you just need to push using git bash (you can use it by going to Repository > Open in Git Bash) and then write:

git push

It’ll probably prompt you to insert your credentials for Github and Gitlab, but it should work.

Now we need to set up our launcher to work with the game and detect the repository.
To do so, we need to first tweak a few values in XVLauncher. When opening the sln project, we might get some compiler errors. Worry not, these are due missing NuGet packages. Just go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution and press on “Restore”. If the errors are still there, we just need to reinstall all the packages, so open
Tools > NuGet Package Manager > Package Manager Settings and write

Update-Package -reinstall



All the errors should now be gone. Next comes setting up the Launcher with all the values it needs. First, we need to generate a Personal Access Token in Gitlab. This’ll allow our launcher to communicate with the Gitlab API and retrieve informations on the repository. To do so, we need to go to our Gitlab account settings (not the repository), and go to the section “Access Tokens”, or simply follow this link https://gitlab.com/-/profile/personal_access_tokens, then set up a new Personal Access Token that we’ll use in our setup.
Set the expiration date far enough in the future as this token can’t be renewed without changing the exe. For this example, I set the expiration date in 2026. Grant it the api, read_user, read_api, read_repository, read_registry permissions and save it.
BE CAREFUL, YOU WILL SEE THIS TOKEN JUST ONCE, SO DON’T LOSE IT!

Now, back to Visual Studio. We need to access the Project properties, so go to Project > XVLauncher Properties and head to the Resources tab. Set the AccessToken property as the one you got from Gitlab, and the Executable property as the executable of your project (in my case, it’s Game.exe).
If you’re working with RPG Maker XP, the SaveDirectory is used to manage the multiple save system, and it requires the name of the application (the same one that’s in the Game.ini file).
For the UpdateUrl, we need to set the URL that contains information about the releases. As this will be formatted with the latest tag retrieved automatically, you can just set it as https://gitlab.com/username/reponame/-/raw/{0}/ ,
in my case it looks like this: https://gitlab.com/xZekro51/VanillaEssentialsTutorial/-/raw/{0}/ .



Afterwards, go to the Settings section and set the ProjectID as the one you can find on the Gitlab repository (right under the repository name), and the GameDirectory as the name of the folder that will contain all the files from your repository.



And that’s it for the barebone setup! Now we just build the project, run it and it should work!

...except it doesn’t. This is because XVLauncher requires at least one release to be available on the Gitlab repository. So let’s go back to Gitlab, go to the Deployments > Releases menu and create a new Release. Note that currently XVLauncher will take whatever is the latest release, without considering its tag (this means that if version 0.5.0 was released after 1.0.0, it will pick up 0.5.0 as the latest version). This might become customizable in the future.

Now that our project has a release, after we’ve built our project we’re set!
We can still go further on with customization, but what we’ll cover for now are the main points: the title, the background images and the indicative download size.

As for the title, just open the MainWindow.xaml file you can find in the Solution Explorer. Then just modify “Your app name” with whatever suits you.



Next let’s handle the background images. XVLauncher automatically picks up all the images in the Resources folder. You can add the images to the folder after the build or in Visual Studio. If you’re doing the latter, make sure to mark the image as “Content” and not “Resource”.



Lastly, to modify the indicative download size we just need to modify the “Downloader.cs” file at line 79. Just modify 2GB with the actual indicative size.


And we’re done! Our Launcher now should look like this:


Sorry for the time it took to make this guide, but a lot went on and we weren’t able to make one right away. If you have any questions feel free to ask them!