Document prefs, screenshots and the 1.1.0 changes

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.0)
-project(AutoSave VERSION 1.0.0)
+project(AutoSave VERSION 1.1.0)
 
 set(CMAKE_CXX_FLAGS "-static -static-libgcc -static-libstdc++ -Wall -Werror")
 set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS} -O2 -DTSFUNCS_DEBUG=false")
@@ -54,4 +54,6 @@ target_link_libraries(${CMAKE_PROJECT_NAME}
 	${TSFUNCS_LIB}
 	minhook
 	psapi
+	gdiplus
+	shlwapi
 )

README.md

@@ -8,6 +8,8 @@ The files use the stock `.bls` format and can be loaded from the normal load scr
 
 Place `AutoSave.dll` in the game's `modules` folder, then quit and start Blockland from Steam. A DLL that is already loaded stays mapped until that restart.
 
+AutoSave installs its scripts from a timer on the game's main loop. It does not patch the console's `evaluate` function, so modules that load after it and look that function up by its first bytes keep working. The console shows `AutoSave: /autosaver is ready` once the chat command is in.
+
 It only saves while this game is the server: a local single-player or multiplayer host, or a dedicated server.
 
 ## Files
@@ -16,18 +18,36 @@ Each save is named for the local time it started, for example `saves/autosave/20
 
 The save is written to `saves/autosave/writing.bls.tmp` and renamed when it is complete, so a crash or cancel never leaves a half-written `.bls`. Old autosaves are not deleted.
 
-`$pref::SaveOwnership` and `$pref::SaveExtendedBrickInfo` are followed the same way the stock save follows them. No screenshot is taken.
+`$pref::SaveOwnership` and `$pref::SaveExtendedBrickInfo` are followed the same way the stock save follows them.
+
+## Preview picture
+
+Each save gets a picture next to it with the same name, for example `saves/autosave/2026-10-26 00-29-28.jpg`. That is the file the load screen shows for a save.
+
+The picture comes from the server preview: the overhead view the game traces for the server list. It is a 768x768 image traced a few pixels per tick on the server, so it works on a dedicated server with no camera. A preview centered with `/setPreviewCenter` keeps that center.
+
+- The engine traces at most 128 pixels per tick. While a picture is wanted, AutoSave also traces pixels itself through the same engine function, 6 ms at a time with a 12 ms pause, and stops while a save is being written. The engine traces the last pixel, so its normal finish still produces the image.
+- If nothing is tracing, AutoSave starts the tracer at the engine's top rate (128 work per tick instead of the default 64). When the picture is done, AutoSave stops the tracer, puts the rate back, and nothing is uploaded.
+- If the game is already tracing its own preview (an internet server does this all the time), AutoSave helps that image along and keeps a copy. The game's upload to the server list is not changed.
+- The console shows the progress every 30 seconds and the time taken, and the chat says when the picture is saved. If the game quits first, that save has no picture. Clearing all bricks stops the tracer, so that save has no picture either.
+- If another save finishes while a picture is still being traced, the picture goes to the newest save.
+
+`/autosaver screenshot off` turns this off. The setting is saved with the other prefs, so it stays off after a restart.
 
 ## When it saves
 
 The first save after starting always runs. After that, a save is skipped if nothing changed. Planting, loading, removing or killing a brick counts as a change. So does adding or clearing events, renaming a brick, and changing its color, paint effect, shape effect, print, collision, raycasting, rendering, light, emitter, item, music, sound or vehicle.
 
+While bricks are loading, the per-brick change checks are skipped, and a finished or cancelled load counts as one change.
+
 A save is also skipped while bricks are loading, while bricks are being cleared, and while the mission is being cleaned up. If a load or a clear starts in the middle of a save, the save stops, its temp file is removed, and the next interval tries again.
 
 ## Large builds
 
 Each slice handles up to the chunk size and stops after 8 ms, then waits at least 12 ms before the next slice. Progress is written to the console every 2 seconds.
 
+Brick values the stock loader sets as fields (angle, baseplate, color, print, color and shape effect, position) are read as fields instead of through method calls. Field names are looked up once, and each datablock's name and print flag are cached per save. The first 64 bricks of each save are also read through the methods; if anything differs, the console says so and the methods are used until the game restarts.
+
 Up to 75000 bricks, bricks are sorted by height like the stock save. Over 75000, the sort and the wrench-extras pass are skipped and the file is written in one pass. The brick count in the header is filled in when the write finishes.
 
 ## Chat commands
@@ -45,17 +65,36 @@ Admins can use:
 - `/autosaver interval <seconds>`: 30 to 86400, default 300
 - `/autosaver chunk <bricks>`: bricks per slice, 1 to 20000, default 4000
 - `/autosaver tick <milliseconds>`: pause between slices, 1 to 1000, default 1 (never less than 12 ms in practice)
+- `/autosaver screenshot on` or `off` (also `screenshots` or `preview`): picture for each save, default on
 
-Out-of-range values are clamped. Changes are announced to everyone. They are not stored, so the defaults return when the game restarts.
+Out-of-range values are clamped. Changes are announced to everyone and saved right away.
 
 `load` uses the file with the newest modified time on disk, including saves made since the game started. It loads with saved ownership and exact colors. The command is case-insensitive.
 
+## Preferences
+
+Settings are server prefs, stored in `config/server/prefs.cs` with the game's other server prefs:
+
+```
+$Pref::Server::AutoSave::Chunk = 4000;
+$Pref::Server::AutoSave::Enabled = 1;
+$Pref::Server::AutoSave::Interval = 300;
+$Pref::Server::AutoSave::Preview = 1;
+$Pref::Server::AutoSave::Tick = 1;
+```
+
+They are read when you start hosting. Until then the timer only checks every 5 seconds whether a server is up. If a pref is missing, the default is used and added to the file the next time the game writes its prefs.
+
+Every `/autosaver on`, `off`, `interval`, `chunk`, `tick` and `screenshot` writes `prefs.cs` right away, using the same export the game runs when custom game settings change. AutoSave only writes the file while a server is running, after the game has loaded it, so other prefs are kept. You can also edit the lines while the game is closed. Values out of range are clamped the same way as in chat.
+
 ## Console
 
 - `autoSave()` starts a save now
 - `autoSaveNewest()` returns the newest autosave path
-- `autoSaveApply()` clamps the settings and restarts the timer
-- `$AutoSave::Enabled`, `$AutoSave::Interval`, `$AutoSave::Chunk`, `$AutoSave::Tick`
+- `autoSaveApply()` clamps the settings, copies them to `$Pref::Server::AutoSave::*`, writes `config/server/prefs.cs` while hosting, and restarts the timer
+- `$AutoSave::Enabled`, `$AutoSave::Interval`, `$AutoSave::Chunk`, `$AutoSave::Tick`, `$AutoSave::Preview` are the live values
+
+A value set on `$AutoSave::*` in the console is not saved, and a new interval does not take effect, until `autoSaveApply()` is called.
 
 ## Build
 
@@ -70,6 +109,6 @@ cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_VERSION_MIN
 cmake --build build
 ```
 
-The result is `build/AutoSave.dll`. CMake is set so the filename has no `lib` prefix. The link line is tsfuncs, MinHook and `psapi`, with static libgcc and libstdc++.
+The result is `build/AutoSave.dll`. CMake is set so the filename has no `lib` prefix. The link line is tsfuncs, MinHook, `psapi`, `gdiplus` (PNG to JPEG for the preview) and `shlwapi`, with static libgcc and libstdc++.
 
-Source is `src/main.cpp` and `CMakeLists.txt`. The current DLL is attached to the v1.0.0 release.
+Source is `src/main.cpp` and `CMakeLists.txt`. The current DLL is attached to the latest release.