Version numbers - Revision history

Michi cc: /* NFO version */ Fix NFO doc linkl.

2025-01-11T14:52:19Z

NFO version: Fix NFO doc linkl.

← Older revision		Revision as of 14:52, 11 January 2025
Line 88:		Line 88:
	There are no implications between GRF container version, GRF version and NFO version. Though of course some things may only be represented using newer NFO versions.		There are no implications between GRF container version, GRF version and NFO version. Though of course some things may only be represented using newer NFO versions.

	The differences between the formats are ''documented'' in the [~~http~~://~~dev~~.~~openttdcoop.org~~/~~projects~~/grfcodec/~~repository~~/~~entry~~/src/readinfo.cpp GRFCodec source code],		The differences between the formats are ''documented'' in the [https://github.com/OpenTTD/grfcodec/blob/master/src/readinfo.cpp GRFCodec source code],
	which can still read all formats (though not write).		which can still read all formats (though not write).

Michi cc: /* GRF container version */ Fix GRF container doc link.

2025-01-11T14:51:10Z

GRF container version: Fix GRF container doc link.

← Older revision		Revision as of 14:51, 11 January 2025
Line 64:		Line 64:
	OpenTTD and TTDPatch.		OpenTTD and TTDPatch.

	The GRF container format is specified in the [~~http~~://~~dev~~.~~openttdcoop~~.~~org~~/~~projects~~/grfcodec/~~repository~~/~~entry~~/docs/grf.txt grfcodec documentation].		The GRF container format is specified in the [https://raw.githubusercontent.com/OpenTTD/grfcodec/refs/heads/master/docs/grf.txt grfcodec documentation].

	=== GRF container version 1 ===		=== GRF container version 1 ===

Frosch: update for OpenTTD versioning schema since version 12

2023-06-27T19:55:24Z

update for OpenTTD versioning schema since version 12

← Older revision		Revision as of 19:55, 27 June 2023
Line 153:		Line 153:
	\| 1.1 \|\| 1.1 nightly rXXXX \|\| 1.1.0-beta X \|\| 1.1.0 \|\| 1.1.x		\| 1.1 \|\| 1.1 nightly rXXXX \|\| 1.1.0-beta X \|\| 1.1.0 \|\| 1.1.x
	\|-		\|-
	\| 1.2 \|\| 1.2 nightly ~~rXXXX~~ \|\| 1.2.0-beta X \|\| 1.2.0 \|\| 1.2.x		\| 1.9 \|\| 1.9 nightly YYYYMMDD <ref>Since 1.9 nightlies no longer use a revision number, but a date.</ref> \|\| 1.9.0-beta X \|\| 1.9.0 \|\| 1.9.x
	\|-		\|-
	\| 1.3 \|\| ~~1.3~~ nightly ~~rXXXX~~ \|\| \|\| \|\|		\| 12 <ref>Version 1.11 was followed by version 12.</ref> \|\| 12 nightly YYYYMMDD \|\| 12.0-beta X \|\| 12.0 \|\| 12.x
	\|}		\|}

Frosch: /* OpenTTD version */

2012-07-08T10:20:02Z

OpenTTD version

← Older revision		Revision as of 10:20, 8 July 2012
Line 153:		Line 153:
	\| 1.1 \|\| 1.1 nightly rXXXX \|\| 1.1.0-beta X \|\| 1.1.0 \|\| 1.1.x		\| 1.1 \|\| 1.1 nightly rXXXX \|\| 1.1.0-beta X \|\| 1.1.0 \|\| 1.1.x
	\|-		\|-
	\| 1.2 \|\| 1.2 nightly rXXXX \|\| 1.2.0-beta X \|\| 1.2.0~~<ref name="notyet">Not released yet.</ref>~~ \|\| 1.2.x~~<ref name="notyet"/>~~		\| 1.2 \|\| 1.2 nightly rXXXX \|\| 1.2.0-beta X \|\| 1.2.0 \|\| 1.2.x
	\|-		\|-
	\| 1.3 \|\| 1.3 nightly rXXXX \|\| \|\| \|\|		\| 1.3 \|\| 1.3 nightly rXXXX \|\| \|\| \|\|

Planetmaker: /* OpenTTD version */ Link directly to OpenTTD's newgrf version for var 21 / 1D

2012-04-10T07:28:36Z

OpenTTD version: Link directly to OpenTTD's newgrf version for var 21 / 1D

← Older revision		Revision as of 07:28, 10 April 2012
Line 137:		Line 137:

	Certain NewGRF features are only supported starting from certain OpenTTD versions on. These version requirements are mentioned throughout the specs using the {{ottd\|}} icon.		Certain NewGRF features are only supported starting from certain OpenTTD versions on. These version requirements are mentioned throughout the specs using the {{ottd\|}} icon.
	NewGRFs can check the OpenTTD version using [[Action9]] for variables [[GlobalVariables\|21 and 1D]] and disable themself using [[ActionB]].		NewGRFs can check the OpenTTD version using [[Action9]] for variables [[GlobalVariables#OpenTTD_Version_.2821_.2F_A1.29\|21 and 1D]] and disable themself using [[ActionB]].

	OpenTTD is versioned in alpha, beta and stable versions. The major and minor version number stays the same for alphas, betas and stables leading to each other,		OpenTTD is versioned in alpha, beta and stable versions. The major and minor version number stays the same for alphas, betas and stables leading to each other,

Frosch: /* GRF version 7 */

2012-04-01T19:19:39Z

GRF version 7

← Older revision		Revision as of 19:19, 1 April 2012
Line 43:		Line 43:
	Most notable changes are:		Most notable changes are:
	* Language codes in [[Action4]] were completely redesigned.		* Language codes in [[Action4]] were completely redesigned.
	* Various callbacks and variables ~~return~~ cargobits instead of cargoslots.		* Various callbacks, properties and variables use cargobits instead of cargoslots.
	The changes are described in detail on the pages for the features they affect.		The changes are described in detail on the pages for the features they affect.

Frosch: /* GRF version 7 */

2012-04-01T19:18:32Z

GRF version 7

← Older revision		Revision as of 19:18, 1 April 2012
Line 43:		Line 43:
	Most notable changes are:		Most notable changes are:
	* Language codes in [[Action4]] were completely redesigned.		* Language codes in [[Action4]] were completely redesigned.
	* Various callbacks return cargobits instead of cargoslots.		* Various callbacks and variables return cargobits instead of cargoslots.
	The changes are described in detail on the pages for the features they affect.		The changes are described in detail on the pages for the features they affect.

Frosch: moved VersionNumbers to Version numbers

2012-04-01T17:08:56Z

moved VersionNumbers to Version numbers

← Older revision	Revision as of 17:08, 1 April 2012
(No difference)

Frosch: page created

2012-04-01T16:14:38Z

page created

New page

There are various version numbers involved in these NewGRF specs. This page clarifies the terms for version numbers.

== Version of a specific NewGRF ==
{{ottdp|1.1|no}}

The version number of a specific NewGRF distinguishes releases of the same NewGRF and defines which release is "newer" or "older".
This has no effect on the NewGRF specs or general behaviour of the NewGRF.
A NewGRF defines its version using [[Action14#GRF_version_.28.22INFO.22_-.3E_.22VRSN.22.29|Action 14]],
it can also define a [[Action14#Minimal_compatible_GRF_version_.28.22INFO.22_-.3E_.22MINV.22.29|minimum version]] to which it is savegame compatible.

Before the introduction of Action14 - and version numbers in it - NewGRFs used to change the GRFID in case of savegame-incompatibility.
However, this was not done consistently by NewGRF authors, esp. since it caused problems in other places (e.g. NewGRFs testing for other NewGRFs).

== GRF version ==

The GRF version defines the version of the NewGRF specs to which a NewGRF adheres.
Changing the GRF version of a GRF is likely to affect the operativity of a NewGRF as it might change the behaviour of various NewGRF features.

Throughout the specs the dependencies and changes between GRF versions are indicated using the {{grf|}} icon.

A NewGRF defines the version of the specs it adheres to within its [[Action8]].

=== GRF version 0 and 1 ===
{{ottdp|no|no}}

These GRF versions are from the alpha and beta days of NewGRFs in general.
Especially version 1 introduced [[Action8]] which allows a NewGRF to specify the GRF version it adheres to.
GRF version 2 concurs with TTDPatch 2.0, the first stable version of TTDPatch supporting NewGRFs. It comes along with a hard compatibility cut in NewGRFs:
TTDPatch 2.0 is the first version to support GRF version 2, while it removes support for version 0 and 1 at the same time (which implies making Action 8 mandatory).

During the development of the GRF specs various features were designed, implemented and redesigned again. As such GRF version 2 is the first stable version of the specs.

=== GRF version 2 to 6 ===
{{ottdp|0.6|2.0}}

These GRF versions were introduced at somewhat arbitrary spots of TTDPatch development to allow NewGRFs to specify requirements for newer GRF features.
Later this approach of versioning the specs was dropped. Instead NewGRFs can now read and test the TTDPatch / OpenTTD version in [[Action9]] and disable themself using [[ActionB]] with an appropiate error message.

=== GRF version 7 ===
{{ottdp|0.6|2.5}}

GRF version 7 makes various semantic changes to various NewGRF features. The same code can be valid for both version 6 and 7, but will have a different meaning.
Most notable changes are:
* Language codes in [[Action4]] were completely redesigned.
* Various callbacks return cargobits instead of cargoslots.
The changes are described in detail on the pages for the features they affect.

=== GRF version 8 ===
{{ottdp|1.2|no}}

GRF version 8 again makes various semantic changes to various NewGRF features.
Most notable changes are:
* Various compatibility layers within the specs were removed to simplify writing NewGRFs resp. to remove arbitrary restrictions.
: E.g. the special meaning of 0xFF?? callback results was removed. Also all callbacks are 15bit callbacks now.
* All remnants of cargoslots were removed. (Except for the cargo definition itself of course.)
* Various parts of the specs were clarified, various callbacks which allowed various results with the same meaning before now only allow definite values for every possible result, while the other values stay reserved.
: E.g. callbacks results which were previously only tested for zero or non-zero must now return a specific value 0 or 1.
* All "height" variables were revised to better distinguish height in heightlevels or in pixels. This is a preparation for the introduction of more than 16 heightlevels.

== GRF container version ==

The GRF container format is the binary format of the GRF file. While the GRF version controls the meaning of the content of a NewGRF, the
GRF container version specifies the storage format for it. As such this version affects the software which reads/writes NewGRFs like grfcodec, nml, and of course also
OpenTTD and TTDPatch.

The GRF container format is specified in the [http://dev.openttdcoop.org/projects/grfcodec/repository/entry/docs/grf.txt grfcodec documentation].

=== GRF container version 1 ===
{{ottdp|0.6|2.0}}

This is the traditional file format from TTD.

=== GRF container version 2 ===
{{ottdp|1.2|no}}

This is a new file format introduced in GRFCodec 6.0. Implementations which only know GRF container version 1 will consider GRFs with this version empty / invalid.

New features in this version are:
* Pseudosprites (and binary include sprites) can be bigger than 64KB.
* Realsprites can be higher than 255 pixels.
* Realsprites can contain various versions of the same sprite in different zoom levels and colour depths (8bpp/32bpp).

There are no implications between GRF container version, GRF version and NFO version. Though of course some things are only possible with GRF container version 2.

== NFO version ==

This is the file format of NFO files, the input/output of GRFCodec and NFORenum.
There are no implications between GRF container version, GRF version and NFO version. Though of course some things may only be represented using newer NFO versions.

The differences between the formats are ''documented'' in the [http://dev.openttdcoop.org/projects/grfcodec/repository/entry/src/readinfo.cpp GRFCodec source code],
which can still read all formats (though not write).

=== NFO version 1 to 7 ===

Along these versions numerous advanced syntax forms were added to GRFCodec. However, every version can be converted into every other of these versions without losing
information when encoding/decoding NewGRFs (except source code comments, which are lost when encoding GRFs). Though older NFO versions might not be that comfortable
for representing certain GRF features (e.g. binary include sprites).

=== NFO versions 8 to 31 ===
Historically the numeric values of GRF versions and NFO versions were often the same (esp. for the long lasting versions 6 and 7), causing quite some confusion among NewGRF authors, which then used the version numbers
incorrectly. When GRF version 8 coincided again (time-wise) with the requirement for a new NFO version, it was decided to skip NFO versions 8 to 31 to make the numeric values
vastly different and thus making confusion less likely.

The value "32" for the new version was picked for unspecified reasons. Rumours say the value 32 stands for:
* Support for 32bpp graphics.
* Support for GRF container version 2.0. (Versions are usually encoded hexadecimal, and 20h = 32)

=== NFO version 32 ===

NFO version 32 adds support for GRF container version 2 specific features like 32bpp graphics or zoom-level specific graphics.
However, NFO version 32 and earlier versions can also be encoded into GRF container version 1 resp. 2.
Encoding into GRF container version 1 or decoding into NFO version < 32 might drop additional sprites though, which cannot be represented in those formats.

== TTDPatch version ==

Certain NewGRF features are only supported starting from certain TTDPatch versions on. These version requirements are mentioned throughout the specs using the {{ttdp|}} icon.
NewGRFs can check the TTDPatch version using [[Action9]] for variables [[GlobalVariables|0B and 1D]] and disable themself using [[ActionB]].

TTDPatch is versioned in alpha, beta and stable versions.
However, before 2.6 alphas the alpha versions were named with different version numbers than the beta/stable versions they would lead to; instead they used the previous stable version incremented by 0.0.1.

{| |-
! Series !! Alpha versions !! Beta versions !! Stable !! Maintenance releases of stables
|-
| 1.9 <ref>These versions had no NewGRF support at all and are only listed to explain the following lines.</ref> || 1.8.1 alpha XX || 1.9 beta X || 1.9 ||
|-
| 2.0 || 1.9.1 alpha XX || 2.0 beta X || 2.0 || 2.0r1
|-
| 2.5 || 2.0.1 alpha XX || 2.5 beta X || 2.5 <ref>Not released yet.</ref> ||
|-
| 2.6 || 2.6 nightly rXXXX || || ||
|}

<references/>

== OpenTTD version ==

Certain NewGRF features are only supported starting from certain OpenTTD versions on. These version requirements are mentioned throughout the specs using the {{ottd|}} icon.
NewGRFs can check the OpenTTD version using [[Action9]] for variables [[GlobalVariables|21 and 1D]] and disable themself using [[ActionB]].

OpenTTD is versioned in alpha, beta and stable versions. The major and minor version number stays the same for alphas, betas and stables leading to each other,
except when the major version number is increased.

{| |-
! Series !! Alpha versions !! Beta versions !! Stable !! Maintenance releases of stables
|-
| 0.6 || 0.6 nightly rXXXX || 0.6.0-beta X || 0.6.0 || 0.6.x
|-
| 0.7 || 0.7 nightly rXXXX || 0.7.0-beta X || 0.7.0 || 0.7.x
|-
| 1.0 || 0.8 nightly rXXXX, 1.0 nightly rXXXX <ref>The nightlies changed the version after the decision that 1.0 would follow 0.7 instead of 0.8.</ref> || 1.0.0-beta X || 1.0.0 || 1.0.x
|-
| 1.1 || 1.1 nightly rXXXX || 1.1.0-beta X || 1.1.0 || 1.1.x
|-
| 1.2 || 1.2 nightly rXXXX || 1.2.0-beta X || 1.2.0<ref name="notyet">Not released yet.</ref> || 1.2.x<ref name="notyet"/>
|-
| 1.3 || 1.3 nightly rXXXX || || ||
|}

<references/>