From 1393df677a7ed7fb139a281c2efd3b181fb9a546 Mon Sep 17 00:00:00 2001 From: Rob B Date: Wed, 18 Sep 2024 22:30:35 -0400 Subject: [PATCH] move Mod Reference blurb to Plugin Setup page --- .../Adding_Ingame_Mod_Icon.adoc | 2 +- .../BeginnersGuide/CreateGitRepo.adoc | 2 +- .../BeginnersGuide/ImportingAnotherMod.adoc | 4 +- .../BeginnersGuide/ReleaseMod.adoc | 4 +- .../SimpleMod/gameworldmodule.adoc | 48 ++++++++++++++++++- .../Development/BeginnersGuide/index.adoc | 43 ----------------- .../BeginnersGuide/project_setup.adoc | 4 +- modules/ROOT/pages/Development/Cpp/setup.adoc | 2 +- .../ROOT/pages/Development/Localization.adoc | 2 +- .../ModLoader/BlueprintInterface.adoc | 6 +-- .../Development/ModLoader/ModModules.adoc | 2 +- modules/ROOT/pages/UploadToSMR.adoc | 4 +- 12 files changed, 62 insertions(+), 61 deletions(-) diff --git a/modules/ROOT/pages/Development/BeginnersGuide/Adding_Ingame_Mod_Icon.adoc b/modules/ROOT/pages/Development/BeginnersGuide/Adding_Ingame_Mod_Icon.adoc index bb4b7fbc..0ee61464 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/Adding_Ingame_Mod_Icon.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/Adding_Ingame_Mod_Icon.adoc @@ -36,7 +36,7 @@ or if you want to add another custom directory to be included, see the steps bel Let's navigate to our SML project (where the FactoryGame.uproject file is located) and from there go to `/Mods/` -(read more on mod references xref:Development/BeginnersGuide/index.adoc#_mod_reference[here]). +(read more on mod references xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[here]). We should now be in the folder where our mod's .uplugin file is located. Next, let's create 2 folders within our mod plugin folder: diff --git a/modules/ROOT/pages/Development/BeginnersGuide/CreateGitRepo.adoc b/modules/ROOT/pages/Development/BeginnersGuide/CreateGitRepo.adoc index 0861d40d..a910e20c 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/CreateGitRepo.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/CreateGitRepo.adoc @@ -34,7 +34,7 @@ Here are some notes about what decisions to make while following the GitHub docu - When prompted, you don't want to create your repository from a template. - (Step 2) Your repository name should be your - xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod reference]. + xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod reference]. It is possible to use a different name, but doing so will require more work later. - (Step 4) We suggest you leave your repository as 'Public' so others can learn from your mod, diff --git a/modules/ROOT/pages/Development/BeginnersGuide/ImportingAnotherMod.adoc b/modules/ROOT/pages/Development/BeginnersGuide/ImportingAnotherMod.adoc index 933a6508..aafbb611 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/ImportingAnotherMod.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/ImportingAnotherMod.adoc @@ -51,7 +51,7 @@ but consider cloning the repository to make it easy to update your copy with fut Regardless of if you extracted a zip or cloned, make sure that the name of folder containing the mod's `.uplugin` file exactly matches the mod's -xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod reference] +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod reference] - the filename of the mod's `.uplugin` file. Otherwise the editor will not properly identify the plugin. @@ -75,7 +75,7 @@ You can find out what other mods a mod depends on via the "Mod Dependency" table or by downloading a version and looking at the dependencies section of the `.uplugin` file contained inside. This section lists other mods by their -xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod reference]. +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod reference]. You can learn more about this section on the xref:Development/BeginnersGuide/ReleaseMod.adoc#_your_mods_uplugin_file[Releasing Your Mod page]. diff --git a/modules/ROOT/pages/Development/BeginnersGuide/ReleaseMod.adoc b/modules/ROOT/pages/Development/BeginnersGuide/ReleaseMod.adoc index 9fe79119..76da3534 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/ReleaseMod.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/ReleaseMod.adoc @@ -179,7 +179,7 @@ Each plugin should be listed as an object with the following properties: !Parameter !Description of Function !Name -! The xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod reference of the plugin] +! The xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod reference of the plugin] you are listing as a dependency. {blank} + {blank} + @@ -433,7 +433,7 @@ This zip file contains all of the mods' selected targets in one file ready to be == Last Chance to Change Your Mod Reference As mentioned on the -xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod Reference section of the Getting Started guide], +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod Reference section of the Getting Started guide], once you release your mod, you can no longer change its Mod Reference. If you decide to change it, you'll have to edit a number of files, most of which are described on that page. diff --git a/modules/ROOT/pages/Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc b/modules/ROOT/pages/Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc index 8d589901..8f20ad7e 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc @@ -3,6 +3,50 @@ To get started with our mod, we'll need to make a new Unreal plugin using Alpakit's wizard. Every mod you make should be a separate Unreal plugin. +== Mod Reference + +We need to talk about the concept of a "mod reference" before we continue +because it will be referenced quite often. + +A mod reference is essentially a mod's unique name. +This mod reference will then be used in class names, file names, folder names, and many other places. +When you upload your mod to the Satisfactory Mod Repository for other people to use, +you'll need to provide your mod reference there as well. + +Your Unreal plugin (also known as your mod) will need to use the mod reference as its name, +and any {cpp} modules you write must be in a Source folder with the mod reference as the name. + +Mod references can't contain special characters (ex. `+`, `#`, `.`, `ß`, ...) *nor can they contain spaces*. +However, they can contain underscores (`_`). + +End users of your mod see your mod's Display Name (which can contain spaces and special characters) instead of the Mod Reference, +with the notable exception of mod folders on disk, log messages, and filepaths. + +We strongly suggest that you follow https://techterms.com/definition/pascalcase[Pascal Case] naming conventions, +that is, each 'word' in the mod reference starts with a capital letter and the rest are lowercase. + +Here are a few possible examples of mod names and suggested mod references. + +.Example Mod Display Names and Corresponding Mod References +|=== +|Mod Display Name |Mod Reference + +|Example Mod +|`ExampleMod` + +|Rob's very cool mod +|`RobsVeryCoolMod` + +Note the exclusion of the apostrophe, because it's a special character. + +|Satisfactory Mod Loader +|`SML` + +Note that a mod's reference doesn't need to exactly match its display name's text. + +|=== + + == Unreal Plugin Creation Since SML3.0, mods are now Unreal plugins, @@ -19,7 +63,7 @@ Select the `Blueprint Only` template. The wizard will also prompt you for a Mod Name. The name of your plugin _must_ be your mod's -xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod Reference]. +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod Reference]. For this documentation example, you can use `DocMod` as the mod reference. When you start on your own mod, you will have to create a new plugin with a mod reference other than this. @@ -29,7 +73,7 @@ Optionally, fill out the "Descriptor Data" section, or leave it blank since it c [WARNING] ==== Be sure to read the notes on -xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod References] +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod References] if you have not yet done so. It is critical that your mod reference follows these formatting rules. ==== diff --git a/modules/ROOT/pages/Development/BeginnersGuide/index.adoc b/modules/ROOT/pages/Development/BeginnersGuide/index.adoc index 6266980b..1d266b8e 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/index.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/index.adoc @@ -87,49 +87,6 @@ The best way to reach the team is our https://discord.ficsit.app[Discord Server] You can find more info on contributing to the docs https://github.com/satisfactorymodding/Documentation#readme[here]. -== Mod Reference - -We need to talk about the concept of a "mod reference" before we continue -because it will be referenced quite often. - -A mod reference is essentially a mod's unique name. -This mod reference will then be used in class names, file names, folder names, and many other places. -When you upload your mod to the Satisfactory Mod Repository for other people to use, -you'll need to provide your mod reference there as well. - -Your Unreal plugin (also known as your mod) will need to use the mod reference as its name, -and any {cpp} modules you write must be in a Source folder with the mod reference as the name. - -Mod references can't contain special characters (ex. `+`, `#`, `.`, `ß`, ...) *nor can they contain spaces*. -However, they can contain underscores (`_`). - -End users of your mod see your mod's Display Name (which can contain spaces and special characters) instead of the Mod Reference, -with the notable exception of mod folders on disk, log messages, and filepaths. - -We strongly suggest that you follow https://techterms.com/definition/pascalcase[Pascal Case] naming conventions, -that is, each 'word' in the mod reference starts with a capital letter and the rest are lowercase. - -Here are a few possible examples of mod names and suggested mod references. - -.Example Mod Display Names and Corresponding Mod References -|=== -|Mod Display Name |Mod Reference - -|Example Mod -|`ExampleMod` - -|Rob's very cool mod -|`RobsVeryCoolMod` - -Note the exclusion of the apostrophe, because it's a special character. - -|Satisfactory Mod Loader -|`SML` - -Note that a mod's reference doesn't need to exactly match its display name's text. - -|=== - == Next Steps Next up is setting up your modding development environment. diff --git a/modules/ROOT/pages/Development/BeginnersGuide/project_setup.adoc b/modules/ROOT/pages/Development/BeginnersGuide/project_setup.adoc index 806e7f54..9b5334ea 100644 --- a/modules/ROOT/pages/Development/BeginnersGuide/project_setup.adoc +++ b/modules/ROOT/pages/Development/BeginnersGuide/project_setup.adoc @@ -414,7 +414,7 @@ Right now you should see two items in a searchable list - `Example Mod (ExampleMod)` and `Satisfactory Mod Loader (SML)`. This is the list of all mods present in your project. They are listed first by friendly name and then by -xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod Reference] +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod Reference] in parentheses. Once you have created a mod, it will appear in the list automatically. @@ -449,7 +449,7 @@ If you ever need to uninstall one of the mods you've packaged, simply go to your xref:faq.adoc#Files_Mods[installation's Mods folder] and delete the folder named with the -xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod Reference] +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod Reference] of the mod you wish to uninstall. == (Optional) Packaging SML diff --git a/modules/ROOT/pages/Development/Cpp/setup.adoc b/modules/ROOT/pages/Development/Cpp/setup.adoc index 070bd321..05611b0a 100644 --- a/modules/ROOT/pages/Development/Cpp/setup.adoc +++ b/modules/ROOT/pages/Development/Cpp/setup.adoc @@ -65,7 +65,7 @@ To begin adding {cpp} code to your mod you'll have to create a Module build conf Navigate to your mod's folder, `Mods/YourModReference/`, where your 'YourModReference.uplugin' file is located. Create a new folder named `Source` and within it a subfolder named `YourModReference`. -As a reminder, the concept of a mod reference is explained xref:Development/BeginnersGuide/index.adoc#_mod_reference[here]. +As a reminder, the concept of a mod reference is explained xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[here]. Within this folder, you should create a new file called `YourModReference.Build.cs`. You can do this by creating a new text file and then changing the extension to a `.cs` file, for example. If you chose to create the file in this manner, we suggest you turn on diff --git a/modules/ROOT/pages/Development/Localization.adoc b/modules/ROOT/pages/Development/Localization.adoc index 486f82ea..67527f7e 100644 --- a/modules/ROOT/pages/Development/Localization.adoc +++ b/modules/ROOT/pages/Development/Localization.adoc @@ -108,7 +108,7 @@ To view your target, click on its name in the table row. image:L10n/ViewTarget.png[Target row hovered] If the target's name is not already your -xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod reference], +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod reference], rename it to match. image:L10n/RenameTarget.png[Rename your target] diff --git a/modules/ROOT/pages/Development/ModLoader/BlueprintInterface.adoc b/modules/ROOT/pages/Development/ModLoader/BlueprintInterface.adoc index 219fc719..6af4c3e2 100644 --- a/modules/ROOT/pages/Development/ModLoader/BlueprintInterface.adoc +++ b/modules/ROOT/pages/Development/ModLoader/BlueprintInterface.adoc @@ -133,11 +133,11 @@ Note that the LoadConfig function does this automatically. The `Blueprint Mod Loading Library` provides functions to interact with the modloading process. === `bool IsModLoaded(String ModReference)` -This function takes a xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod reference] +This function takes a xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod reference] as input and checks if any kind of mod with that reference got loaded or not. === `Array GetLoadedMods()` -This function returns the xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod references] of all currently loaded mods in an array. +This function returns the xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod references] of all currently loaded mods in an array. === `ModInfo GetLoadedModInfo(String ModReference)` This function allows you to access additional information about the mod with the given reference. @@ -215,7 +215,7 @@ Mainly contents of the data.json of the mod. - String ModId (read only) + -The xref:Development/BeginnersGuide/index.adoc#_mod_reference[mod reference] +The xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[mod reference] - String Name (read only) + The display name of the mod diff --git a/modules/ROOT/pages/Development/ModLoader/ModModules.adoc b/modules/ROOT/pages/Development/ModLoader/ModModules.adoc index 015c1e3b..1b982fba 100644 --- a/modules/ROOT/pages/Development/ModLoader/ModModules.adoc +++ b/modules/ROOT/pages/Development/ModLoader/ModModules.adoc @@ -84,7 +84,7 @@ and then do your custom initialization logic. == Types of Modules It's highly suggested that you give your mod modules names that include their owning mod's -xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod Reference]. +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod Reference]. This helps with telling what module belongs to what mod when you have multiple mods loaded in the editor, and it makes them easier to identify in crash logs. diff --git a/modules/ROOT/pages/UploadToSMR.adoc b/modules/ROOT/pages/UploadToSMR.adoc index e9b6659a..479d6378 100644 --- a/modules/ROOT/pages/UploadToSMR.adoc +++ b/modules/ROOT/pages/UploadToSMR.adoc @@ -48,7 +48,7 @@ don't worry, you can come back and edit these fields later. One of the most important fields on this screen is the 'Mod Reference' field. Explained in more detail on the -xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod Reference section of the Getting Started guide], +xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod Reference section of the Getting Started guide], your mod reference is your mod's unique name. As a reminder, your mod's plugin folder and C++ source folder (if using {cpp}) must have the same name as your mod reference. Your mod reference cannot contain special characters or spaces. @@ -58,7 +58,7 @@ Your mod reference cannot contain special characters or spaces. **You can't change your mod reference after you have added your mod to SMR!** So make sure it is correct! At least five times! -And read up on the xref:Development/BeginnersGuide/index.adoc#_mod_reference[Mod Reference section] +And read up on the xref:Development/BeginnersGuide/SimpleMod/gameworldmodule.adoc[Mod Reference section] again to make sure you understand what other parts of your mod need to use this same value. ====