Documentation: Updates in prep for v0.2

Author: zephyris

CHANGELOG.md

@@ -1,10 +1,18 @@
 # OpenGFX2 Changelog
 
-# v0.1
+## v0.2
 Base set:
-* First OpenGFX-independent baseset
-* 8bpp 1x zoom 'Classic' variant
-* 32bpp 4x zoom 'High Def' variant
+* Bug fixes from v0.1, including a few game-breaking missing (white box) sprites.
+* Initial support for 2x GUI scaling (including in 'Classic' variant).
+
+Settings NewGRF:
+* Parameter control of grass (terrain tile), foundation and tree style per climate. Almost fully mix-and-match.
+
+## v0.1
+Base set:
+* First OpenGFX-independent baseset.
+* 8bpp 1x zoom 'Classic' variant.
+* 32bpp 4x zoom 'High Def' variant.
 'Classic' is a complete baseset. 'High Def' 32bpp and 4x zoom sprites are not universally complete, and uses 8bpp 1x zoom fallbacks.
 
 Settings NewGRF:

README.md

@@ -1,41 +1,63 @@
 # OpenGFX2
 # ![opengfx2_titletext](https://github.com/zephyris/opengfx2/assets/2762690/1adabdf4-baf8-48b2-ae35-279c3d808d0e)
 
-Work-in-progress / development repo for an "OpenGFX v2". Or maybe that should be "OpenGFX director's edition", "refactored OpenGFX", or perhaps "OpenGFX extra zoom" or "OpenGFX 32bpp". Or some combination of all of them.
+"OpenGFX2" graphics base set for [OpenTTD](https://github.com/OpenTTD/OpenTTD). This is a spiritual successor to [OpenGFX](https://github.com/OpenTTD/OpenGFX). Think of it as "OpenGFX version 2", or maybe that should be "OpenGFX director's edition", "refactored OpenGFX", or perhaps "OpenGFX extra zoom" or "OpenGFX 32bpp". Or some combination of all of them.
 
 Partly derived directly from OpenGFX, partly redrawn or revised from my original 32bpp sources. Almost all sprites have been updated or revised.
 
 Features far better organisation of sprites. Extensive use of automated composite sprite generation using Python of bubious quality. Drawn and coded with extra zoom levels and 32bpp in mind.
 
 ## Quick start
 
+### In-game content downloader / BaNaNaS
+It is easiest to use the in-game content downloader (`Check Online Content` in the OpenTTD main menu).
+
+To install, search for `OpenGFX2`, tick the checkbox next to OpenGFX2 Base graphics, and hit `Download`.
+
+To set as the base graphics set, go to `Game Options > (Graphics) > Base Graphics` from the OpenTTD main menu. Select `OpenGFX2 Classic`, then close the `Game Options` window.
+
+### Manual download
 Download a release from [the prebuilt grf releases](https://github.com/zephyris/opengfx2/tags) and install using the instructions below.
 
-Thease are early release previews not available in the in-game content downloader.
+These are early release previews not available in the in-game content downloader. This includes base set versions (the "High Def" 32bpp 4x zoom version) and NewGRFs not yet available through the in-game downloader.
 
-## Building
-Requires `git lfs` for large file handling.
+### Installation
+Install the baseset by copying `opengfx2_8.tar` and/or `opengfx2_32ez.tar` into the `baseset` directory for your OpenTTD installation.
 
-Requires a system which can run `bash` shell scripts, `python3` with `PIL`, `blend-modes`, `numpy`, `skimage`, `nmlc`, `concurrent`, `multiprocessing`, `tqdm`.
+Install the newgrfs by copying each `.grf` file into the `newgrf` directory for your OpenTTD installation.
 
-Clone the repository and run `make_all.sh`, it will take a long time...
+To set as the base graphics set, go to `Game Options>(Graphics)>Base Graphics` Set and select `OpenGFX2 Classic` (8bpp 1x zoom version) or `OpenGFX2 High Def` (32bpp 4x zoom version).
 
-The built baseset will be in `baseset/`, called `opengfx2.tar`.
+To set OpenGFX2 settings, go to `NewGRF Settings`, find `OpenGFX2 Settings` and add to `Active NewGRF files`. Then, select `OpenGFX2 Settings` in the `Active NewGRF files list` and select `Set parameters` then adjust the settings. This is a bit of a hack, and will hopefully change in the future.
 
-The build newgrf(s) will be in `newgrf/`.
+Install other NewGRFs as normal using `NewGRF settings`.
 
-## Installation
-Install the baseset by copying `opengfx2.tar` into the `baseset` directory for your OpenTTD installation.
+## Building
+These notes are for if you want to build OpenGFX2 from the source files. If you just want to download OpenGFX2 then you don't need to worry about these.
 
-Install the newgrfs by copying each `.grf` file into the `newgrf` directory for your OpenTTD installation. 
+Requires `git lfs` for large file handling. Once `git lfs` is installed then clone using `git` as normal.
 
-To set as the base graphics set, go to `Game Options>(Graphics)>Base Graphics` Set and select `OpenGFX2`.
+Requires a system which can run `bash` shell scripts, `python3` with `PIL`, `blend-modes`, `numpy`, `skimage`, `nmlc`, `concurrent`, `multiprocessing`, `tqdm`. This has been developed using Windows Subsystem for Linux (WSL) and might have peculiarities (eg. incorrect file permissions) on a real Linux install.
 
-To set OpenGFX2 settings, go to `NewGRF Settings`, find `OpenGFX2 Settings` and add to `Active NewGRF files`. Then, select `OpenGFX2 Settings` in the `Active NewGRF files list` and select `Set parameters` then adjust the settings. This is a bit of a hack, and will hopefully change in the future.
+### To build
+Clone the repository, navigate to the repository root directory and run `make_all.sh`. It will take a long time...
 
-Install other NewGRFs as normal using `NewGRF settings`.
+The built baseset will be in `baseset/`, making different versions called `opengfx2_<version>.tar`.
+
+The build newgrf(s) will be in `newgrf/`, making various `.grf` files.
+
+### Build process notes
+Image processing makes a bunch of intermediate files, particularly `*_8bpp.png` and things in `pygen` directories. Others are `_bt32bpp`, `_rm32bpp.png`. These files are assumed to be temporary intermediates, and any user-modified versions will be blindly overwritten. Make sure you look at `.gitignore` see which files this applies to.
+
+Files processed by `python` and encoded by `nml` are `.png` files, but those may be derived from other sources. Raw sprites were variously drawn\generated in Paint.NET, Aseprite, Blender and more. Conversion from those raw sources to `.png` files is not part of the build process - it must be done manually.
+
+## Development
+These notes are to help development. If you are just downloading or building OpenGFX2 then you don't need to worry about these.
 
-## Further notes
-Image processing makes a bunch of intermediate files, particularly `*_8bpp.png` and things in `pygen` directories.
+### Release preparation
+Remember to bump the versions: 
+* Base set version in `baseset/baseset_generate_obg.py`
+* NewGRF versions in `newgrf/nml/<newgrf_name>/<newgrf_name>-header.pmnl`
+* `extra.grf`/`opengfx2_settings.grf` co-compatibility check in `baseset/nml/extra-header.pnml`
 
-Files used by `python` are `.png` files, but those may be derived from other sources. Raw raw sprites wre variously drawn\generated in Paint.NET, Aseprite, Blender and more.
+For better or worse, base set currently uses fractional (0.1, 0.2, ...) versioning and NewGRFs use integer (1, 2, ...) versioning.