From af3517b5c1187b0941f84d6ab7b879ce42366a28 Mon Sep 17 00:00:00 2001 From: Francis Date: Sun, 22 Sep 2024 08:45:32 +0100 Subject: [PATCH] Many tweaks and additions Changes: - Rename `*.mdx` to `*.md` where inline Javascript isn't used - Add missing `Installing Java` section to `userguide/docs/java.mdx` - Fix a few typos and try to reduce repition in various places - Add section on which version of Java to install to `userguide/docs/java.mdx` - Add section on installer log file to `userguide/docs/faq.md` - Reinstate and re-word commented-out section on driver troubleshooting in `userguide/docs/faq.md` - Add some inline HTML comments on things to consider documenting - Add initial article on launchers and mod managers - Various other little tweaks, because OCD... --- userguide/docs/faq.md | 79 ++++++++++++++++++++++++++ userguide/docs/faq.mdx | 70 ----------------------- userguide/docs/{index.mdx => index.md} | 2 +- userguide/docs/installer.md | 39 +++++++++++++ userguide/docs/installer.mdx | 35 ------------ userguide/docs/java.mdx | 41 +++++++++---- userguide/docs/launchers.md | 61 ++++++++++++++++++++ 7 files changed, 211 insertions(+), 116 deletions(-) create mode 100644 userguide/docs/faq.md delete mode 100644 userguide/docs/faq.mdx rename userguide/docs/{index.mdx => index.md} (96%) create mode 100644 userguide/docs/installer.md delete mode 100644 userguide/docs/installer.mdx create mode 100644 userguide/docs/launchers.md diff --git a/userguide/docs/faq.md b/userguide/docs/faq.md new file mode 100644 index 00000000..1c1ebb3e --- /dev/null +++ b/userguide/docs/faq.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 4 +--- + +# Frequently Asked Questions + +This section aims to answer some common questions as well as covering some pitfalls you might experience when using the NeoForge installer. + +## Troubleshooting the NeoForge Installer + +For most users the installer should run without error. + +If the installer runs but pops up an error dialog box while executing, see the [NeoForge Installer Log File] section below. + +### Troubleshooting the NeoForge Installer on Windows + +File associations for executing Java applications are sometimes missing or otherwise misconfigured. + +For example, running the installer may momentarily flash up a black window, present the `Open with ...` dialog box, or it might open in a file archiving program such as WinRAR or 7-Zip. + +To fix this, download and run (double-click) [JarFix], a program designed to fix broken or missing file associations. + +Once complete, restart your computer and try running the installer again. + +### Troubleshooting the NeoForge Installer on Linux + +File associations for executing Java applications are often missing completely on Linux distributions. + +In order to run the installer you may need to execute it manually in a terminal. + +For instance, with an installer for NeoForge version `21.1.54`, running the following in a terminal should bring up its GUI: + +``` +$ java -jar neoforge-21.1.54-installer.jar +``` + +For pointers on finding a terminal application on Linux, see the [Locating a Terminal Application] section in the [Checking for and Installing Java] article. + +### NeoForge Installer Log File + +When experiencing issues with the NeoForge installer, you might be asked to provide its log file, which should be created in the same directory the installer itself resides in. + +For example, the installer for version `21.1.54` should create a file with the name of `neoforge-21.1.54-installer.jar.log`. + +## Troubleshooting NeoForge + +You might run into problems when trying to launch Minecraft with NeoForge installed. + +This can happen for a number of reasons, including out-dated and/or buggy graphics card (GPU) drivers. + +First, check to see whether Minecraft without NeoForge works. If the game launches successfully and does not crash, read on. + +If Minecraft by itself crashes, you will not be able to install NeoForge. + +### Updating GPU Drivers + +Due to an interaction between NeoForge's early-loading screen and out-dated/buggy GPU drivers, Minecraft may crash. + +This can sometimes be fixed by updating the drivers for your GPU. + +Linked below are tools for the three most common GPU manufacturers, which can be used to download and install driver updates. + +- **Intel**: https://www.intel.com/content/www/us/en/support/detect.html +- **AMD**: https://www.amd.com/en/support +- **NVIDIA**: https://www.nvidia.com/download/index.aspx + +:::note +It is possible that your computer may have multiple GPUs. + +For example, a laptop might have one integrated into the CPU itself as well as a dedicated (discrete) GPU. +::: + +If you do not know who manufactured your GPU, how many you have, or even which drivers to update, see the [Further Help] section of the main article for a link to the NeoForged project's Discord server, where you can ask for help. + +[JarFix]: https://johann.loefflmann.net/downloads/jarfix.exe +[Locating a Terminal Application]: ./java.mdx#locating-a-terminal-application +[Checking for and Installing Java]: ./java.mdx +[NeoForge Installer Log File]: ./faq.md#neoforge-installer-log-file +[Further Help]: ./index.md#further-help \ No newline at end of file diff --git a/userguide/docs/faq.mdx b/userguide/docs/faq.mdx deleted file mode 100644 index 9ff38bba..00000000 --- a/userguide/docs/faq.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Frequently Asked Questions - -This section aims to answer some common questions as well as covering some pitfals you might experience when using the NeoForge installer. - -## Troubleshooting the NeoForge Installer - -### Troubleshooting the NeoForge Installer on Windows - -File associations for executing Java applications are sometimes missing or otherwise misconfigured. - -For example, running the installer may momentarily flash up a black window, present the `Open with ...` dialog box, or it might open in a file archiving program such as WinRAR or 7-Zip. - -To fix this, download and run (double-click) [JarFix], a program designed to fix broken or missing file associations. - -Once complete, restart your computer and try running the installer again. - -### Troubleshooting the NeoForge Installer on Linux - -File associations for executing Java applications are often missing completely on Linux distributions. - -In order to run the installer you may need to execute it manually in a terminal. - -For instance, with an installer for NeoForge version `21.1.54`, running the following in a terminal should bring up its GUI: - -``` -$ java -jar neoforge-21.1.54-installer.jar -``` - -For pointers on how to find a terminal application on Linux, see [Locating Terminal Application]. - - - -[JarFix]: https://johann.loefflmann.net/downloads/jarfix.exe -[Locating Terminal Application]: ./java.mdx#locating-terminal-application \ No newline at end of file diff --git a/userguide/docs/index.mdx b/userguide/docs/index.md similarity index 96% rename from userguide/docs/index.mdx rename to userguide/docs/index.md index f3932ed1..a5a6af24 100644 --- a/userguide/docs/index.mdx +++ b/userguide/docs/index.md @@ -24,4 +24,4 @@ The NeoForged project has a [Discord] server, including a `#user-support` channe [Discord]: https://discord.neoforged.net/ [Checking for and Installing Java]: ./java.mdx -[Installing NeoForge]: ./installer.mdx \ No newline at end of file +[Installing NeoForge]: ./installer \ No newline at end of file diff --git a/userguide/docs/installer.md b/userguide/docs/installer.md new file mode 100644 index 00000000..7a9ee5b0 --- /dev/null +++ b/userguide/docs/installer.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 2 +--- + +# Installing NeoForge + +## Running The Installer + +The NeoForge installer is OS-agnostic and is universal in that it can be used to install on both the client and server. + +With Java installed, you should be able to just double-click the installer's `.jar` file and proceed from there. + +If double-clicking does not bring up the installer's GUI, or doing so presents you with an OS error, see the section [Troubleshooting the NeoForge Installer] of the [FAQ]. + +## Installing NeoForge on a Server + +You might want to install NeoForge on a "headless" server which does not have a GUI and therefore no means of double-clicking to run the installer. + +Usually this will mean that you need to use remote-access software such as [OpenSSH] to open a terminal and install via the command line. + +With a terminal opened on the server you wish to install on, the installer is reaady to be launched. + +For example, to install NeoForge version `21.1.51`, run the following command: + +``` +java -jar neoforge-21.1.51-installer.jar --installServer +``` + +:::note +By default, this command will install to the current working directory. + +If this is not what you want, specify the path you want to install the server to after the `--installServer` option, e.g. by replacing `--installServer` with `--installServer /path/to/install/to`. +::: + + + +[Troubleshooting the NeoForge Installer]: ./faq#troubleshooting-the-installer +[FAQ]: ./faq +[OpenSSH]: https://www.openssh.com/ \ No newline at end of file diff --git a/userguide/docs/installer.mdx b/userguide/docs/installer.mdx deleted file mode 100644 index 9b6565a2..00000000 --- a/userguide/docs/installer.mdx +++ /dev/null @@ -1,35 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Installing NeoForge - -## Running The Installer - -The NeoForge installer is OS-agnostic and is universal in that it can be used to install on both the client and server. - -With Java installed, you should be able to just double-click the installer's `.jar` file and proceed from there. - -If double-clicking does not work, or your OS presents you with an error when doing so, see the section [Troubleshooting the NeoForge Installer] of the [FAQ]. - -## Installing NeoForge on a Server - -You might want to install NeoForge on a "headless" server which does not have a GUI and therefore no means of double-clicking to run the installer. - -Usually this will mean that you need to use remote-access software such as [OpenSSH] to open a terminal and install NeoForge via the command line. - -Once you have opened a connection to the server you want to install on, the process is similar to that in the [] section of the [FAQ] with one extra `--installServer`. - -For example, to install a NeoForge server, version `21.1.51`, run the following command: - -``` -java -jar neoforge-21.1.51-installer.jar --installServer -``` - -This command will install the NeoForge server to the current working directory by default. - -If this is not what you want, specify the path you want to install to after the `--installServer`, e.g. by replacing the last `--installServer` with `--installServer /path/to/install/to`. - -[Troubleshooting the NeoForge Installer]: ./faq.mdx#troubleshooting-the-installer -[FAQ]: ./faq.mdx -[OpenSSH]: https://www.openssh.com/ \ No newline at end of file diff --git a/userguide/docs/java.mdx b/userguide/docs/java.mdx index ee843682..2feade66 100644 --- a/userguide/docs/java.mdx +++ b/userguide/docs/java.mdx @@ -9,34 +9,34 @@ import TabItem from '@theme/TabItem'; This section provides instructions on how to check your computer for an existing Java installation. -If you are sure that you do not already have Java installed, you can skip to the [Installing Java] section of this article below. +If you are sure that you do not already have Java installed, you can skip to the [Installing Java] section below. ## Checking for Existing Java Installation -To find out if you already have Java, you will need to locate and run the terminal application that is provided by your OS. +To find out if you already have Java you can use the terminal application provided by your OS. -### Location Terminal Application - -The name of the application to use differs based on the OS that is running: +### Locating a Terminal Application - On Windows, one of the following should be available: + Windows has three options depending on version: - Windows Terminal - PowerShell - Command Prompt (aka `cmd`) - On macOS there is the `Terminal.app` often found on the Finder dock. + macOS has Terminal which is often found on the Finder dock. - On Linux, using your window manager's main menu, you should have at least one such application, usually named just `Terminal` though could have other names such as `Console, `Konsole` or similar. + The names for terminal applications vary on Linux but one of the following should be available from your distribution's main menu: + - GNOME Terminal (or just Terminal) + - Konsole ### Testing for Installed Java Version -Once you have located your OS's terminal application, run the command `java -version` which should present you with information similar to the following: +Once you have located the terminal application for your OS, run the command `java -version`, which should present you with information similar to the following: ``` openjdk version "21.0.4" 2024-07-16 LTS @@ -46,4 +46,25 @@ OpenJDK 64-Bit Server VM Temurin-21.0.4+7 (build 21.0.4+7-LTS, mixed mode, shari ## Installing Java -[Installing Java]: ./java.mdx#installing-java \ No newline at end of file +Minecraft itself recommends the [Microsoft Build of OpenJDK] (Microsoft JDK) for running Minecraft. + + + +If you do not want to use the Microsoft JDK, you can instead donwload an installer for, e.g. Temurin from the Eclipse Foundation, from [Adoptium]. + +### Which Version of Java to Install + +You will need to install a specific version of Java depending on the version of NeoForge you are installing. + +The following table lists the versions of Java that are recommended for a particular version of minecraft: + +| Minecraft version | Java version | +|-------------------|--------------| +| 1.20.2 - 1.20.4 | 17 | +| 1.20.5 and above | 21 | + + + +[Installing Java]: ./java.mdx#installing-java +[Microsoft Build of OpenJDK]: https://www.microsoft.com/openjdk +[Adoptium]: https://adoptium.net/temurin/releases/ \ No newline at end of file diff --git a/userguide/docs/launchers.md b/userguide/docs/launchers.md new file mode 100644 index 00000000..7154ea10 --- /dev/null +++ b/userguide/docs/launchers.md @@ -0,0 +1,61 @@ +--- +sidebar_position: 3 +--- + +# Launchers and Mod Managers + +There are two supported ways that you can launch Minecraft with Neoforge. + +The first is to use the official, vanilla launcher from Mojang, which the NeoForge installer creates a profile for. + +The second option is to use a third-party launcher, some of which are listed below in the [Third-Party Launchers] section. + +## Locating the Game Directory + +Minecraft stores its files, like your game's saves, as well as crash reports and log files in a so-called game directory. + +The location of the game directory will differ depending on which launcher you use to run the game. + +The vanilla launcher will create a `.minecraft` directory in your OS user's home directory. This is the game directory for the vanilla launcher. + + + +:::note +If you are using another launcher, refer to their documentation on where the game directory is located. +::: + +## Locating Log Files and Crash Reports + +Minecraft stores log files and crash reports in the game directory. + +You might be asked to provide log files or crash reports when seeking help. + +If you do not know where to find them, open your game directory in a file manager application where there should be two directories: + +- `logs` This directory contains log files for the game, with the files `latest.log` and `debug.log` being most pertinent. +- `crash-reports` This directory contains plain-text crash reports, each with timestamped filenames e.g. `crash-2024-08-11_15.54.06-client.txt`. + + + +## Third-Party Launchers + +There are a number of third-party launchers (also known as mod managers) to choose from, including: + +- [CurseForge App] +- [Modrinth App] +- [ATLauncher] +- [Prism Launcher] + +These launchers differ from the vanilla launcher in a number of helpful ways. + +First of all, the launcher should fully handle installing and updating NeoForge for you. + +Second, you will be able to create multiple game profiles (also known as instances), allowing you to easily seperate different versions of the game. + +Finally, all of the linked launchers have the ability to manage mods, making installing and updating mods much easier. + +[Third-Party Launchers]: ./launchers.md#third-party-launchers +[CurseForge App]: https://www.curseforge.com/download/app +[Modrinth App]: https://modrinth.com/app +[ATLauncher]: https://atlauncher.com/ +[Prism Launcher]: https://prismlauncher.org/ \ No newline at end of file