This documentation is a work in progress. For more immediate help, try the unofficial modding Discord
PlateUp! supports mods and the Steam workshop. Documentation is a work in progres, but you can use tools such as DNSpy to examine the game's code to see how things are implemented. The unofficial modding Discord is active and very helpful for questions.
To begin, you can look at Getting Started to see how to start creating mods.
PlateUp is written in Unity's ECS framework. This means it's a little bit different to how most Unity games work. In general, most of your code should be written as systems (rather than MonoBehaviors in typical Unity games).
ECS frameworks have three parts; Entities, Components and Systems:
Most of the time you should think purely in terms of components (which are the data) and systems (which are the code).
Systems should contain code, components should contain data. Don't put data in your systems and don't put logic in your components
In PlateUp, there is a component
CPlayer which marks an entity as being a player, and a component
CPosition which indicates that the entity has a position in the world. If you wanted all players to slowly drift upwards, you would write a system which looped over all entities with
CPosition and added a small amount to the position each update.
Writing ECS code feels quite different to Unity's old GameObject/MonoBehavior workflow, but after learning the core concepts it is fairly straightforward. PlateUp contains a number of helpers to make writing code smoother.
Most of your code will be in written in systems. When implementing a new system, there are two key functions, Initialise and OnUpdate.
Systems can use entity queries to gather all the information about a set of entities at once. For our example above, we'd need our system to have one entity query, which would look for entities with
CPosition. In our OnUpdate, the system would access the
CPosition of each entity in the query, move it slightly, and then set it on the entity again.
The ECS framework is very efficient and is optimised to allow systems to loop over and act on large amounts of entities every frame. In general, Unity's ECS systems can loop over and act on thousands of entities every frame without performance problems.
There's nothing wrong with a system that queries and acts on every appliance every frame, even if there are hundreds of appliances
Systems should be as small and have a single purpose wherever possible. It's better to have lots of small systems that work together than one large system that tries to do everything. The part of the game that handles picking up and putting down items is split into more than 20 separate systems. This makes it more modular and easier to expand. The base game has more than 650 systems.
You can modify default game behaviour by adding in new systems. You can also override behaviour by disabling existing systems and implementing them yourself. If you want to maintain most of the behaviour of a system, you can inherit from that system and then disable the parent system.
For more information on writing code in ECS systems, see Systems
PlateUp uses a hybrid ECS approach. This means the game also uses the traditional MonoBehavior/GameObject framework but only for displaying things to players. The game handles most of this for you - any entity with the
CRequiresView will automatically have the view managed for you on all the clients.
In general, you cannot write game logic in views. Views are run by each client independently, and should not access ECS methods. Any code written in a view should only act using client-side information, such as the view data sent to it.
For more information on implementing your own views, see Views
PlateUp is designed to be multiplayer from the ground up. In general, you shouldn't need to do anything special to support multiplayer functionality. Only the host runs the ECS systems, the other players are only transmitted data about views. If your code only involves ECS then only the host will need it. If your code also changes views then clients will need to install it.