From c8779fb311c2665d3fc45c18b2f3460cd998d179 Mon Sep 17 00:00:00 2001 From: Niels Martin Hansen Date: Sun, 26 Jan 2020 13:45:51 +0100 Subject: 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. --- docs/logging_and_performance_metrics.md | 40 +++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'docs/logging_and_performance_metrics.md') 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. -- cgit v1.2.3-54-g00ecf