diff --git a/README.md b/README.md index b896e4232..bf004ea36 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,21 @@ 

A mod for Cities: Skylines that gives you more control over road and rail traffic in your city

Steam Workshop • Discord Guild • Installation Guide • User Guide • Issue Tracker • Report a Bug

-

+

-> ## Notice -> We are currently working on version 11, which uses Harmony library. If you had any existing pull requests, or repository forks, they will need rebasing to the heavily modified `master` branch. If you need any help, please contact us using the links above. +> ## Notices +> Users: +> * Having problems with traffic despawning after updating roads or rails? Try [Broken Node Detector](https://steamcommunity.com/sharedfiles/filedetails/?id=1777173984) which helps detect a game bug. Colossal Order are aware of the issue. +> * We are currently alpha-testing TM:PE Version 11. If you want to help test, please see [TM:PE V11 alpha test](https://steamcommunity.com/sharedfiles/filedetails/?id=1806963141) in the Steam Workshop. +> Developers: +> * We are currently working on version 11, which uses Harmony library. If you had any existing pull requests, or repository forks, they will need rebasing to the heavily modified `master` branch. If you need any help, please contact us using the links above. ## Current release -> Having problems with traffic despawning after updating roads or rails? Try [Broken Node Detector](https://steamcommunity.com/sharedfiles/filedetails/?id=1777173984) which helps detect a game bug. Collossal Order are aware of the issue. - ### TM:PE [10.21.1 hotfix](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/compare/10.21...10.21.1), 06/07/2019 - Fixed: Speed panel tanks fps if train tracks on screen (thanks rlas & DaEgi01!) (#411, #413) -- Meta: Main changelog refactored (#412) +- Meta: Main changelog refactored (#412) ### TM:PE [10.21](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/compare/10.20...10.21), 02/07/2019 @@ -75,4 +77,4 @@ We will not provide support if: - You are using an older version of the mod. - You are using an older version of Cities: Skylines. -TM:PE is only tested on and updated for the latest version of Cities: Skylines. \ No newline at end of file +TM:PE is only tested on and updated for the latest version of Cities: Skylines. diff --git a/TLM/ATTACHING_DEBUGGER.md b/TLM/ATTACHING_DEBUGGER.md deleted file mode 100644 index 4f2b697de..000000000 --- a/TLM/ATTACHING_DEBUGGER.md +++ /dev/null @@ -1,104 +0,0 @@ -# Attaching Debugger to Cities.exe - -Use this guide to attach a debugger to Cities: Skylines. - -> **Notes:** -> * Attaching a debugger can significantly reduce frame rate and cause lots of lag. -> * This has only been tested on Windows. - -### Setup - -> You only need to follow these steps once to set up your debug environment. - -First, let's backup your current ```mono.dll```: - -* Navigate to ```<%STEAM%>\steamapps\common\Cities_Skylines\Cities_Data\Mono\``` -* Make a backup of ```mono.dll``` (you could just rename it ```mono-backup.dll```) - -> The location of ```<%STEAM%>``` is usually ```C:\Program Files (x86)\Steam``` - -Next, download the following files from [```https://github.com/0xd4d/dnSpy/releases```](https://github.com/0xd4d/dnSpy/releases): - -* ```dnSpy-net472.zip``` -* ```Unity-debugging-5.x.zip``` - -Now we apply a new ```mono.dll``` and test the game is working: - -* Make sure the game is **not** running -* Open ```Unity-debugging-5.x.zip```: - * Navigate to ```Unity-debugging\unity-5.6.6\win64\``` (note: **```unity-5.6.6```**) - * Copy ```mono.dll``` to ```<%STEAM%>\steamapps\common\Cities_Skylines\Cities_Data\Mono\``` -* Run the game to check if it's working: - * If not, delete the downloaded ```mono.dll``` then restore the original version - * You'll have to scour the internet to work out what went wrong, sorry. -* Close the game - -Next, add two environment variables: - -* Press **Win+R** (_Run dialog appears_): - * Enter ```sysdm.cpl``` - * Choose **OK** -* On the **Advanced** tab, choose **Environment Variables...** -* The variables to add are shown below: - -1. > **key:** ```DNSPY_UNITY_DBG``` - > **value:** ```--debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,defer=y,no-hide-debugger``` -2. > **key:** ```DNSPY_UNITY_DBG2``` - > **value:** ```--debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,suspend=n,no-hide-debugger``` - -Finally, unarchive **dnSpy**: - -* Extract the downloaded ```dnSpy-net472.zip``` to a folder - * It can be anywhere, eg. ```dnSpy/``` on your desktop - -### Debugging - -> Do this each time you want to debug the game. - -First, launch **dnSpy**: - -* Run ```dnSpy.exe``` -* On the left, in **Assembly Explorer**, remove any ```.dll``` files that are listed - * Tip: Select one, press **Ctrl+A** then **Delete** - -Now run the game and attach **dnSpy**: - -* Start ```Cities.exe``` -* **Alt+Tab** to **dnSpy** app -* Press **F5** (or choose **Start**) and select: - * **Debug Engine:** ```Unity (Connect)``` - * **Port:** ```55555``` -* Click **OK**: - * You should see an **orange status bar** at the bottom of application with text: ```Running...``` -* From the **Debug** menu, choose **Windows -> Modules** _(Ctrl+Shift+A)_ -* You should see lots of ```.dll``` files and some ```data-00...``` entries -* **Right-click** on any of them, select **Open All Modules**, then * Click **OK** - * The game may hang for few seconds -* On the left, in **Assembly Explorer**, you should see all ```.dll``` files loaded in-game - * There will be some duplicates -* **Right-click** on any of them, then **Sort Assemblies** to make the list easier to work with - -That's it, you are debugging. Now your mods are sure to be bugless :P - -### Reverting - -If you want to return the game back to normal: - -* Exit the game -* Replace the downloaded ```mono.dll`` with your backup of the original ```mono.dll``` -* Start the game - -I'm sure you can work out how to simplify or automate toggling between the two ```mono.dll``` files :) - -### Tips - -* Use **Search** tab _(Ctrl+Shift+K)_ for to find class, property, field, method, etc... -* You can right-click a method definition then select **Analyze** to see where it's used - -### Notes - -* I have no idea why there are duplicated libraries (some sort of protection?) -* Only one copy of each library will have working breakpoints - * After sorting assemblies, it's usually the first instance of a listed file - * Once you know which one it is, you can safely remove the other from Assembly Explorer -* Don't rebuild your mod library with game running, otherwise you'll have to clear Assembly Explorer and open the modules again, which means the duplicates come back diff --git a/TLM/BUILDING_INSTRUCTIONS.md b/TLM/BUILDING_INSTRUCTIONS.md deleted file mode 100644 index 17a02c803..000000000 --- a/TLM/BUILDING_INSTRUCTIONS.md +++ /dev/null @@ -1,50 +0,0 @@ - - -# Project building instructions - - -#### Prerequisites: -* [Git for Windows](https://gitforwindows.org/) / [GitHub Desktop](https://desktop.github.com/) -* one prefered __IDE__ _(Integrated Development Environment)_ to build project: - * Visual Studio 2017 Community (free) - * JetBrains Rider (paid) - * or other similar... -* sources of this repository: - * Git for Windows console: - * use ```git clone https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition``` to download sources of this repository - * after successful cloning type ```cd Cities-Skylines-Traffic-Manager-President-Edition``` - * then ```git submodule update --init --recursive``` to fetch dependencies - * Github desktop: - * clone repository using this link ```https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition.git``` - * dependencies should be installed automatically - -## To build project follow actions: - - -Open __TMPL.sln__ located at ``` \TLM\``` using preferred __IDE__. - -##### Visual Studio: - - * use dropdown from __actions bar__ _(dropdown located under Team menu)_ to select _desired_ solution configuration - * fix missing libraries locations - inside __Solution Explorer__ right click on every project and select __Properties__ - then __Reference Paths__ and add __Managed__ folder from game directory located under ```\Cities_Data\Managed``` - * to build project with selected configuration choose one of actions: - * right click on __TLM__ project from __Solution Explorer__ - * use _Build_ menu -> _Build Solution_ __F6__ - -##### JetBrains Rider: - * currently there is no GUI for adding Reference Paths so you have to create config for every project inside from scratch: - - 1. Create file with extension ```*.csproj.user```named as project name e.g. ```TLM.csproj.user``` - 2. Paste below code inside newly created file and replace `````` with correct path - ``` - - - - \Cities_Data\Managed\ - - - ``` - - * select configuration using dropdown located on _actions bar_ - * use __Ctrl+F9__ to build solution, or __right click__ on solution inside __File Explorer (Alt+1)__ diff --git a/TLM/PR_REVIEW_INSTRUCTIONS.md b/TLM/PR_REVIEW_INSTRUCTIONS.md deleted file mode 100644 index f50c8b0b7..000000000 --- a/TLM/PR_REVIEW_INSTRUCTIONS.md +++ /dev/null @@ -1,23 +0,0 @@ - -## Pull Request Review - - -### Clone PR as new branch inside repository folder: - -#### Github Desktop(Atom-version): -* the PR can be selected from the 'Current Branch' drop-down. - - -#### Git for windows console -* get __PR__ index - this number with __#__ after __PR__ name -* inside project folder ``` \\TLM\ ``` - * type ```git fetch origin pull//head:``` _(skip <>)_ e.g. ```git fetch origin pull/123/head:PR_123``` -* to switch to newly created branch: - * type ```git checkout ``` _(skip <>)_ e.g. ```git checkout PR_123``` - * or use branch switch menu _(usually bottom right corner of preferred __IDE__)_ - - If you don't see new branch to select try to refresh available branches: - * __VS 2017:__ _TeamExplorer -> Refresh_ - * __JB Rider:__ _VCS -> Git -> Fetch_ - -### Now newly created branch should be accessible from branch switch menu diff --git a/docs/ATTACHING_DEBUGGER.md b/docs/ATTACHING_DEBUGGER.md new file mode 100644 index 000000000..fd72fa599 --- /dev/null +++ b/docs/ATTACHING_DEBUGGER.md @@ -0,0 +1,106 @@ +# Attaching Debugger to Cities.exe + +This guide explains how to attach a debugger to Cities: Skylines. + +> **Note:** +> * Attaching a debugger can significantly reduce frame rate and cause lots of lag. +> * This has only works on MS Windows. If you're on a Mac, set up a Boot Camp partition and use that. + +## Setup + +> You only need to follow these steps once + +#### Download the files + +Get these files from [`https://github.com/0xd4d/dnSpy/releases`](https://github.com/0xd4d/dnSpy/releases): + +* `dnSpy-net472.zip` (or later) +* `Unity-debugging-5.x.zip` + +#### Backup `mono.dll`: + +* Navigate to `C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Mono\` + * Change the folder if you installed game somewhere else +* Make a backup of `mono.dll` (you could just rename it `mono-backup.dll`) + +#### Apply debug `mono.dll`: + +* Make sure the game is **not** running +* Open `Unity-debugging-5.x.zip`: + * Navigate to `Unity-debugging\unity-5.6.7\win64\` + * You should check which version of Unity is being used - see first line of your `output_log.txt` + * Copy `mono.dll` to `C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Mono\` +* Run the game to check if it's working: + * If not, delete the downloaded `mono.dll` then restore the original version + * You'll have to scour the internet to work out what went wrong, sorry. +* Close the game + +#### Add environment variables: + +* Press **Win+R** (_Run dialog appears_): + * Enter `sysdm.cpl` + * Choose **OK** +* On the **Advanced** tab, choose **Environment Variables...** +* The variables to add are shown below: + +1. > **key:** `DNSPY_UNITY_DBG` + > **value:** `--debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,defer=y,no-hide-debugger` +2. > **key:** `DNSPY_UNITY_DBG2` + > **value:** `--debugger-agent=transport=dt_socket,server=y,address=127.0.0.1:55555,suspend=n,no-hide-debugger` + +#### Unarchive `dnSpy`: + +* Extract the downloaded `dnSpy-net472.zip` to a folder + * It can be anywhere, eg. `dnSpy/` on your desktop + +## Debugging + +> Do this each time you want to debug the game. + +#### Launch `dnSpy`: + +* Run `dnSpy.exe` +* On the left, in **Assembly Explorer**, remove any `.dll` files that are listed + * Tip: Select one, press **Ctrl+A** then **Delete** + +#### Attach `dnSpy` to game: + +* Start `Cities.exe` +* **Alt+Tab** to **dnSpy** app +* Press **F5** (or choose **Start**) and select: + * **Debug Engine:** `Unity (Connect)` + * **Port:** `55555` +* Click **OK**: + * You should see an **orange status bar** at the bottom of application with text: `Running...` +* From the **Debug** menu, choose **Windows -> Modules** _(Ctrl+Shift+A)_ +* You should see lots of `.dll` files and some `data-00...` entries +* **Right-click** on any of them, select **Open All Modules**, then * Click **OK** + * The game may hang for few seconds +* On the left, in **Assembly Explorer**, you should see all `.dll` files loaded in-game + * There will be some duplicates +* **Right-click** on any of them, then **Sort Assemblies** to make the list easier to work with + +That's it, you are debugging. Now your mods are sure to be bugless :P + +## Reverting + +If you want to return the game back to normal (and greatly improve in-game performance): + +* Exit the game +* Replace the downloaded `mono.dll` with your backup of the original `mono.dll` +* Start the game + +I'm sure you can work out how to simplify or automate toggling between the two `mono.dll` files :) + +## Tips + +* Use **Search** tab _(Ctrl+Shift+K)_ for to find class, property, field, method, etc... +* You can right-click a method definition then select **Analyze** to see where it's used + +## Notes + +* I have no idea why there are duplicated libraries (some sort of protection?) +* Only one copy of each library will have working breakpoints + * After sorting assemblies, it's usually the first instance of a listed file + * Once you know which one it is, you can safely remove the other from Assembly Explorer +* Don't rebuild your mod library with game running, otherwise you'll have to clear Assembly Explorer and open the modules again, which means the duplicates come back diff --git a/docs/BUILDING_INSTRUCTIONS.md b/docs/BUILDING_INSTRUCTIONS.md new file mode 100644 index 000000000..21ea2039b --- /dev/null +++ b/docs/BUILDING_INSTRUCTIONS.md @@ -0,0 +1,131 @@ +# Solution building instructions + +This guide explains how to: + +* Install required software +* Clone the repository (source code) to your local computer +* Build (compile) the source code to DLL files +* Test in-game + +We strongly recommend doing development work on Windows as there's much more tooling available. If you're using a Mac, set up a Boot Camp partition for Windows and use that. If you're using Linux, consult the internets. + +## Install + +> You only need to do these steps once + +The following software is required... + +* IDE (Integrated Development Environment), either: + * [Visual Studio Community](https://visualstudio.microsoft.com/vs/) (free) + * Important: [2019 version](https://docs.microsoft.com/en-us/visualstudio/releases/2019/release-notes) (or later) must be used ([why?](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/pull/463)) + * [JetBrains Rider](https://www.jetbrains.com/rider/) (paid) +* GitHub client, either: + * [GitHub Desktop](https://desktop.github.com/) (recommended if you are not used to working with GitHub) + * [Git for Windows](https://gitforwindows.org/) + +If desired, there are some [additional tools listed in the wiki](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/wiki/Dev-Tools). + +## Clone + +> You only need to do these steps once + +This will clone the source code to your local machine... + +#### GitHub Desktop: + +* Go to [the online repository](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition) +* Click the green **Clone or Download** button and choose **Open in Desktop** +* Follow on-screen instructions (dependencies will be handled automatically) + +#### Git for Windows: + +* Open the inbuilt console +* Use `git clone https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition` clone repository locally +* Then `cd Cities-Skylines-Traffic-Manager-President-Edition` +* Then `git submodule update --init --recursive` to fetch dependencies + +## Environment + +> You only need to do these steps once + +#### Dependencies + +TM:PE relies on several `.dll` files bundled with the game. They can be found in the following folder (may be different folder depending on where game is installed): + +> `C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Managed\` + +You'll have to link the dependencies using _only one_ of the following methods: + +* Create a `\TLM\dependencies` folder and copy in the `.dll` files +* Create a `\TLM\dependencies` symlink to the `...\Managed` folder shown above +* Manually add reference paths to each project in the solution. + +If you choose the latter option, the procedure depends on your IDE. + +In Visual Studio: + +* Open `\TLM\TMPL.sln` in your IDE, then... +* For each project listed in the **Solution Explorer** (right sidebar): + 1. Right-click the project, then choose **Properties** + 2. Select **Reference Paths** on the left + 3. Add folder: `C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Managed\` (may be different folder depending on where game is installed) + +In JetBrains Rider: + +* At time of writing, there is no GUI for adding Reference Paths so you have to do it manually: + * For each project, create a `.csproj.user` file (in the folder of that project) + * For example, the `TLM` project needs a `TLM.csproj.user` file (in the `\TLM` folder) + * Paste in the following code, editing the path if necessary: +```xml + + + + C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines\Cities_Data\Managed\ + + +``` + +#### Enable Roslyn Analyzers + +This is only required for the JetBrains Rider IDE: + +* [Activate Roslyn Analyzers](https://www.jetbrains.com/help/rider/Settings_Roslyn_Analyzers.html) ([why?](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/pull/463)) + +## Build + +This will compile the source code to DLL files... + +#### Configurations: + +There are several build configurations, but we mostly use just three: + +* `DEBUG` - this build enables all kinds of debug features, including the in-game debug menu, debug overlays and debug logging + * Mod display name will include `DEBUG` +* `RELEASE` - this build is for public releases of the `STABLE` edition of TM:PE + * Mod display name will include `STABLE` +* `RELEASE LABS` - this build is for the public releases of the `LABS` edition of TM:PE + * Mod display name will include `LABS` + +#### In Visual Studio: + +* Choose desired build configuration + * Use the drop-down on the toolbar (it's adjacent to `Any CPU`) +* Then build the project: + * Right-click **TLM** project in **Solution Explorer** and choose **Build** + * Or, **Build > Build Solution** (shortcut: `Ctrl` + `Shift` + `B`) + +#### In JetBrains Rider: + +* Choose desired build configuration + * Use the dropdown on the actions bar (under Team menu) +* Then build the project: + * Right-click **TLM** project in **Solution Explorer** and choose **Build** + * Or, **Build > Build Solution** (shortcut: `F6`) + +#### Testing: + +The built DLL files are automatically copied over to the local mods folder of the game if the build is successful. If not, check the post-build events for the `TLM` project. + +Once built, you should be able to test the mod in-game. Remember to enable it in **Content Manager > Mods**. + +If you have any problems, let us know! diff --git a/docs/LOGGING.md b/docs/LOGGING.md new file mode 100644 index 000000000..fdc5ccf97 --- /dev/null +++ b/docs/LOGGING.md @@ -0,0 +1,212 @@ +# Logging in TM:PE + +This guide explains: + +* Why we use `TMPE.log` +* How to enable predefined debug logging +* Log methods and when to use them + +> TM:PE logging is not as simple as one would expect, [because reasons](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/issues/349#issuecomment-512650775). + +## Why `TMPE.log`? + +The game log (either `output_log.txt` on Windows, or `Player.log` on Mac/Linux) is generally huge and difficult to browse, so we use a dedicated `TMPE.log` to make life a bit easier for ourselves. + +The log file location depends on operating system: + +* Windows: Same folder as your `output_log.txt` +* Mac: See [Issue #379](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/issues/379) +* Linux: Probably in `~/.config/unity3d/Colossal Order/Cities: Skylines/TMPE.log` + +More importantly, TM:PE has lots of ready made logging that can be turned on or off as required... + +## Log switches + +Log switches determine which sets of existing log messages are output to the `TMPE.log`. + +### Toggling existing switches + +Build the solution in `DEBUG` mode, then launch Cities: Skylines, then open mod settings to ensure the global config is updated. + +This will add a `` section to the `TMPE_GlobalConfig.xml` file, which can be found in the following folder (may be different depending on where you installed the game): + +> `C:\Program Files (x86)\Steam\steamapps\common\Cities_Skylines` + +The relevant section looks like this: + +```xml + + + false + false + ... + + None + None + +``` + +The boolean values correlate to the `Switches[]` array in `TLM/State/ConfigData/DebugSettings.cs`. + +To enable a logging for a switch, change it's value from `false` to `true` and save the changes. + +The `TMPE_GlobalConfig.xml` will then need to be reloaded: + +* In TM:PE mod options, select the **Maintenance** tab +* Click the **Reload global configuration** button + +Logging associated with that switch will now be output to the `TMPE.log` file. + +### Extended options + +Some of the existing logging can be filtered to specific vehicle types or path modes. You can define those in the `TMPE_GlobalConfig.xml` via the following elements (`None` means "don't filter"): + +```xml +None +None +``` + +### Adding new switches + +In `TLM/State/ConfigData/DebugSettings.cs`: + +* Add a new `DebugSwitch` enum value +* Add the default value to the `Switches` array + +> If your `TMPE_GlobalConfig.xml` already contains the `` section, remember to add a new `` element _before_ launching the game. + +Once the switch is defined, you can then use it with applicable logging methods listed below. + +## Logging methods + +We use our own logging class that provides some features tailored to the specific needs of TM:PE. + +The `static` logging class can be found in [`CSUtil.Commons/Log.cs`.](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/blob/master/TLM/CSUtil.Commons/Log.cs) + +### Performance considerations + +Large swathes of TM:PE code is called every frame. Logging needs to be performance tuned. + +> Note: We could probably, at some point, make the log writer run in its own thread, but haven't got round to that yet. + +#### Log.Info, Log.Warning, Log.Error, Log.\_Debug, Log.\_Trace: + +* String is formatted at call site +* ⚠ Expensive if multiple `$"string {interpolations}"` are used +* ✔ Cheap if wrapped in an `if (booleanValue) { ... }` +* ✔ Cheap if there is a const string or a very simple format call with a few args +* `Log._Debug()` and `Log._Trace()` calls are removed by compiler in all `RELEASE` builds + +#### Log.InfoFormat, Log.\_DebugFormat, etc.: + +* Message formatted at callee site, during logging +* ⚠ Expensive if not wrapped in a `if (boolValue) { ... }` condition +* ✔ Good for very long format strings with multiple complex arguments +* ✔ As they use format string literal, it can be split multiple lines without performance penalty +* ✔ Prevents multiple calls to `string.Format()` unlike multiline `$"string {interpolations}"` +* 💲 The cost incurred: building args array (with pointers) +* `Log._DebugFormat()` calls are removed by compiler in all `RELEASE` builds + +#### Log.WarningIf, Log.\_DebugIf, etc: + +* If the condition is `true`, invoke the lambda and log the string it returns +* ⚠ Cannot capture `out` and `ref` values +* ✔ Lambda building is just as cheap as format args building +* ✔ Actual string is formatted ONLY if the condition holds true +* 💲 The cost incurred: Each captured variable is copied into lambda function +* `Log.DebugIf()` calls are removed by compiler in all `RELEASE` builds + +#### Log.NotImpl: + +* Use to log an error if an unimplemented method is called +* `Log.NotImpl()` calls are removed by compiler in all `RELEASE` builds + +### All builds + +These methods are available in all builds, including `RELEASE`. + +> :warning: Use sparingly and avoid in-game usage as they will [completely tank frame rate](https://github.com/krzychu124/Cities-Skylines-Traffic-Manager-President-Edition/issues/411). + +#### `Log.Info(str)` + +Writes a simple string to the log file. + +```csharp +Log.Info("Hello world!"); +``` + +Avoid concatenating multiple `$"string {interpolations}"` as it's very expensive; use `Log.InfoFormat()` instead. + +#### `Log.InfoFormat(format, args)` + +```csharp +Log.InfoFormat("Some {0} {1} {3}", "string", "with", "args"); +``` + +#### `Log.Warning(str)` + +Like `Log.Info()` but at warning level. Also outputs a stack trace. + +#### `Log.WarningFormat(format, args)` + +Like `Log.InfoFormat()` but at warning level. Also outputs a stack trace. + +#### `Log.WarningIf(switch, func)` + +Similar to `Log.Warning()` but the string is generated by a lambda function (`func` param). + +The function is only called, while logging, if `switch` evaluates to `true`. + +```csharp +Log.WarningIf(DebugSwitch.LaneConnections.Get(), () => $"string {interpolation}"); +``` + +#### `Log.Error(str)` + +Like `Log.Info()` but at error level. Also outputs a stack trace. + +#### `Log.ErrorFormat(format, args)` + +Like `Log.InfoFormat()` but at error level. Also outputs a stack trace. + +#### `Log.ErrorIf(switch, func)` + +Like `Log.WarningIf()` but at error level. Also outputs a stack trace. + +### Debug builds only + +Methods prefixed with `_`, and also the `NotImpl()` method, are only available in `DEBUG` build configurations. + +#### `Log._Debug(str)` + +Like `Log.Info()` but at `Debug` level. + +#### `Log._DebugFormat(format, args)` + +Like `Log.InfoFormat()` but at `Debug` level. + +#### `Log._DebugIf(switch, func)` + +Like `Log.WarningIf()` but at `Debug` level (no stack trace). + +#### `Log._DebugOnlyWarning(str)` + +Like `Log.Warning()`. + +#### `Log._DebugOnlyWarningIf(switch, func)` + +Like `Log.WarningIf()`. + +#### `Log._DebugOnlyError(str)` + +Like `Log.Error()`. + +#### `Log._Trace(str)` + +Like `Log.Info()` but at `Trace` level. + +Requires both the `DEBUG` and `TRACE` defines. + +#### `Log.NotImpl(str)` + +Like `Log.DebugOnlyError()` but prefixes the string with `Not implemented:`. diff --git a/docs/PR_REVIEW_INSTRUCTIONS.md b/docs/PR_REVIEW_INSTRUCTIONS.md new file mode 100644 index 000000000..9f565a0e1 --- /dev/null +++ b/docs/PR_REVIEW_INSTRUCTIONS.md @@ -0,0 +1,41 @@ +# Reviewing a Pull Request (PR) + +In addition to code review (via online diffs), you'll also need to build the PR locally to test it in-game. + +## Before you start + +If you haven't already done so, work through the [BUILDING_INSTRUCTIONS](./BUILDING_INSTRUCTIONS.md) guide to ensure your environment is set up, configured and building properly. + +## Cloning the PR + +#### GitHub Desktop: + +* Choose the PR from the **Current Branch** drop-down +* If prompted, choose **Switch Branch** (don't change anything on the dialog) +* If the panel at the top shows an option to `Pull`, click it to pull any recent commits + +#### Git for windows: + +* You'll need the PR number (shown at end of URL in the PR online) +* Open the inbuilt console +* Inside project folder `\\TLM\`: + * `git fetch origin pull//head:` + * For example: `git fetch origin pull/123/head:PR_123` for PR #123 +* Switch to new branch: + * `git checkout ` + * For example: `git checkout PR_123` + +#### In the IDE: + +* You can also clone a PR directly within the IDE +* Use branch switch menu - it's usually in the bottom-right corner +* If you don't see the PR branch, refresh branches: + * Visual Studio: + * Open **Team Explorer** (tab on the bottom of Solution Explorer panel in the sidebar) + * Click the blue **Refresh** icon (next to the green plug icon under the Team Explorer panel title bar) + * JetBrains Rider: + * Choose **VCS** -> **Git** -> **Fetch** + +## Building the PR + +See the **Build** section in [BUILDING_INSTRUCTIONS](./BUILDING_INSTRUCTIONS.md) guide \ No newline at end of file