forked from Infinidoge/nix-minecraft
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request Infinidoge#10 from imsofi/pr/readme
readme: rewrite from org to markdown
- Loading branch information
Showing
1 changed file
with
59 additions
and
62 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,131 +1,128 @@ | ||
| #+TITLE: nix-minecraft | ||
| #+AUTHOR: Infinidoge | ||
| #+EMAIL: [email protected] | ||
| #+OPTIONS: toc:nil date:nil | ||
| # nix-minecraft | ||
|
|
||
| * About | ||
| ## About | ||
|
|
||
| ~nix-minecraft~ is an attempt to better package and support Minecraft as part of the Nix ecosystem. As of currently, it packages all (and I mean all) of the Vanilla versions, along with all supported versions of the Fabric and Quilt loaders. | ||
| `nix-minecraft` is an attempt to better package and support Minecraft as part of the Nix ecosystem. As of currently, it packages all (and I mean all) of the Vanilla versions, along with all supported versions of the Fabric and Quilt loaders. | ||
|
|
||
| * Installation | ||
| ## Installation | ||
|
|
||
| This repository is made exclusively as a Nix flake. Due to a lack of understanding of now Nix flake compat works, I have not included it, however if a PR is made to add compatibility, I may accept it. | ||
|
|
||
| In your ~flake.nix~: | ||
| #+begin_src nix | ||
| In your `flake.nix`: | ||
| ```nix | ||
| { | ||
| inputs = { | ||
| nix-minecraft.url = "github:Infinidoge/nix-minecraft"; | ||
| }; | ||
| } | ||
| #+end_src | ||
| ``` | ||
|
|
||
| In your system configuration: | ||
| #+begin_src nix | ||
| ```nix | ||
| { inputs, ... }: # Make sure the flake inputs are in your system's config | ||
| { | ||
| imports = [ inputs.minecraft.nixosModules.minecraft-servers ]; | ||
| nixpkgs.overlays = [ inputs.nix-minecraft.overlay ]; | ||
| } | ||
| #+end_src | ||
| ``` | ||
|
|
||
| From there, you can setup the service or use the packages, as described below. | ||
|
|
||
| * Roadmap | ||
| ## Roadmap | ||
|
|
||
| ** TODO: Finish documentation | ||
| ### TODO: Finish documentation | ||
|
|
||
| This README file is incomplete, and doesn't fully describe the ~services.minecraft-servers~ module. | ||
| Additionally, documentation should be added for the maintenance of the ~vanillaServers.*~ and ~fabricServers.*~. | ||
| This README file is incomplete, and doesn't fully describe the `services.minecraft-servers` module. | ||
| Additionally, documentation should be added for the maintenance of the `vanillaServers.*`, `fabricServers.*`, and `quiltServers.*`. | ||
|
|
||
| * Packages | ||
| ## Packages | ||
|
|
||
| ** ~vanillaServers.*~ | ||
| [[./pkgs/minecraft-servers][Source]] | ||
| ### `vanillaServers.*` | ||
| [Source](./pkgs/minecraft-servers) | ||
|
|
||
| An attrset of all of the vanilla server versions, in the form of ~vanilla-version~, where ~version~ is the Minecraft version (=1.18=, =1.12.2=, =22w16b=, etc), with all periods and spaces replaced with underscores (=1_18=, =1_12_2=, etc). | ||
| An attrset of all of the vanilla server versions, in the form of `vanilla-version`, where `version` is the Minecraft version (`1.18`, `1.12.2`, `22w16b`, etc), with all periods and spaces replaced with underscores (`1_18`, `1_12_2`, etc). | ||
|
|
||
| For convenience, ~vanillaServers.vanilla~ is equivalent to the latest major version. | ||
| For convenience, `vanillaServers.vanilla` is equivalent to the latest major version. | ||
|
|
||
| #+begin_src | ||
| ``` | ||
| vanillaServers.vanilla-1_18_2 | ||
| vanillaServers.vanilla-22w16b | ||
| vanillaServers.vanilla-22w13oneblockatatime | ||
| #+end_src | ||
| ``` | ||
|
|
||
| ** ~fabricServers.*~ | ||
| [[./pkgs/fabric-servers][Source]] | ||
| ### `fabricServers.*` | ||
| [Source](./pkgs/fabric-servers) | ||
|
|
||
| An attrset of all of the Fabric server versions, in the form of ~fabric-mcversion~ or ~fabric-mcversion-fabricversion~, following the same format as described above for version numbers. If the ~fabricversion~ isn't specified, it uses the latest version. | ||
| An attrset of all of the Fabric server versions, in the form of `fabric-mcversion` or `fabric-mcversion-fabricversion`, following the same format as described above for version numbers. If the `fabricversion` isn't specified, it uses the latest version. | ||
|
|
||
| The ~mcversion~ must be ~>=1.14~, and if specified, the ~fabricversion~ must be ~>=0.10.7~. The former is a limitation of Fabric, while the latter is the constraint I put on my packaging lockfile. | ||
| The `mcversion` must be `>=1.14`, and if specified, the `fabricversion` must be `>=0.10.7`. The former is a limitation of Fabric, while the latter is the constraint I put on my packaging lockfile. | ||
|
|
||
| For convenience, ~fabricServers.fabric~ is equivalent to the latest major Minecraft and Fabric versions. | ||
| For convenience, `fabricServers.fabric` is equivalent to the latest major Minecraft and Fabric versions. | ||
|
|
||
| #+begin_src | ||
| ``` | ||
| fabricServers.fabric-1_18_2 | ||
| fabricServers.fabric-22w16b | ||
| fabricServers.fabric-1_18_2-0_13_3 # Specific fabric loader version | ||
| #+end_src | ||
| ``` | ||
|
|
||
| ** ~quiltServers.*~ | ||
| [[./pkgs/quilt-servers][Source]] | ||
| ### `quiltServers.*` | ||
| [Source](./pkgs/quilt-servers) | ||
|
|
||
| ~quiltServers~ functions the same as ~fabricServers~, but with the Quilt mod loader. | ||
| `quiltServers` functions the same as `fabricServers`, but with the Quilt mod loader. | ||
|
|
||
| ** ~minecraftServers.*~ | ||
| ### `minecraftServers.*` | ||
|
|
||
| ~vanillaServers // fabricServers // quiltServers~. Will be used most often as it contains all of the different server versions across each mod loader. When using the overlay, this will replace the Nixpkgs ~minecraftServers~. | ||
| `vanillaServers // fabricServers // quiltServers`. Will be used most often as it contains all of the different server versions across each mod loader. When using the overlay, this will replace the Nixpkgs `minecraftServers`. | ||
|
|
||
| ** Others | ||
| ### Others | ||
|
|
||
| - ~vanilla-server~: Same as ~vanillaServers.vanilla~ | ||
| - ~fabric-server~: Same as ~fabricServers.fabric~ | ||
| - ~minecraft-server~: Same as ~vanilla-server~ | ||
| * `vanilla-server`: Same as `vanillaServers.vanilla` | ||
| * `fabric-server`: Same as `fabricServers.fabric` | ||
| * `minecraft-server`: Same as `vanilla-server` | ||
|
|
||
| *** ~fetchModrinthMod~ | ||
| [[./pkgs/helpers/fetchModrinthMod.nix][Source]] | ||
| #### `fetchModrinthMod` | ||
| [Source](./pkgs/helpers/fetchModrinthMod.nix) | ||
|
|
||
| Helper function that fetches a mod from [[https://modrinth.com/][Modrinth]]. | ||
| Helper function that fetches a mod from [Modrinth](https://modrinth.com/). | ||
|
|
||
| To use it, first find a mod on Modrinth, and click on the version you want. Among the information displayed, there is a =Version ID= string. This version ID will be refers to that version of the mod. See ~services.minecraft-servers...symlinks~ below for an example usage. | ||
| To use it, first find a mod on Modrinth, and click on the version you want. Among the information displayed, there is a `Version ID` string. This version ID will be refers to that version of the mod. See `services.minecraft-servers` below for an example usage. | ||
|
|
||
| #+begin_src shell | ||
| ```shell | ||
| nix run github:Infinidoge/nix-minecraft#nix-prefetch-modrinth -- versionid | ||
| #+end_src | ||
| ``` | ||
|
|
||
| (This helper script can also be used in a temporary shell with ~nix shell github:Infinidoge/nix-minecraft#nix-prefetch-modrinth~) | ||
| (This helper script can also be used in a temporary shell with `nix shell github:Infinidoge/nix-minecraft#nix-prefetch-modrinth`) | ||
|
|
||
| #+begin_src nix | ||
| ```nix | ||
| pkgs.fetchModrinthMod { id = "versionid"; hash = "hash from above command"; } | ||
| #+end_src | ||
| ``` | ||
|
|
||
| *** TODO: ~fetchCurseForgeMod~ | ||
| #### TODO: `fetchCurseForgeMod` | ||
|
|
||
| Not yet available, however planned for the future, assuming an elegant-enough method can be found. For now, you can use ~fetchurl~ with the file URL and file hash. | ||
| Not yet available, however planned for the future, assuming an elegant-enough method can be found. For now, you can use `fetchurl` with the file URL and file hash. | ||
|
|
||
| * Modules | ||
| ## Modules | ||
|
|
||
| ** ~services.minecraft-servers~ | ||
| [[./modules/minecraft-servers.nix][Source]] | ||
| ### `services.minecraft-servers` | ||
| [Source](./modules/minecraft-servers.nix) | ||
|
|
||
| Module for hosting multiple servers at once. | ||
|
|
||
| TODO: Finish documentation of the module. In the meantime, see [[./modules/minecraft-servers.nix]] | ||
| TODO: Finish documentation of the module. In the meantime, see [source](./modules/minecraft-servers.nix). | ||
|
|
||
| *** ~servers.<name>~ | ||
| ### `servers.<name>` | ||
|
|
||
| This family of options govern individual servers, which will be created on boot. | ||
|
|
||
| **** ~symlinks~ | ||
| #### `servers.<name>.symlinks` | ||
|
|
||
| This option is special in that it allows for declarative management of arbitrary things inside of the server's folder. | ||
|
|
||
| How it works is that it takes an attrset of derivations, and symlinks each derivation into place with the name of the attribute in the attrset. | ||
|
|
||
| For example, | ||
|
|
||
| #+begin_src nix | ||
| ```nix | ||
| { | ||
| symlinks = { | ||
| text-file = pkgs.writeTextFile { | ||
|
|
@@ -134,15 +131,15 @@ For example, | |
| }; | ||
| }; | ||
| } | ||
| #+end_src | ||
| ``` | ||
|
|
||
| Would symlink a file containing ~"Some text"~ into the server's folder. | ||
| Would symlink a file containing `"Some text"` into the server's folder. | ||
|
|
||
| This option is quite powerful, and can be used for a number of things, though most notably it can be used for declaratively setting up mods or plugins for the server. | ||
|
|
||
| This example takes an attrset of the IDs and hashes for Modrinth mods, fetches each one, and makes a folder containing those mods. (~linkFarmFromDrvs~ is quite useful because it can take a list of derivations and produce a folder suitable for this purpose.) The names in this attrset are meaningless, I only included them as convenient labels. | ||
| This example takes an attrset of the IDs and hashes for Modrinth mods, fetches each one, and makes a folder containing those mods. (`linkFarmFromDrvs` is quite useful because it can take a list of derivations and produce a folder suitable for this purpose.) The names in this attrset are meaningless, I only included them as convenient labels. | ||
|
|
||
| #+begin_src nix | ||
| ```nix | ||
| { | ||
| symlinks = { | ||
| mods = pkgs.linkFarmFromDrvs "mods" (map pkgs.fetchModrinthMod (builtins.attrValues { | ||
|
|
@@ -155,4 +152,4 @@ This example takes an attrset of the IDs and hashes for Modrinth mods, fetches e | |
| })); | ||
| }; | ||
| } | ||
| #+end_src | ||
| ``` | ||