From c123a67225e781ac2c9ba6865a6bb68a103319a6 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Fri, 27 Mar 2026 15:44:41 +0100 Subject: [PATCH 01/11] doc: refactor and clarify linux installation instructions --- doc/docs/tutorial.md | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index 8e925767..adb7a66f 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -48,35 +48,41 @@ If you want a video supplement, please refer to the [**Video Supplement**](#vide ## Linux Tutorial: -You can clone the repo, or install it as an [AUR package](https://aur.archlinux.org/packages/casual-pre-loader-git). +### Arch Linux or similar distros +There is an [AUR package](https://aur.archlinux.org/packages/casual-pre-loader-git). After installing, you can run the program with `casual-pre-loader` or through your launcher. - - Using [yay](https://github.com/Jguer/yay): -```sh -yay -S casual-pre-loader-git -casual-pre-loader -``` +Settings are stored under `${XDG_CONFIG_HOME}/casual-pre-loader`, defaulting to `~/.config/casual-pre-loader` if `${XDG_CONFIG_HOME}` is unset or empty. - - Using [paru](https://github.com/Morganamilo/paru): -```sh -paru -S casual-pre-loader-git -casual-pre-loader -``` +Mod data is stored under `${XDG_DATA_HOME}/casual-pre-loader`, defaulting to `~/.local/share/casual-pre-loader` if `${XDG_DATA_HOME}` is unset or empty. + +### Any Linux distro +Ensure that the following dependencies are installed: +`python3.12+ python-ensurepip python-venv` +These may be packaged differently depending on the distro. - - Or with git: +!!! note + There is an additional optional dependency on `wine`. If it's installed, it is used to run the windows build of `studiomdl` in order to compile MDL files. + (This may be unnecessary in the future if [this PR](https://github.com/craftablescience/sourcepp/pull/85)) gets merged. + +You can then download and run the program by cloning the repo: ```sh git clone --recursive https://github.com/cueki/casual-pre-loader cd casual-pre-loader +./scripts/run.sh ``` +The run script helps set up a virtualenv, if you know what you're doing, you could also just skip the run script and install any required python packages globally. -Then run the script whenever you want to use the app: +The program stores settings and mod data under the `userdata/` directory that is created on program launch. +If you'd rather store user files in the regular per-user locations (like the AUR package does), you can create an empty `.noportable` file in the project's root folder ```sh -./scripts/run.sh +touch .noportable ``` !!! warning - Linux users should use `scripts/run.sh` to launch the application. Do **NOT** use `RUNME.bat` - that's for Windows only. + Linux users should use `scripts/run.sh` to launch the application. Do **NOT** run `RUNME.bat` under wine. -If you're on Ubuntu, or an Ubuntu-based derivative (such as Mint or PopOS), you may get an error similiar to the following: +### Additional steps for Ubuntu or derivatives (e.g. Mint, PopOS, etc.) +You may get an error similiar to the following: ``` This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem. ``` From 9cfd82e1a5cee2ea6e344d48fdddeeab386ade21 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Thu, 16 Apr 2026 08:12:23 +0200 Subject: [PATCH 02/11] doc: add section on immutable distros --- doc/docs/tutorial.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index adb7a66f..8b30bda5 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -81,6 +81,28 @@ touch .noportable !!! warning Linux users should use `scripts/run.sh` to launch the application. Do **NOT** run `RUNME.bat` under wine. +### Aditional steps for immutable distros (e.g. SteamOS, Bazzite, etc.) +Since installing packages is quite a hassle on most immutable distros - and usually has some downsides - using something like [`flatpak`](https://flatpak.org/) to install `wine` is recommended. +```sh +flatpak install "$(flatpak remote-ls flathub --app --columns=ref | grep org.winehq.Wine | grep stable | sort -Vr | head -n1)" +``` + +However, the wine flatpak requires you to invoke it as `flatpak run org.winehq.Wine`, and since the preloader expects a binary named `wine` to be on the `PATH`, we need to put a small script on the `PATH` that just calls the correct invocation. + +User scripts that should be on the `PATH` are typically placed in `${XDG_BIN_HOME}`, which should be `~/.local/bin` by default. +To add this directory to the `PATH` if it hasn't already: +```sh +echo 'PATH="${PATH+"${PATH}:"}${XDG_BIN_HOME:="${HOME}/.local/bin"}"' >>~/.bash_profile # or `~/.profile`, or wherever else you set envvars +``` + +Then we simply create a small wrapper script: +```sh +: "${XDG_BIN_HOME:="${HOME}/.local/bin"}" +mkdir -p "${XDG_BIN_HOME}" +printf '#!/bin/sh\n\nexec flatpak run org.winehq.Wine "${@}"' >"${XDG_BIN_HOME}/wine" +chmod +x "${XDG_BIN_HOME}/wine" +``` + ### Additional steps for Ubuntu or derivatives (e.g. Mint, PopOS, etc.) You may get an error similiar to the following: ``` From 6c4824cdf37453d7fa3cf48292af04c3e54cd3a7 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Wed, 29 Apr 2026 03:51:03 +0200 Subject: [PATCH 03/11] doc: clarify credits --- doc/docs/index.md | 30 ++++++++++-------------------- 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/doc/docs/index.md b/doc/docs/index.md index 06c76857..66061297 100644 --- a/doc/docs/index.md +++ b/doc/docs/index.md @@ -11,24 +11,14 @@ ## Download the latest release [Here]({{ config.repo_url }}/releases/). - ## Thank you <3: -[djsigmann](https://github.com/djsigmann) for help with AUR packaging, documentation, and other misc development. - -[akuji](https://gamebanana.com/members/2017711) for being a huge help with discord support, documentation, and misc development. - -[Feathers](https://github.com/FeathersTheChick) for help with documentation. - -[Allen Scott](https://gamebanana.com/members/1242417) for the original logo. - -[THE GOAT](https://gamebanana.com/members/2133251) This person made the [square_series](https://gamebanana.com/mods/435309) preset. - -[Skeleton Hotel](https://gamebanana.com/members/1414545). - -[Taxicat](https://gamebanana.com/members/1333549) and [Qorange](https://gamebanana.com/members/2060075) for the [transparent_flamethrower](https://gamebanana.com/mods/348622). - -[Ashe_tf](https://gamebanana.com/members/1932153) for fixing the [medicgun_beam](https://gamebanana.com/mods/437447). - -[SonOfDiscordiA](https://gamebanana.com/members/2670597) for the [short_circuit](https://gamebanana.com/mods/446897). - -[agrastiOs](https://github.com/agrastiOs) for the [UltimateVisualFixPack](https://github.com/agrastiOs/Ultimate-TF2-Visual-Fix-Pack). +[djsigmann](https://github.com/djsigmann) for help with AUR packaging, providing linux-specific support, documentation, CI/CD, and other misc development. +[akuji](https://gamebanana.com/members/2017711) for being a huge help with discord support, documentation, and misc development. +[Feathers](https://github.com/FeathersTheChick) for help with documentation and the logo. +[Allen Scott](https://gamebanana.com/members/1242417) for the original logo. +[THE GOAT](https://gamebanana.com/members/2133251) This person made the [square_series](https://gamebanana.com/mods/435309) preset. +[Skeleton Hotel](https://gamebanana.com/members/1414545). +[Taxicat](https://gamebanana.com/members/1333549) and [Qorange](https://gamebanana.com/members/2060075) for the [transparent_flamethrower](https://gamebanana.com/mods/348622). +[Ashe_tf](https://gamebanana.com/members/1932153) for fixing the [medicgun_beam](https://gamebanana.com/mods/437447). +[SonOfDiscordiA](https://gamebanana.com/members/2670597) for the [short_circuit](https://gamebanana.com/mods/446897). +[agrastiOs](https://github.com/agrastiOs) for the [UltimateVisualFixPack](https://github.com/agrastiOs/Ultimate-TF2-Visual-Fix-Pack). From 9281cb2adeea0e4e7277c3dc0c32ad37523e54c7 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Wed, 29 Apr 2026 05:01:10 +0200 Subject: [PATCH 04/11] fix(docs): correct repo and site url macros --- .github/workflows/deploy.yml | 2 +- doc/mkdocs.yml | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 70f867fa..c74a1516 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -44,7 +44,7 @@ jobs: - name: Build documentation env: - REPO_URL: https://github.com/${{ github.repository }}/ + REPO_URL: https://github.com/${{ github.repository }} SITE_URL: ${{ steps.configure-pages.outputs.base_url }} run: | cd doc diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml index 403e1d2b..d2b49c67 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -1,8 +1,8 @@ site_name: Casual-Pre-loader site_author: Feathers & djsigmann -repo_url: !ENV [REPO_URL, "https://github.com/cueki/casual-pre-loader/"] -site_url: !ENV [SITE_URL, "https://cueki.github.io/casual-pre-loader/"] +repo_url: !ENV [REPO_URL, "https://github.com/cueki/casual-pre-loader"] +site_url: !ENV [SITE_URL, "https://cueki.github.io/casual-pre-loader"] nav: - Home: index.md From d94b5402b5e9ef973ae32ff49d3da2012966f822 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Wed, 17 Jun 2026 04:17:59 +0200 Subject: [PATCH 05/11] doc: add MacOS support disclaimer --- doc/docs/tutorial.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index 8b30bda5..90e6d57a 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -7,6 +7,11 @@ If you need further assistance installing the preloader, or just want to chat, j If you want a video supplement, please refer to the [**Video Supplement**](#video-supplement) section! +!!! note + MacOS support for Team Fortress 2 was officially dropped in 2024, and hasn't been properly playable since 2019. + It is possible to download older depots, or to run the windows build through `wine`/`crossover`, but this requires running an older version of the game and/or prevents users from connecting to VAC-enabled servers (e.g. casual servers). + As such, the casual-pre-loader does not support MacOS, and support is not planned. + ## Windows Tutorial: ### Step 1: Installation From 4d9a785bcf9870e8a6ead6e593260485da8e11bd Mon Sep 17 00:00:00 2001 From: djsigmann Date: Wed, 17 Jun 2026 04:26:26 +0200 Subject: [PATCH 06/11] doc: clarify windows install instructions --- doc/docs/tutorial.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index 90e6d57a..ea5cdf6c 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -17,10 +17,11 @@ If you want a video supplement, please refer to the [**Video Supplement**](#vide ### Step 1: Installation 1. **Install the latest version of the preloader from [GitHub]({{ config.repo_url }}/releases) or [Gamebanana]({{ gamebanana_url }}).** -2. **Once you have the zip file, extract it, and put the folder anywhere you'd like.** +2. **Once you have the zip file, extract it, and put the folder anywhere you like.** !!! note - Ensure it is not in a Onedrive shared folder or in your game's `custom` folder. + Ensure it is not under a Onedrive shared folder or a folder the user does not have write permissions for (e.g. `C:\program files`). + Do not put the casual-pre-loader in your game's `custom` folder. It is not a mod, and does not get loaded by the game. ### Step 2: Adding your mods From 72d53bed5ba3e73ab44b1b9b6f1c26f43688201f Mon Sep 17 00:00:00 2001 From: djsigmann Date: Fri, 19 Jun 2026 04:38:41 +0200 Subject: [PATCH 07/11] doc: add note regarding packaging contribution invitations --- doc/docs/tutorial.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index ea5cdf6c..31237cf5 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -23,6 +23,9 @@ If you want a video supplement, please refer to the [**Video Supplement**](#vide Ensure it is not under a Onedrive shared folder or a folder the user does not have write permissions for (e.g. `C:\program files`). Do not put the casual-pre-loader in your game's `custom` folder. It is not a mod, and does not get loaded by the game. +!!! note + If you're interested in packaging the casual-pre-loader via winget, choco, scoop, or any other windows package manager, please feel free to open a PR! + ### Step 2: Adding your mods 1. **Prepare your mods. The preloader can handle all mods, even mods that aren't *'casual compatible',* so don't be afraid to use whatever you'd like! Once you have all the mods you want, set them aside.** @@ -54,6 +57,9 @@ If you want a video supplement, please refer to the [**Video Supplement**](#vide ## Linux Tutorial: +!!! note + If you're interested in packaging the casual-pre-loader for your distro, please feel free to open a PR! + ### Arch Linux or similar distros There is an [AUR package](https://aur.archlinux.org/packages/casual-pre-loader-git). After installing, you can run the program with `casual-pre-loader` or through your launcher. From dac1c4d3ffc88a3b6a3aecba412629dc5192b9d1 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Fri, 19 Jun 2026 04:41:31 +0200 Subject: [PATCH 08/11] doc: add note regarding flatpak packaging status --- doc/docs/tutorial.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index 31237cf5..9273d1fa 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -115,6 +115,10 @@ printf '#!/bin/sh\n\nexec flatpak run org.winehq.Wine "${@}"' >"${XDG_BIN_HOME}/ chmod +x "${XDG_BIN_HOME}/wine" ``` +!!! note + Packaging the preloader as a `flatpak` would render all of this unnecessary, [there is already an open issue](https://github.com/cueki/casual-pre-loader/issues/142). + + ### Additional steps for Ubuntu or derivatives (e.g. Mint, PopOS, etc.) You may get an error similiar to the following: ``` From ab4ab6bd75982283b13ba11401dad1e534c6774c Mon Sep 17 00:00:00 2001 From: djsigmann Date: Sun, 21 Jun 2026 07:04:03 +0200 Subject: [PATCH 09/11] doc: update youtube tutorial link to new video --- doc/docs/tutorial.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index 9273d1fa..a67b2d44 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -130,6 +130,4 @@ sudo apt-get install -y libxcb-cursor-dev ``` ## Video Supplement: - - -*This will eventually be updated to the most recent version, and have a linux section - Feathers* + From 67883d0b4b5769aefbf6e579f689c89eac06e0e0 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Sat, 8 Aug 2026 22:13:52 +0200 Subject: [PATCH 10/11] doc: add memer's credit --- doc/docs/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/docs/index.md b/doc/docs/index.md index 66061297..6be2014b 100644 --- a/doc/docs/index.md +++ b/doc/docs/index.md @@ -15,6 +15,7 @@ [djsigmann](https://github.com/djsigmann) for help with AUR packaging, providing linux-specific support, documentation, CI/CD, and other misc development. [akuji](https://gamebanana.com/members/2017711) for being a huge help with discord support, documentation, and misc development. [Feathers](https://github.com/FeathersTheChick) for help with documentation and the logo. +[Memer](https://github.com/MemerOnYT) for help with testing. [Allen Scott](https://gamebanana.com/members/1242417) for the original logo. [THE GOAT](https://gamebanana.com/members/2133251) This person made the [square_series](https://gamebanana.com/mods/435309) preset. [Skeleton Hotel](https://gamebanana.com/members/1414545). From 7f40e89ff2c4bc96177bf1a5693044730796cd54 Mon Sep 17 00:00:00 2001 From: djsigmann Date: Sun, 23 Aug 2026 00:48:58 +0200 Subject: [PATCH 11/11] doc: provide update to status of sourcepp PR --- doc/docs/tutorial.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/docs/tutorial.md b/doc/docs/tutorial.md index a67b2d44..1d390a9d 100644 --- a/doc/docs/tutorial.md +++ b/doc/docs/tutorial.md @@ -75,6 +75,7 @@ These may be packaged differently depending on the distro. !!! note There is an additional optional dependency on `wine`. If it's installed, it is used to run the windows build of `studiomdl` in order to compile MDL files. (This may be unnecessary in the future if [this PR](https://github.com/craftablescience/sourcepp/pull/85)) gets merged. + UPDATE: The aforementioned PR hwas been merged, but we still require python bindings to the relevant c++ code. You can then download and run the program by cloning the repo: ```sh