Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document procedures for switches and random switches #105

Open
andythenorth opened this issue Apr 26, 2020 · 7 comments
Open

Document procedures for switches and random switches #105

andythenorth opened this issue Apr 26, 2020 · 7 comments

Comments

@andythenorth
Copy link
Contributor

Procedures were added in #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
Copy link
Contributor Author

andythenorth commented Jul 1, 2021

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)
  1. 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.

  2. 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
Copy link
Contributor

glx22 commented Jul 6, 2021

Looks like a good start :)

@andythenorth
Copy link
Contributor Author

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
Copy link
Contributor

glx22 commented Aug 15, 2021

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

@andythenorth
Copy link
Contributor Author

Oof adventures in 15 bit values yes.

@andythenorth
Copy link
Contributor Author

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
Copy link
Contributor

glx22 commented May 9, 2022

Var 1C is last_computed_result in NML.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants