{"id":22347241,"url":"https://github.com/essentialgg/essential-mod","last_synced_at":"2025-04-04T07:03:08.700Z","repository":{"id":247963547,"uuid":"788915285","full_name":"EssentialGG/Essential-Mod","owner":"EssentialGG","description":"Essential is a quality of life mod that boosts Minecraft Java Edition to the next level!","archived":false,"fork":false,"pushed_at":"2025-03-25T19:36:29.000Z","size":5530,"stargazers_count":253,"open_issues_count":1,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-04T06:37:14.944Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://essential.gg/","language":"Kotlin","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EssentialGG.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/release-1.0.0.1.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-19T10:40:17.000Z","updated_at":"2025-04-03T19:35:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"d6cf291c-4e79-4e36-9957-640df91ed914","html_url":"https://github.com/EssentialGG/Essential-Mod","commit_stats":null,"previous_names":["essentialgg/essential","essentialgg/essential-mod"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EssentialGG%2FEssential-Mod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EssentialGG%2FEssential-Mod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EssentialGG%2FEssential-Mod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EssentialGG%2FEssential-Mod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EssentialGG","download_url":"https://codeload.github.com/EssentialGG/Essential-Mod/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247135138,"owners_count":20889420,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-04T10:06:01.653Z","updated_at":"2025-04-04T07:03:08.678Z","avatar_url":"https://github.com/EssentialGG.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Essential\n\nEssential is a quality of life mod that boosts Minecraft Java Edition to the next level!\n\nThe source code of the Essential Mod is accessible to everyone, demonstrating our commitment to transparency with our\nusers and the broader community.\n\nFor assistance with this repository or the mod, please utilize the dedicated channels available in our [Discord](https://essential.gg/discord).\n\nDiscover more about Essential on our [Website](https://essential.gg) or visit the [Essential Wiki](https://essential.gg/wiki).\n\n## Building\n\nBefore building Essential, you must have [Java Development Kits (JDKs)](https://adoptium.net/temurin/releases/)\ninstalled for Java versions 21, 17, 16, and 8 (even if you only want to build for a specific Minecraft version).\nJava 21 (or newer) must be the default Java version on your system.\n\nNo additional tools are required. Gradle will be automatically installed by the\n[gradle-wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) program included in the repository and\navailable via the `./gradlew` (Linux/Mac) or `gradlew.bat` (Windows) scripts.\nWe highly recommend using these instead of a local installation of Gradle to ensure you're using the exact same version\nof Gradle as was used for the official builds. We cannot guarantee that older or newer versions will work and produce\nbit-for-bit identical output.\n\nNote that this repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules).\nBe sure to run `git submodule update --init --recursive` after cloning the repository for the first time (or clone with\n`--recursive`), and also every time after you pull a new version.\n\n### Building Essential Mod\n\nTo build all of Essential for all Minecraft versions, run `./gradlew build`.\nDepending on your system and internet connection the first build may take anywhere from 10 minutes to an hour.\n\nTo build for a specific Minecraft version, run `./gradlew :\u003cversion\u003e-\u003cloader\u003e:build`, e.g. for Minecraft 1.12.2 run\n`./gradlew :1.12.2-forge:build`.\nNote that building any version other than the main version (currently 1.12.2) will require all versions between it and\nthe main version to be set up regardless, so the time saved over building for all versions may vary wildly.\n\nOnce finished, you should be able to find the Essential jars in `versions/\u003cMC-Version\u003e/build/libs/`.\n\nThe jar file starting with `pinned_` is the mod file made available via Modrinth/CurseForge.\nThe other jar file is downloaded by the in-game update functionality, third-party mods which embed the\nEssential Loader, the thin container mods available on essential.gg/download, as well as the Essential Installer.\n\n### Building Essential Loader\n\nThe latest version of Essential Loader is automatically built when building [Essential](#building-essential-mod) because\nit is included in the `pinned` jar files.\n\nThe loader is split into three \"stages\" (for details see `loader/docs/stages.md`) each with one jar per \"platform\"\n(for details see `loader/docs/platforms.md`).\nYou can find these jar files in `loader/\u003cstage\u003e/\u003cplatform\u003e/build/libs/`.\n\n### Building Essential Container\n\nThe Essential Container is a thin mod which does nothing but download Essential on first launch.\nThe jar files available for download on essential.gg/download and installed by the Essential Installer are such\n\"Container\" files.\nUnlike the jars published on Modrinth/CurseForge (\"pinned\" jars), it does not contain a specific version of Essential,\nrather it downloads whatever version is the latest at first launch.\n\nGiven it only contains code to load Essential and no code to directly interact with Minecraft itself, there are only\nfour different versions:\n- `fabric` for everything Fabric\n- `launchwrapper` for Forge on Minecraft 1.8.9 and 1.12.2\n- `modlauncher8` for Forge on Minecraft 1.16.5\n- `modlauncher9` for Forge on Minecraft 1.17 and above\n\nFor more technical details about these different platforms, see `loader/docs/platforms.md`.\nFor more technical details about \"container\"/\"pinned\" mods, see `loader/docs/container-mods.md`.\n\nTo build the Essential Container, run `./gradlew :loader:container:\u003cplatform\u003e:build` where `\u003cplatform\u003e` is one of the\nfour platforms listed above.\nYou can find the resulting jar file in `loader/container/\u003cplatform\u003e/build/libs/`.\n\n## CI\n\nEvery Essential release is built by CI twice, once by our main (internal, self-hosted) CI system and a second time\ndirectly from this repository on a GitHub-provided runner.\n\nThe first internal run is generally much faster and includes a few extra steps such as integration tests, uploading\n(but not yet publishing) of the jars to our infrastructure, as well as publishing the source code to this repository.\n\nThe second run, directly from this repository, exists primarily to ensure that the source code we publish actually\nmatches the jars that were produced and uploaded by the first run.\nAfter building the mod from scratch directly from publicly accessible source code in the GitHub-provided clean\nenvironment, it will download the main jars from our infrastructure and ensure that they are bit-for-bit identical to\nthe ones it just built.\n\nIt will also log and make available as an artifact via GitHub the checksums of the files it built, such that\nthird-parties may independently verify the files served by our infrastructure without having to build the entire mod\nthemselves.\nNote that GitHub will however unfortunately delete Actions logs and artifacts after some time.\n\nIt will not verify the checksums of the \"pinned\" jars (those available via Modrinth/CurseForge) because these are\ndeterministically derived from the main jars (see `build-logic/src/main/kotlin/essential/pinned-jar.gradle.kts`), so\nverifying the main jars is sufficient.\nOur internal CI does not even upload these pinned jars, they are re-generated on demand when publishing to\nModrinth/CurseForge.\nTheir checksums are printed to the publicly visible log during the second run though, so third-parties may at any time\ncompare them to the files served by Modrinth/CurseForge.\n\n## Verifying checksums\n\nTo verify checksums of any Essential-related files from your `.minecraft` folder, first either\n[build](#building-essential-mod) the respective Essential version, or find the corresponding GitHub Actions run and\ndownload its `checksums` text file / look at the `Generate checksums` log section of its `build` job.\n\nThen use the below sub-sections to identify which kind of file you are looking at, as well as what path to find the\nrespective jar file at in this repository.\n\nIf you have built Essential yourself, you may then compare the file at the given path to the one in your `.minecraft`\nfolder.\nIf you are looking at the GitHub Actions run, you are looking at a list of files with their corresponding\n[SHA-256 checksum](https://en.wikipedia.org/wiki/SHA-2). Use a program (e.g. `sha256sum` on Linux) to generate the\nchecksum of the file in your `.minecraft` folder and compare it to the checksum of the file in the list.\n\nNote that some Essential versions are compatible with multiple Minecraft versions, see the `versions/aliases.txt` for\nan exact mapping, or simply compare with the next available Minecraft versions above and below your version.\n\nNote that not all files in your `.minecraft` folder are updated at the same time, so some of them may be from older\nEssential versions.\n\nNote that if your installation of Essential is older, there may still be mod and loader files in there from before\nsource code has been made publicly accessible and even from before builds were deterministic.\nIf you still have such files and are concerned about them, please get in contact with us and we will try to verify its\nauthenticity.\n\n### Files in the .minecraft/mods folder\n\nIf your jar file is smaller than one megabyte (typically includes a Minecraft version but never an Essential version in\nits name),\nit should be an [Essential Container](#building-essential-container) file.\nPlease refer to the linked section for which \"platform\" corresponds to your Minecraft + Mod Loader and where the built\njar file can be found.\n\nIf your jar file is much larger (typically includes both the Minecraft version and the Essential version in its name),\nit should be the `pinned_` file found in `versions/\u003cMC-Version\u003e/build/libs/`.\n\n### Files in the .minecraft/essential folder\n\nIf your file is named `Essential (\u003cMod-Loader\u003e_\u003cMC-Version\u003e).jar`,\nit should be the main `Essential ` (not the `pinned_`) file found in `versions/\u003cMC-Version\u003e/build/libs/`.\n\nIf your file is named `Essential (\u003cMod-Loader\u003e_\u003cMC-Version\u003e).processed.jar`,\nit is a temporary file derived from the above file with the same name without the `processed` suffix.\nIf you delete it, it will be re-generated from that file on next launch.\n\n### Files in the .minecraft/essential/libraries folder\n\nThese are extracted from the main Essential jar [in the .minecraft/essentials](#files-in-the-minecraftessential-folder)\n(from its `META-INF/jars/` folder, as well as recursively for those jars).\nIf you delete them, those that are still used by your current Essential version will be re-extracted on next launch.\n\n### Files in the .minecraft/essential/loader folder\n\nIf your file is named `stage1.jar`, it is extracted from\n[the mods in your .minecraft/mods](#files-in-the-minecraftmods-folder) folder and from the main Essential jar\n[in the .minecraft/essentials](#files-in-the-minecraftessential-folder) folder (whichever has the most recent version).\nIn either case, unless you are on an ancient Essential version, it should match the jar file found in\n`loader/stage1/\u003cplatform\u003e/build/libs/` where `\u003cplatform\u003e` is one of the four listed in\n[this section of the README](#building-essential-container).\n\nIf your file is named `stage2.\u003cMod-Loader\u003e_\u003cMC-Version\u003e.jar`, it should match the jar file found in\n`loader/stage2/\u003cplatform\u003e/build/libs/` where `\u003cplatform\u003e` is one of the four listed in\n[this section of the README](#building-essential-container).\nNote that this file in particular is not at all updated in lockstep with Essential, so its version may very well be\nolder or even newer than the one which this repo references for your Essential version.\nIt should usually be accompanied by a `.meta` file though which should contain its version (not the Essential version),\nyou may then be able to find this version in the `loader` repository and build it specifically.\nNote that even though you found this file is in the `stage1` folder, it is the `stage2` of the loader (the reason it is\nin the `stage1` folder is because `stage1` loads it).\n\n## License\n\nBelow, you'll find an outline of what is permitted and what is restricted under the source-available license of the\nEssential Mod's source code.\n\n**What you CAN do**\n\n- Audit the source code.\n- Compile the source code to confirm the authenticity of the official releases.\n- Create unmodified forks of the repository.\n\n**What you CANNOT do**\n\n- Utilize any code or assets, including for personal use.\n- Incorporate the source code in any other projects or use our code as a reference in new projects.\n- Modify or alter the source code provided here.\n- Distribute compiled versions of the source code or modified source code.\n\nThis summary is not an exhaustive interpretation of the license; for a comprehensive understanding, please refer to [the\nfull license file](https://github.com/EssentialGG/Essential/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fessentialgg%2Fessential-mod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fessentialgg%2Fessential-mod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fessentialgg%2Fessential-mod/lists"}