Difference between revisions of "Getting Started"

From Forge Community Wiki
m
(Buildscript updates)
 
(16 intermediate revisions by 8 users not shown)
Line 1: Line 1:
−
<!-- need to format code Tags -->
+
'''Minecraft Forge''' is a modding framework, designed to allow different mods to load and work together to be compatible. Through the years, there has been many changes in the Forge tooling to make working with mods as seamless as possible. It is now easier than ever to start making your own mod.
−
= Home =
 
−
== Getting Started with Forge ==
 
−
This is a simple guide to get you from nothing to a basic mod. The rest of this documentation is about where to go from here.
 
−
=== From Zero to Modding ===
 
−
# Obtain a source distribution from forge’s [https://files.minecraftforge.net/ files] site. (Look for the MDK file type)
 
−
# Extract the downloaded source distribution to an empty directory. You should see a bunch of files, and an example mod is placed in <code>src/main/java</code> for you to look at. Only a few of these files are strictly necessary for mod development, and you may reuse these files for all your projects These files are:
 
−
#* <code>build.gradle</code>
 
−
#* <code>gradlew.bat</code>
 
−
#* <code>gradlew</code>
 
−
#* the <code>gradle</code> folder
 
−
# Move the files listed above to a new folder, this will be your mod project folder.
 
−
# Choose your IDE:
 
−
#* Forge explicitly supports developing with Eclipse or IntelliJ environments, but any environment, from Netbeans to vi/emacs, can be made to work.
 
−
#* For both Intellij IDEA and Eclipse their Gradle integration will handle the rest of the initial workspace setup, this includes downloading packages from Mojang, MinecraftForge, and a few other software sharing sites.
 
−
#* For most, if not all, changes to the build.gradle file to take effect Gradle will need to be invoked to re-evaluate the project, this can be done through Refresh buttons in the Gradle panels of both the previously mentioned IDEs.
 
−
# Generating IDE Launch/Run Configurations:
 
−
#*For Eclipse, run the <code>genEclipseRuns</code> gradle task (<code>gradlew genEclipseRuns</code>). This will generate the Launch Configurations and download any required assets for the game to run. After this has finished refresh your project.
 
−
#*or IntelliJ, run the <code>genIntellijRuns</code> gradle task (<code>gradlew genIntellijRuns</code>). This will generate the Run Configurations and download any required assets for the game to run. After this has finished edit your Configurations to fix the “module not specified” error by changing selecting your “main” module.
 
  
−
=== Customizing Your Mod Information ===
+
== The Mod Development Kit ==
−
Edit the <code>build.gradle</code> file to customize how your mod is built (the file names, versions, and other things).
+
The '''Mod Development Kit''' or '''MDK''' is a downloadable archive that contains the basic skeleton for starting a new mod. It contains the following files and folders:
  
−
{{Colored box|title=Important|content='''Do not''' edit the <code>buildscript {}</code> section of the build.gradle file, its default text is necessary for ForgeGradle to function.}}
+
{{Tree list}}
 +
* '''The Mod Development Kit'''
 +
** <code>gradle/wrapper/</code> - The folder containing the [https://docs.gradle.org/7.4.2/userguide/gradle_wrapper.html Gradle wrapper]'', Forge uses Version '''7.4.2'''''
 +
** <code>src</code> - The sources folder
 +
*** <code>main</code> - The <code>main</code> source set
 +
**** <code>java</code> - The java sources for the <code>main</code> source set
 +
***** ...
 +
**** <code>resources</code> - The resources for the <code>main</code> source set
 +
***** <code>META-INF</code> - The folder for '''meta'''data '''inf'''ormation files<ref>[https://stackoverflow.com/a/6075320/14416954 StackOverflow answer]: ''... Basically, if it was stored in META-INF, it was Meta-data Information...''</ref>
 +
****** <code>mods.toml</code> - The [[Mods.toml file|<tt>mods.toml</tt> file]], where mods are declared
 +
***** <code>pack.mcmeta</code> - File used by Minecraft to [[mc:Data Pack#pack.mcmeta|identify data and resource packs]]
 +
** <code>.gitattributes</code> - Used by [[wikipedia:Git|Git]] for specifying attributes for files<ref>[https://git-scm.com/docs/gitattributes Official git documentation on <tt>.gitattributes</tt>]</ref>
 +
** <code>.gitignore</code> - Used by Git for specifying intentionally untracked/ignored files<ref>[https://git-scm.com/docs/gitignore Official git documentation on <tt>.gitignore</tt>]</ref>
 +
** <code>build.gradle</code> - The Gradle buildscript, which defines the project and tasks<ref>[https://docs.gradle.org/7.4.2/userguide/tutorial_using_tasks.html Gradle User Guide for 7.4.2: ''Build Script Basics'']</ref>
 +
** <code>changelog.txt</code> - The Forge version changelog
 +
** <code>CREDITS.txt</code> - Forge's credits/''thank you'' file
 +
** <code>gradle.properties</code> - The Gradle properties file, for defining additional variables and options<ref>[https://docs.gradle.org/7.4.2/userguide/build_environment.html#sec:gradle_configuration_properties Gradle User Guide for 7.4.2: ''Build Environment § Gradle properties'']</ref>
 +
** <code>gradlew</code> - The *nix shell file for executing the Gradle wrapper
 +
** <code>gradlew.bat</code> - The Windows batch file for executing the Gradle wrapper
 +
** <code>LICENSE.txt</code> - File containing the licensing information for Forge and libraries
 +
** <code>README.txt</code> - Readme file with the basic setup instructions
 +
{{Tree list/end}}
  
−
Almost anything underneath the <code>// Only edit below this line, the above code adds and enables the necessary things for Forge to be setup.</code> marker can be changed, many things can be removed and customized there as well.
+
== Basic MDK Setup ==
 +
# Download the MDK from the [https://files.minecraftforge.net/ official Minecraft Forge download site] and extract the MDK into an empty folder.
 +
# Open your IDE of choice, and import the project as a Gradle project.
 +
#* For '''Eclipse''': <tt>File > Import > Gradle > Existing Gradle Project</tt>, select the folder for the <tt>Project root directory</tt>, click <tt>Finish</tt>
 +
#* For '''IntelliJ IDEA''': <tt>File > Open</tt>, select and open the folder, select the <tt>build.gradle</tt> file, click <tt>OK</tt>, click <tt>Open as Project</tt>
 +
#* For '''Visual Studio Code''': Run <code>./gradlew buildNeeded</code> and then <code>./gradlew eclipse</code>, then <tt>File > Open Folder...</tt> and select the folder
 +
# Wait for the setup process to complete and the Minecraft sources are decompiled.
 +
#* For '''Visual Studio Code''': This step can be skipped as it was already done in the previous step
 +
# Generate the run configurations for your IDE using the appropriate Gradle task. <br>These tasks can be run in the terminal using <code>./gradlew gen***Runs</code>.
 +
#* For '''Eclipse''': the task is <code>genEclipseRuns</code>; to run in the IDE directly, open the <tt>Gradle Tasks</tt> tab on the bottom panel, ''wait until the tasks have loaded'' then expand the folder, expand the <tt>fg_runs</tt> folder, then double-click <tt>genEclipseRuns</tt>.
 +
#* For '''IntelliJ IDEA''': the task is <code>genIntellijRuns</code>; to run in the IDE directly, open the <tt>Gradle</tt> on the right, expand the project folder, double-click <tt>Tasks > fg_runs > genIntellijRuns</tt>.
 +
#* For '''Visual Studio Code''': the task is <code>genVSCodeRuns</code>; the [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack Extension Pack for Java] and [https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle Gradle for Java plugin] should both be installed for smoother integration.
  
−
There is a whole site dedicated to customizing the forge <code>build.gradle</code> files - the [https://forgegradle.readthedocs.org/en/latest/cookbook/ ForgeGradle cookbook]. Once you’re comfortable with your mod setup, you’ll find many useful recipes there.
+
{{Tip|The most popular IDEs used by Forge and mod developers are [https://www.eclipse.org/eclipseide/ Eclipse] and [https://www.jetbrains.com/idea/ IntelliJ IDEA]. While Visual Studio Code has a run generation task, because of its relative unpopularity as an IDE for Minecraft modding, the user will have to self-diagnose any issues that may arise from their use of it.}}
  
−
==== Simple build.gradle Customizations ====
+
== Customizing the MDK ==
−
These customizations are highly recommended for all projects.
+
The MDK provides default values for the buildscript and <tt>mods.toml</tt> file. These values should be replaced with your own mod's information.
−
* To change the name of the file you build - edit the value of <code>archivesBaseName</code> to suit.
 
−
* To change your “maven coordinates” - edit the value of <code>group</code> as well.
 
−
* To change the version number - edit the value of <code>version</code>.
 
−
* To update the run configurations - replace all occurrences of <code>examplemod</code> to the mod id of your mod.
 
  
−
=== Building and Testing Your Mod ===
+
All edits should be done below the <code>id 'net.minecraftforge.gradle'</code> line. The lines above it are required for the Forge MDK to work correctly, and should not be modified without proper knowledge.
−
# To build your mod, run <code>gradlew build</code>. This will output a file in <code>build/libs</code> with the name <code>[archivesBaseName]-[version].jar</code>. This file can be placed in the <code>mods</code> folder of a forge enabled Minecraft setup, and distributed.
+
* All references to <code>examplemod</code> in the buildscript should be replaced with your modid.
−
# To test run with your mod, the easiest way is to use the run configs that were generated when you set up your project. Otherwise, you can run <code>gradlew runClient</code>. This will launch Minecraft from the <code><runDir></code> location, including your mod code. There are various customizations to this command. Consult the [https://forgegradle.readthedocs.org/en/latest/cookbook/ ForgeGradle cookbook] for more information.
+
** Use your IDE's find-and-replace function to quickly replace these values.
−
# You can also run a dedicated server using the server run config, or <code>gradlew runServer</code>. This will launch the Minecraft server with its GUI.
+
** Pick a unique and memorable modid. The modid must be between 2 and 64 characters, and must consist of lowercase letters, numbers, underscores (<code>_</code>) and hyphens (<code>-</code>). The recommendation is to avoid using acronyms and abbreviations.
 +
* Change the <code>archivesBaseName</code> variable to your modid. This is used as the base name for the JAR file when you build your mod, and as the <tt>artifactId</tt> of your mod's [https://maven.apache.org/pom.html#Maven_Coordinates maven coordinates].
 +
* Change the <code>group</code> to your [[Proper Mod Structuring#Packaging|unique root java package]]. This is used as the <tt>groupId</tt> of your mod's maven coordinates.
 +
* In the <code>jar</code> task, change the values of the <code>Specification-Vendor</code> and <code>Implementation-Vendor</code> keys to your username/brand name or other form of identification.
 +
* ''Optional suggestion: '' Change the <code>version</code> variable to have a 0 as the major version (ex. <code>'0.1'</code>. This is to follow [[Semantic Versioning#During Development|semantic versioning guidelines]] for versions in active development.
  
−
{{Colored box|title=Note|content=It is always advisable to test your mod in a dedicated server environment if it is intended to run there.}}
+
== Building and Testing ==
 +
You can test your mod in the development environment using either your IDE's run configurations and built-in debugging utilities, or by running the <code>run*</code> task as defined by the buildscript's run configurations.
 +
 
 +
There are four default run configurations with the MDK:
 +
* <code>runClient</code>, for starting the client.
 +
* <code>runServer</code>, for starting the dedicated server. ''You will need to accept the EULA through the <tt>eula.txt</tt> after running the server for the first time.''
 +
* <code>runData</code>, for starting the client in [[Datageneration|data generation]] mode.
 +
* <code>runGameTestServer</code>, for starting a build server to run [[Game_Tests|game tests]].
 +
 
 +
{{Tip|Always test your mod in both the client and the dedicated server, even if you are making a one-sided mod. Mods should not crash when running on both sides, and one-sided mods should not crash if they run on the wrong side.}}
 +
 
 +
You can build your mod's final JAR using the <code>build</code> task. The resulting JAR will be located in the <code>build/libs</code> folder under your project directory.
  
 
[[Category:Getting Started]]
 
[[Category:Getting Started]]
 +
 +
 +
[[Category:Beginner Topics]]

Latest revision as of 19:27, 13 June 2022

Minecraft Forge is a modding framework, designed to allow different mods to load and work together to be compatible. Through the years, there has been many changes in the Forge tooling to make working with mods as seamless as possible. It is now easier than ever to start making your own mod.

The Mod Development Kit

The Mod Development Kit or MDK is a downloadable archive that contains the basic skeleton for starting a new mod. It contains the following files and folders:

  • The Mod Development Kit
    • gradle/wrapper/ - The folder containing the Gradle wrapper, Forge uses Version 7.4.2
    • src - The sources folder
      • main - The main source set
        • java - The java sources for the main source set
          • ...
        • resources - The resources for the main source set
    • .gitattributes - Used by Git for specifying attributes for files[2]
    • .gitignore - Used by Git for specifying intentionally untracked/ignored files[3]
    • build.gradle - The Gradle buildscript, which defines the project and tasks[4]
    • changelog.txt - The Forge version changelog
    • CREDITS.txt - Forge's credits/thank you file
    • gradle.properties - The Gradle properties file, for defining additional variables and options[5]
    • gradlew - The *nix shell file for executing the Gradle wrapper
    • gradlew.bat - The Windows batch file for executing the Gradle wrapper
    • LICENSE.txt - File containing the licensing information for Forge and libraries
    • README.txt - Readme file with the basic setup instructions

Basic MDK Setup

  1. Download the MDK from the official Minecraft Forge download site and extract the MDK into an empty folder.
  2. Open your IDE of choice, and import the project as a Gradle project.
    • For Eclipse: File > Import > Gradle > Existing Gradle Project, select the folder for the Project root directory, click Finish
    • For IntelliJ IDEA: File > Open, select and open the folder, select the build.gradle file, click OK, click Open as Project
    • For Visual Studio Code: Run ./gradlew buildNeeded and then ./gradlew eclipse, then File > Open Folder... and select the folder
  3. Wait for the setup process to complete and the Minecraft sources are decompiled.
    • For Visual Studio Code: This step can be skipped as it was already done in the previous step
  4. Generate the run configurations for your IDE using the appropriate Gradle task.
    These tasks can be run in the terminal using ./gradlew gen***Runs.
    • For Eclipse: the task is genEclipseRuns; to run in the IDE directly, open the Gradle Tasks tab on the bottom panel, wait until the tasks have loaded then expand the folder, expand the fg_runs folder, then double-click genEclipseRuns.
    • For IntelliJ IDEA: the task is genIntellijRuns; to run in the IDE directly, open the Gradle on the right, expand the project folder, double-click Tasks > fg_runs > genIntellijRuns.
    • For Visual Studio Code: the task is genVSCodeRuns; the Extension Pack for Java and Gradle for Java plugin should both be installed for smoother integration.
The most popular IDEs used by Forge and mod developers are Eclipse and IntelliJ IDEA. While Visual Studio Code has a run generation task, because of its relative unpopularity as an IDE for Minecraft modding, the user will have to self-diagnose any issues that may arise from their use of it.

Customizing the MDK

The MDK provides default values for the buildscript and mods.toml file. These values should be replaced with your own mod's information.

All edits should be done below the id 'net.minecraftforge.gradle' line. The lines above it are required for the Forge MDK to work correctly, and should not be modified without proper knowledge.

  • All references to examplemod in the buildscript should be replaced with your modid.
    • Use your IDE's find-and-replace function to quickly replace these values.
    • Pick a unique and memorable modid. The modid must be between 2 and 64 characters, and must consist of lowercase letters, numbers, underscores (_) and hyphens (-). The recommendation is to avoid using acronyms and abbreviations.
  • Change the archivesBaseName variable to your modid. This is used as the base name for the JAR file when you build your mod, and as the artifactId of your mod's maven coordinates.
  • Change the group to your unique root java package. This is used as the groupId of your mod's maven coordinates.
  • In the jar task, change the values of the Specification-Vendor and Implementation-Vendor keys to your username/brand name or other form of identification.
  • Optional suggestion: Change the version variable to have a 0 as the major version (ex. '0.1'. This is to follow semantic versioning guidelines for versions in active development.

Building and Testing

You can test your mod in the development environment using either your IDE's run configurations and built-in debugging utilities, or by running the run* task as defined by the buildscript's run configurations.

There are four default run configurations with the MDK:

  • runClient, for starting the client.
  • runServer, for starting the dedicated server. You will need to accept the EULA through the eula.txt after running the server for the first time.
  • runData, for starting the client in data generation mode.
  • runGameTestServer, for starting a build server to run game tests.
Always test your mod in both the client and the dedicated server, even if you are making a one-sided mod. Mods should not crash when running on both sides, and one-sided mods should not crash if they run on the wrong side.

You can build your mod's final JAR using the build task. The resulting JAR will be located in the build/libs folder under your project directory.

  1. ↑ StackOverflow answer: ... Basically, if it was stored in META-INF, it was Meta-data Information...
  2. ↑ Official git documentation on .gitattributes
  3. ↑ Official git documentation on .gitignore
  4. ↑ Gradle User Guide for 7.4.2: Build Script Basics
  5. ↑ Gradle User Guide for 7.4.2: Build Environment § Gradle properties
Retrieved from ‘https://forge.gemwire.uk/index.php?title=Getting_Started&oldid=3264’