From 55ea7425b2b97458a14c480d976d2470372086e5 Mon Sep 17 00:00:00 2001 From: RallyBlock Date: Mon, 26 Oct 2026 11:08:03 -0400 Subject: [PATCH] Add README --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ea763d2 --- /dev/null +++ b/README.md @@ -0,0 +1,75 @@ +# AutoSave + +Server module for Blockland v21. While you host, it saves every brick on the server to `saves/autosave/` on a timer. A save is written a few milliseconds at a time, so the server keeps ticking during a large save. + +The files use the stock `.bls` format and can be loaded from the normal load screen. + +## Install + +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. + +It only saves while this game is the server: a local single-player or multiplayer host, or a dedicated server. + +## Files + +Each save is named for the local time it started, for example `saves/autosave/2026-10-26 00-29-28.bls`. Windows does not allow colons in file names, so the time uses hyphens; the description line inside the file uses colons. If a file with that name already exists, ` (2)`, ` (3)` and so on is added. + +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. + +## 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. + +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. + +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 + +Anyone can use: + +- `/autosaver help` +- `/autosaver status` + +Admins can use: + +- `/autosaver on` and `/autosaver off` +- `/autosaver save` (or `now`): save right away +- `/autosaver load` (or `reload`): clear all bricks, then load the newest file in `saves/autosave/` +- `/autosaver interval `: 30 to 86400, default 300 +- `/autosaver chunk `: bricks per slice, 1 to 20000, default 4000 +- `/autosaver tick `: pause between slices, 1 to 1000, default 1 (never less than 12 ms in practice) + +Out-of-range values are clamped. Changes are announced to everyone. They are not stored, so the defaults return when the game restarts. + +`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. + +## 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` + +## Build + +Blockland is a 32-bit program, so the DLL has to be built with a 32-bit MinGW toolchain (`i686-w64-mingw32`). Put that toolchain's `bin` directory first on `PATH` so CMake finds that `gcc` and `mingw32-make`. + +`find_package(TSFUNCS)` needs a tsfuncs 1.0.1 package: `tsfuncs-config.cmake` next to `include/` and `lib/`. MinHook's cmake package lives under that package's `lib/minhook`. Pass the package directory as `CMAKE_PREFIX_PATH`. + +From this repo: + +``` +cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_VERSION_MINIMUM=3.5 -DCMAKE_PREFIX_PATH=C:/path/to/tsfuncs -S . -B build +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++. + +Source is `src/main.cpp` and `CMakeLists.txt`. The current DLL is attached to the v1.0.0 release.