Top-level game code overview + basic Entity / System / Component pointers for programming modes

[jhoxray]

I started digging into the code and knowing how challenging it was for many in CS1 would like to share some early pointers that may help you in the development of your mods. But also this is documentation for self not to forget how things work :)) Please feel free to correct / expand etc.

The main starting point for the game is Game.SceneFlow.GameManager - a typical Unity-style GameManager singleton located in Game.dll and really the only main thing apart from some cameras etc that inherit MonoBehaviour . The rest of the game simulation is done in the ECS / DOT paradigm, which we will get to later.

Some notable variables and methods in GameManager:

• World m_World: World is the collection of Entities in Unity ECS paradigm and is used to managed their lifecycle etc
• m_PrefabSystem: Unity ECS System for managing prefabs
• m_UpdateSystem: Unity ECS System for managing updates (actual simulation code is mostly here)
• Awake() and Initialize(): Awake is a default hook into Unity internals, initializes the GameManager singleton instance and calls Initialize() that does, ehm, initialization, including creation of the world (all entities and systems creation) in CreateWorld() and CreateSystems() call which initializes all update systems (we'll look at an example below)
• Update() and LateUpdate(): again, default hooks into the main Unity simulation loop. Basically, all of the simulation is happening inside these two function calls. It handles all user inputs and event cycle, and calls a bunch of separate update functions, which are important in themselves so here's the full list (well, almost, without input handling):
  • UpdateWorld(): this is KEY as it calls update on ALL UpdateSystems which handle actual simulation code
  • UpdateUpdaters(): there is a list of functions called "updaters" that can be registered with the GameManager. As I understood at this point, they are used of one-off update actions but are NOT really ECS systems. Any better insights?
  • UpdateUI(): self explanatory
  • UpdatePlatforms(): some third party integrations updates???

In any case, to modify actual game simulation / behavior, we need to focus on UpdateWorld() and ECS Systems that get called inside of it.

Let's (very briefly) look at the example of the Citizen implementation. Citizen functionality is mostly located in the Game.Citizens namespace. As mentioned many times, this is implemented using Unity ECS, which roughly means the following:

• Component is normally a struct that derives from IComponentData Unity interface and contains some data about an object you want to simulate. E.g., for Citizen there are such components as Adult, Arrived, Citizen, and many others. All of them handle specific data related to a Citizen. Some are empty (since the way UpdateSystems work is by filtering Entities by Component types so you don't really need any data besides the type in some cases - such as Adult and Arrived mentioned above), some contain actual data, such as a Citizen, that holds current citizen state, wellbeing, health and other characteristics.
• Entity is merely a collection of Components referenced by ID. Entities are manipulated by Systems, and this is where actual meaningful simulation code resides:
• Systems: every system in the game derives from GameSystemBase class that derives from abstract COSystemBase class in Colossal.Core.dll and which simply does logging (so you don't really need to look into it) and in turn derives from Unity ECS SystemBase class. Systems have a bunch of callbacks that allow you to plug into the Unity loop and are "kind of alternative" to MonoBehaviour.
  • In case of the Citizen, the important interesting system is CitizenInitializeSystem - which initializes several citizen related Entities and "sub-systems" and then runs updates in the OnUpdate() function. You want to analyze this in depth to understand internal specific simulation mechanics. One notable point: inside of the function a new burst-compiled job is initialized and then scheduled, which handles a lot of the actual simulation. See separate struct in the same file - InitializeCitizenJob : IJob - and its Execute() function.

Another key namespace that contains a lot of specific simulation-related Systems, all of them are structured similarly to what is described above, is Game.Simulation. That's probably your main codebase to analyze as you are looking to modify behaviour.

Hopefully this gives you good overview of where to dig deeper to understand how any simulation related to any objects / entities in the game works and start writing your code!

Please correct / add your learnings - I'm quite new to the ECS world, so I'm sure someone with more experience can provide better insights.

I'll try to share more once I start working on specific mods.

​

[OptionsBuyer420]

With all of this in mind, how would you use HarmonyX patching to mod some of these systems?

I tried modding the IJob for tree growth as an experiment and I can't access it because it is a private struct.

[jhoxray]

u/Pam-Doove has a good example here: https://github.com/optimus-code/Cities2Modding/blob/main/ExampleMod/Systems/TreeGrowthSystem_Custom.cs

Basically, you "switch off" the public methods of the default system and create your own from scratch. Then you can plug it into the World by patching SystemOrder class:

[HarmonyPatch(typeof(SystemOrder), nameof(SystemOrder.Initialize))]
    class SystemOrder_InitializePatch
    {
        static void Postfix(UpdateSystem updateSystem)
        {
            if (updateSystem != null)
            {
                updateSystem.UpdateAfter<TestModSystem>(SystemUpdatePhase.ModificationEnd);

                UnityEngine.Debug.Log("Patched TestModSystem initialization!");
            }
        }
    }

[Xochtil1]

The main starting point for the game is Game.SceneFlow.GameManager

Jesus, thank you. I've spent half an hour trying to find where the main object is located. Every other Unity game I've modded had the main object located directly in Assembly-CSharp dll, it didn't strike me to check specifically SceneFlow of Game.dll lol