Feature: NewGRF callback profiling (#7868)

Adds a console command newgrf_profile to collect some profiling data about NewGRF action 2 callbacks and produce a CSV file.

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/logging_and_performance_metrics.md b/docs/logging_and_performance_metrics.md
index 9f0679acd..1f5866aba 100644
--- a/docs/logging_and_performance_metrics.md
+++ b/docs/logging_and_performance_metrics.md
@@ -99,3 +99,43 @@ The following is an explanation of the different statistics:
 If the frame rate window is shaded, the title bar will instead show just the
 current simulation rate and the game speed factor.
 
+## 3.0) NewGRF callback profiling
+
+NewGRF developers can profile callback chains via the `newgrf_profile`
+console command. The command controls a profiling mode where every sprite
+request is measured and logged, and written to a CSV file in the end.
+
+The NewGRF developer tools need to be enabled for the command to function.
+
+View the syntax for the command in-game with the console command
+`help newgrf_profile`.
+
+Profiling only works during game or in the editor, it's not possible to
+profile across the main menu, world generation, or loading savegames.
+
+The CSV files contain one line per sprite request during the profiling.
+They can get very large, especially on large games with many objects from
+the GRF. Start profiling short periods such as 3 or 7 days, and watch the
+file sizes.
+
+The produced CSV file contains the following fields:
+
+- *Tick* - Game tick counter, this may wrap to zero during recording.
+  Mainly useful to distinguish events from separate ticks.
+- *Sprite* - Index of the root Action 2 sprite in the GRF file. This is
+  the sprite group being resolved.
+- *Feature* - NewGRF feature number the sprite group is being resolved for.
+  This will be 0xFF for AI purchase selection and ambient sound callbacks.
+- *Item* - The id of the item within the GRF. For cargotypes, railtypes,
+  roadtypes, and tramtypes, this is the integer representation of the label.
+- *CallbackID* - The type of callback being resolved. ID 0 is regular graphics
+  lookup. See the `newgrf_callbacks.h` file in the OpenTTD source code for the
+  full list of callback IDs.
+- *Microseconds* - Total time spent to resolve the Action 2, in microseconds.
+- *Depth* - Number of recursive Action 2 lookups were made during resolution.
+  Value zero means the sprite group resolved directly.
+- *Result* - Result of the callback resolution. For lookups that result in
+  a sprite, this is the index of the base action 2 in the GRF file. For
+  callbacks that give a numeric result, this is the callback result value.
+  For lookups that result in an industry production or tilelayout, this
+  is the sprite index of the action 2 defining the production/tilelayout.