GRFv9 - Revision history

Jgr: Spelling/grammar

2025-06-27T19:30:03Z

Spelling/grammar

← Older revision		Revision as of 19:30, 27 June 2025
Line 18:		Line 18:
	The current GRF specification has several areas which are not ideal and could be improved in a subsequent specification version.		The current GRF specification has several areas which are not ideal and could be improved in a subsequent specification version.

	This section should list current pain points and non-~~idea specification~~ aspects, and where possible suggest improvements or general design principles for future additions.		This section should list current pain points and non-ideal aspects of the specification, and where possible suggest improvements or general design principles for future additions.
	This section is non-exhaustive.		This section is non-exhaustive.

Jgr at 22:07, 4 June 2025

2025-06-04T22:07:09Z

← Older revision		Revision as of 22:07, 4 June 2025
Line 24:		Line 24:

	GRFs are currently limited to 256 simultaneous action2 IDs. This is a common pain point for NewGRF authors. NewGRF authors are encouraged to needlessly duplicate action2s (e.g. by use of templating mechanisms) to mitigate this, this results in larger GRF files which has a negative impact on content distribution and run-time performance.		GRFs are currently limited to 256 simultaneous action2 IDs. This is a common pain point for NewGRF authors. NewGRF authors are encouraged to needlessly duplicate action2s (e.g. by use of templating mechanisms) to mitigate this, this results in larger GRF files which has a negative impact on content distribution and run-time performance.
	Moving to 16 bit Action2 IDs would remove this problem without imposing significant technical ~~difficult~~.		Moving to 16 bit Action2 IDs would remove this problem without imposing significant technical difficulty.

	=== General Design Comments on VariationalAction2 ===		=== General Design Comments on VariationalAction2 ===

Jgr: /* Existing Work */

2025-06-04T22:06:39Z

Existing Work

← Older revision		Revision as of 22:06, 4 June 2025
Line 10:		Line 10:
	GRFv9 PRs (closed)		GRFv9 PRs (closed)
	https://github.com/OpenTTD/OpenTTD/pull/13309 (NML: https://github.com/OpenTTD/nml/pull/357)		https://github.com/OpenTTD/OpenTTD/pull/13309 (NML: https://github.com/OpenTTD/nml/pull/357)

			For 15.0:
			Add explicit (Var)Action2 results for "callback failed" and "calculated result". https://github.com/OpenTTD/OpenTTD/pull/14149

	== Design Considerations ==		== Design Considerations ==

Jgr: /* General Design Comments on VariationalAction2 */

2025-06-04T21:45:44Z

General Design Comments on VariationalAction2

← Older revision		Revision as of 21:45, 4 June 2025
Line 31:		Line 31:
	* Some 60x variables are needlessly expensive at run-time because expensive sub-parts are calculated even when the GRF only needed another part of the variable (e.g. industry variable 67/68) (this can be reasonably mitigated without a spec change).		* Some 60x variables are needlessly expensive at run-time because expensive sub-parts are calculated even when the GRF only needed another part of the variable (e.g. industry variable 67/68) (this can be reasonably mitigated without a spec change).

	The current "error group" behaviour for unavailable variables is ~~extremely~~ unintuitive, especially when working from a higher abstraction layer such as NML. This also interacts unfavourably with the suggested callback topology where unhandled callbacks are routed onto the graphics chain.		The current "error group" behaviour for unavailable variables is unintuitive, especially when working from a higher abstraction layer such as NML. This also interacts unfavourably with the suggested callback topology where unhandled callbacks are routed onto the graphics chain.

	Returning a "failed" result currently requires returning a different value depending on the current value of variable 0C and the feature type (see CB_FAILED in NML), a VariationalAction2 type (or other equivalent mechanism) which results in an unambiguous callback failure in all contexts may be useful.

	Code patterns very commonly used by NewGRF authors such as <code>flag ? a : b</code> in NML read and immediately throw away the value of <code>a</code> when <code>flag</code> is false. The generated VarationalAction2 sequence for this is also overly verbose. It may be useful to consider adding operators or other mechanisms to enable these types of patterns to be expressed more efficiently.		Code patterns very commonly used by NewGRF authors such as <code>flag ? a : b</code> in NML read and immediately throw away the value of <code>a</code> when <code>flag</code> is false. The generated VarationalAction2 sequence for this is also overly verbose. It may be useful to consider adding operators or other mechanisms to enable these types of patterns to be expressed more efficiently.

	Likewise, adding simple relational operators (as opposed to the current cmp/ucmp) could reduce the need for verbose sequences to do comparisons.		Likewise, adding simple relational operators (as opposed to the current cmp/ucmp) could reduce the need for verbose sequences to do comparisons.

			Procedure calls (variable 7E) truncate the result value to 15 bits, this is a source of surprising behaviour for NewGRF authors. Avoiding this requires using variable 1C. It may be useful to remove the need for this truncation.

Jgr: Initial comments on VariationalAction2

2025-06-04T21:28:06Z

Initial comments on VariationalAction2

@@ Line 17: / Line 17: @@
 This section should list current pain points and non-idea specification aspects, and where possible suggest improvements or general design principles for future additions.
 This section is non-exhaustive.
 === Concurrent Action2 ID Limit ===
@@ Line 24: / Line 22: @@
 GRFs are currently limited to 256 simultaneous action2 IDs. This is a common pain point for NewGRF authors. NewGRF authors are encouraged to needlessly duplicate action2s (e.g. by use of templating mechanisms) to mitigate this, this results in larger GRF files which has a negative impact on content distribution and run-time performance.
 Moving to 16 bit Action2 IDs would remove this problem without imposing significant technical difficult.

Jgr at 20:42, 4 June 2025

2025-06-04T20:42:23Z

@@ Line 2: / Line 2: @@
 == Introduction ==
-This page describes work so far, design considerations and other items of interest for a potential version 9 of the GRF specification (GRFv9), or equivalent evolution of GRF the specification.
+This page describes work so far, design considerations and other items of interest for a potential version 9 of the GRF specification (GRFv9), or equivalent specification evolution.
 This page is a not a guarantee that any such changes will be occur in future, or that any such future work will closely match that described here.
@@ Line 10: / Line 10: @@
 GRFv9 PRs (closed)
 https://github.com/OpenTTD/OpenTTD/pull/13309 (NML: https://github.com/OpenTTD/nml/pull/357)

Jgr: Initial page

2025-06-04T20:27:09Z

Initial page

New page

== Introduction ==

This page describes work so far, design considerations and other items of interest for a potential version 9 of the GRF specification (GRFv9), or equivalent evolution of GRF the specification.

This page is a not a guarantee that any such changes will be occur in future, or that any such future work will closely match that described here.

== Existing Work ==

GRFv9 PRs (closed)
https://github.com/OpenTTD/OpenTTD/pull/13309 (NML: https://github.com/OpenTTD/nml/pull/357)