tf2-nix/README.org

#+title: tf2-nix
#+author: Madeleine Sydney Ślaga

tf2-nix provides a framework for configuring [[https://en.wikipedia.org/wiki/Team_Fortress_2][Team Fortress 2]] (TF2), a game that not only allows for, but sometimes demands, a surprising amount of hacking to optimise your experience. User customisations includes anything from essential performance tweaks, to aesthetic changes such as UI overhauls, hit-sounds, and animations, to basic scripting.

For the practical purposes including easy deployment and version-tracking, as well as "the spiritual purity of configuring computers correctly,"[fn:1] tf2-nix was created. This project's goal is to provide complete configuration, package-management, and, when possible, packages themselves, for TF2.

* Disclaimers

** This is an alpha status project

At the moment, this project should mostly be considered a proof of concept. It is usable, I am using it, but it is pretty bare-bones. I hope to gradually expand this project anon. More packages, modules, all the Nix goodness we're accustomed to.

Further, I'm not the most experienced Nix user. Expect bad code and unidiomatic interfaces. I encourage you to point out said bad code if you spot it. }:)

** TF2 is a radioactive zigzagging target

In my experience, TF2 and Valve software in general [[https://github.com/DeerUwU/deerhud-tf2/pull/15][react]] [[https://github.com/flathub/com.valvesoftware.Steam/issues/1218][very]] [[https://github.com/nix-community/impermanence/issues/165#issuecomment-2529954063][dramatically]][fn:2][fn:3] when prodded with even slightly unorthodox setups. Brace yourself before updating TF2, and never be afraid to open an issue here.

* FAQ (Frequently-anticipated questions)

** How make [[https://github.com/nix-community/impermanence][Impermanence]] work?

See [[https://github.com/nix-community/impermanence/issues/165#issuecomment-2537723929][nix-community/impermanence#165]]:

- If =~/.local/share/Steam= is persisted using a symlink, Steam works, but ~home.file~ breaks.
- If =~/.local/share/Steam= is persisted using a bind-mount via Impermanence's Home-manager module, Steam breaks, but ~home.file~ works.
- If =~/.local/share/Steam= is persisted using a bind-mount *via Impermanence's NixOS module*, Steam works, and ~home.file~ works!

For the purists and the masochists, I recommend a despicable game file-system ping-pong:

[[file:assets/file-system-ping-pong.png]]

* Usage

tf2-nix is dead simple. No modules of any variety are provided (at this point in time). A TF2 'config' is packaged into a derivation resembling TF2's =tf= directory. Your final config is composed of several configs; your HUD, your scripts, your maps, your hitsounds, etc. are individually packaged as 'configs,' which are ultimately merged into one[fn:4]. It is then left to you, the user, to install it as you wish. I expect ~home.file.${path-to-tf-dir} = {source = your-config; recursive = true;}~ to suffice for most people.

** TL;DR

*** As a flake

Bring in the input, and build your TF2 config as a package:

#+begin_src nix
  {
    inputs = {
      tf2-nix.url = "gitlab:msyds/tf2-nix";
    };

    outputs = { self, ... }@inputs:
      let
        system = "x86_64-linux";
        pkgs = import inputs.nixpkgs { inherit system; };
        tf2pkgs = inputs.tf2-nix.packages.${system};
        my-tf2-config = tf2pkgs.mergeTf2Configs (with tf2pkgs; [
          # Your chosen packages.
          mastercomfig.presets.medium-low
          mastercomfig.addons.flat-mouse
          mastercomfig.addons.no-tutorial
          mastercomfig.addons.null-canceling-movement
          improved-crosshairs
          loadouts-script
          huds.broesel-hud
          maps.jump_beef
          # If you have a directory with the following structure, you can import
          # it here to merge it into your config.
          #     my-existing-config
          #     ├── cfg
          #     │   └── ...
          #     ├── custom
          #     │   └── ...
          #     └── maps
          #         └── ...
          ./my-existing-config
        ]);
      in {
        # ...
      };
  }
#+end_src

You can then install your configuration into TF2's =tf= directory:

#+begin_src nix
  ### home.nix
  let
    # Confirm that this is actually where your tf dir lives!
    tf-dir = ".local/share/Steam/steamapps/common/Team Fortress 2/tf";
  in {
    home.file.${tf-dir} = {
      source = my-tf2-config;
      recursive = true;
    };
  }
#+end_src

Rebuild your system, and rejoice!

** Example Flake

Try out the example flake:

#+begin_example
$ nix build 'gitlab:msyds/tf2-nix?dir=example'
#+end_example

The resulting config can then be explored in =./result/=.

** Library

TODO!

** Packages

The package set is best explored via ~nix repl~ and ~nix flake show~. Some notable subsets are listed here:

*** HUDs

A package set of HUDs is generated primarily using data from [[https://github.com/mastercomfig/hud-db][hud-db]], complemented with a handful of manual additions and overrides.

*** Maps

The map list currently consists of primarily rocket jumping courses, per [[https://jumpacademy.tf/fastdl][JumpAcademy.tf]].

*** Mastercomfig

[[https://comfig.app/][Mastercomfig]] presets and addons are packaged from their [[https://github.com/mastercomfig/mastercomfig/releases][GitHub releases]].

* Contributing

Don't hesitate to open issues/PRs not only for "real issues" (bugs, missing features) but for poor UX, bad code, or anything else.

* To-do list

- [X] Generate a package set from [[https://github.com/mastercomfig/hud-db][hud-db]].
- [ ] Support non-GitHub HUDs from [[https://github.com/mastercomfig/hud-db][hud-db]].
- [ ] CI action to update hud-db.
- [ ] Mastercomfig [[https://comfig.app/][comfig.app]] wrapper.
- [ ] VPK builder.
- [ ] Configure launch options (Is this feasible?).
- [ ] A higher-level NixOS/Home-manager module.
- [ ] Tests.
- [X] Figure out installation for Impermanence users.
- [ ] Package Paysus' animation overhauls.
- [X] Generate package set from [[https://cdn.jumpacademy.tf/][jumpacademy.tf]].

* See also

- [[https://github.com/spiretf/nix][gh:spiretf/nix, a set of tf2-related nix packages]]

* Footnotes

[fn:4] Forming a commutative [[https://en.wikipedia.org/wiki/Monoid][monoid]] }:). I know you were wondering.

[fn:3] [[file:assets/bind-mount.png]]

[fn:2] [[file:assets/gamescope.png]]

[fn:1] [[file:assets/spiritual-purity.png]]