¶ Making Mods: Getting Started
Currently, mods can primarily work with game code, and improved modding support for adding content to the game is coming soon.
¶ Recommended Software
This list should serve as a guide to the kind of software required for different kinds of mods. The individual items listed are those commonly used by PlateUp! modders, or versions used to develop PlateUp! which ensures compatibility. You need not use the exact pieces of software mentioned here if you have a preferred one that works for your needs. Refer to the Installation Guide for a more detailed steps to install the recommended software.
¶ Required for all:
- C# Integrated Development Environment (IDE)
- Microsoft Visual Studio Community 2022 or later (Standalone)
- Microsoft Visual Studio Community 2019 (Bundled with Unity in Unity Hub)
¶ Content mod (Adds assets into the game)
Mods in this category include, but is not limited to,
- Player Cosmetics
- New Appliances
- New Restaurant Settings
- Sound Effects
- Visual Effects
- Unity 2020.3.43f1 (Install from Unity Hub)
¶ Tools
¶ Creating a project
Code mods should consist of a compiled .dll. To begin, create a project in your favourite IDE. To use game code, you'll need to add references to the game's DLLs, which can be found in the game's installation directory inside PlateUp_Data\Managed.
You should add references to the DLLs as required, with most of the game's code contained in files beginning Kitchen. You'll probably also need to add references to:
- Unity.Entities.dll
- Unity.Collections.dll
- Unity.Collections.LowLevel.ILSupport.dll
- UnityEngine.CoreModule.dll
Optionally, instead of adding references manually, you can use the following community made NuGet Package. You can install it into your project using the Visual Studio Package Manager after you have created the project.
¶ Writing code
PlateUp is built on Unity's DOTS ECS framework. Where possible you should stick to this design to ensure your mods are as compatible and functional as possible. ECS code is primarily based on components and systems.
When a mod is loaded, the game will automatically load any components implementing IModComponent and systems implementing IModSystem. Your code should mostly be contained within systems, and your data should be mostly contained within components.
Systems should inherit from GenericSystemBase or a subtype - these have a number of helpers that make writing code easier. These methods (and any others) may change, especially while modding support is being implemented. In general, your systems will have code in OnUpdate() that acts on a set of entities and modifies their components.
For an example, see the following system, which sets every appliance on fire once:
using Kitchen;
using KitchenMods;
using Unity.Collections;
using Unity.Entities;
namespace MyMod {
public class SetEverythingOnFire : GenericSystemBase, IModSystem {
private EntityQuery Appliances;
struct CHasBeenSetOnFire : IModComponent { }
protected override void Initialise() {
base.Initialise();
Appliances = GetEntityQuery(new QueryHelper()
.All(typeof(CAppliance))
.None(
typeof(CFire),
typeof(CIsOnFire),
typeof(CFireImmune),
typeof(CHasBeenSetOnFire)
));
}
protected override void OnUpdate() {
var appliances = Appliances.ToEntityArray(Allocator.TempJob);
foreach (var appliance in appliances) {
EntityManager.AddComponent<CIsOnFire>(appliance);
EntityManager.AddComponent<CHasBeenSetOnFire>(appliance);
}
appliances.Dispose();
}
}
}
The system uses an EntityQuery to find a set of entites by their components, then take those entities and sets them on fire (by adding CIsOnFire) and ensures they won't be set on fire by this system again (by adding CHasBeenSetOnFire)
¶ Building, running and distributing
The game looks for mods in two places; in a folder called Mods next to the game exe (for development and testing) and via mods subscribed over the Steam workshop.
To develop your mod, build any .dll and place them into its a folder for your mod within Mods (which you may have to create). The game will automatically load any mods in this location (or subscribed on the Steam Workshop) when launching.
To upload your mod to the Steam Workshop, you currently need to be in the Workshop Beta group. You can then use PlateUp_Data/ModUploader.exe which has a GUI to upload your mod. Once uploaded, you can edit mod metadata either via the uploader or via the Workshop page.
¶ Summary
- Mods should be placed inside a named folder in the Mods folder (which you might need to create), in your PlateUp! install directory. If you are unsure where your Steam Library is on disk, you can right click PlateUp! in Steam, properties, installed files, and hit "Browse..." to navigate to the correct file location. Enter the "PlateUp" folder and create the "Mods" folder.
- Code should be placed into one or more .dll files inside the folder
- Content can be placed into one or more .assets files as Unity asset bundles (methods to create these more easily will be available later)
- The game will automatically load your .dll files when launching and then add any components implementing
IModComponentand systems implementingIModSystem - Your systems should probably inherit from
GenericSystemBase(or a subtype) to access PlateUp-specific helpers