docs: explain bitmap resolution configuration option

Author: aspizu

docs/configuration.md

@@ -63,6 +63,25 @@ Specify the order in which sprites are layered, by default the order is undefine
 layers = ["sprite_name_1", "sprite_name_2"]
 ```
 
+## Bitmap Resolution
+
+Controls the resolution handling for bitmap images (PNG, BMP) in your project.
+
+```toml
+bitmap_resolution = 2 # default is 1
+```
+
+### How Bitmap Resolution Works
+
+Scratch internally uses high-resolution bitmaps where each screen pixel corresponds to 4 image pixels (2x scale factor). This setting determines how goboscript handles this scaling:
+
+- **`bitmap_resolution = 1`** (default): Your images are stored as-is, and Scratch automatically scales them up by 2x when the project loads. Use normal-sized images (e.g., 480x360 for full stage backdrops).
+
+- **`bitmap_resolution = 2`**: Your images are treated as high-resolution and displayed at half their pixel size. You must provide double-sized images (e.g., 960x720 for full stage backdrops) to achieve the same visual size.
+
+!!! NOTE
+    This setting only affects bitmap formats (PNG, BMP). Vector formats (SVG) are unaffected.
+
 ## Turbowarp options
 
 goboscript can generate a turbowarp configuration comment inside the Stage.