Document procedures for switches and random switches

[andythenorth]

Procedures were added in https://github.com/OpenTTD/nml/pull/66

NML docs need updated to cover procedures.

Maybe directly in these pages? https://newgrf-specs.tt-wiki.net/wiki/NML:Switch https://newgrf-specs.tt-wiki.net/wiki/NML:Random_switch

[andythenorth]

Procedures Procedures are a technique for using a switch chain where normally a variable would be used. The switch chain is called like a variable, runs whatever logic is required, and returns a result to the calling switch. The calling switch can also pass parameters to the procedure.

Benefits of procedures

1. Remove duplicate code. For example a vehicle grf might use complex rules for choosing the sprites for a vehicle. There might be 20 vehicles with similar switches in the graphics chains. These can't all share the same switch because they need to return the correct unique sprites. Using procedures, each vehicle can use a single switch, which calls a procedure containing the complex rules. This returns a result to the vehicle, which switches to the appropriate sprites. Removing the duplicate code:

• makes it easier for the author to write and maintain the nml code, because reusable code is written once instead of many times
• usually will compile faster
• reduces filesize (not a big deal, but still useful)

2. Simplify complex expressions in switches. It's possible to write very complex expressions for the switch variable, for example stacking up ternary operations. These don't format well in nml and are hard to read and make sense of. By moving the logic to a chain of switches, it can be easier to read and understand the code.

3. Creating fake custom variables. IS IT REALLY WISE TO EXPLAIN THIS?

To use: switch_name() or switch_name(parameter_1, parameter_2, ... parameter_n)

Explain the declaration of parameters in the procedure (callee).

[glx22]

Looks like a good start :)

[andythenorth]

Tyler has some real-world examples which are much better than any of mine.

https://github.com/2TallTyler/improved_town_layouts/blob/master/src/functions.nml

[glx22]

Don't forget to put a note about the 15bit return value :)

[andythenorth]

Oof adventures in 15 bit values yes.

[andythenorth]

Did we ever discuss var 1C?

From the nfo docs: Because callback results are limited to 15 bits, to access the full 32 bit result you can read variable 1C instead (e.g. by and-ing the 7E result with 0 and then adding var. 1C).

[glx22]

Var 1C is last_computed_result in NML.