Motivation / Problem

Given a series of save files from the same running game, it's possible to use a game_start.scr script in conjunction with openttd -g to quickly run through each save file and automatically generate screenshots. Such screenshots can be useful to generate a video of how a map progressed and changed over time. This works great for "whole map/world" screenshot types, like minimap or even giant screenshots of small- to moderately-sized games.

If you have a larger-sized game, or if you have a particularly interesting smaller area of the map, then you might want to instead make a series of "visible area" screenshots. However, your save files might have been made whilst the game was at different zoom levels or different locations, and unfortunately

• while a scrollto command exists, there's no zoomto, and
• even though scrollto exists, taking a screenshot immediately after scrollto doesn't correctly reflect the new map location.

These changes would benefit the "model railway" group of players who want to storytell (e.g. to "replicate historical scenarios").

Description

This patchset enables a game_start.scr script like the following to be used:

zoomto 0
scrollto instant 45 65
zoomto 2
screenshot normal
exit

zoomto is a new console command that allows the zoom level of the main window viewport to be manipulated, whereas the optional instant argument for scrollto makes the screenshot command work correctly (the fact it doesn't work today might be considered a bug and there might exist some other way to do this, see next section).

Discussion

• in implementing zoomto, I settled on two while()s that call into DoZoomInOutWindow(), but this might be doing too much work if jumping multiple zoom levels; I also tried other alternatives that seemed to work just fine (e.g. setting vp->zoom directly, updating vp->virtual_width/vp->virtual_height w/ ScaleByZoom(), calling MarkWholeScreenDirty()), but I wasn't sure if these would be as safe as DoZoomInOutWindow()

• calling scrollto followed immediately by screenshot in a script doesn't work without this patch allowing scrollto to be "instant" (without "instant", you will get a screenshot of where the map was before asking for the scrollto), and initially one would think that this is due to smooth scrolling being enabled, but even turning that off before calling scrollto doesn't fix the problem; calling ScrollMainWindowToTile() with its instant flag enabled does fix the problem, though, so the instant argument here surfaces that to the console... but alternatively...

  • maybe the user-facing version of the command should be left as-is and instant=true should always be passed?,
    or
  • maybe there is a way to mark the viewport dirty at the end of scrollto in such a way without instant=true that screenshot will work?,
    or
  • maybe there is something that could be fixed in the screenshot command or in something like SetupScreenshotViewport()?

Checklist for review

Some things are not automated, and forgotten often. This list is a reminder for the reviewers.

• The bug fix is important enough to be backported? (label: 'backport requested')
• This PR touches english.txt or translations? Check the guidelines
• This PR affects the save game format? (label 'savegame upgrade')
• This PR affects the GS/AI API? (label 'needs review: Script API')
  • ai_changelog.hpp, gs_changelog.hpp need updating.
  • The compatibility wrappers (compat_*.nut) need updating.
• This PR affects the NewGRF API? (label 'needs review: NewGRF')
  • newgrf_debug_data.h may need updating.
  • PR must be added to API tracker