From 66a6ef252772203b8aa17882f4b6670b7b2168e7 Mon Sep 17 00:00:00 2001
From: Andy <andy@teamrubber.com>
Date: Sat, 21 Sep 2024 14:47:07 +0100
Subject: [PATCH] Codechange: comments

---
 src/roster.py                                            | 7 +++++++
 src/templates/procedures_wagon_recolour_strategies.pynml | 5 ++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/roster.py b/src/roster.py
index e80cc5656..02769ee29 100755
--- a/src/roster.py
+++ b/src/roster.py
@@ -381,6 +381,13 @@ def init_wagon_modules(self):
                     raise
 
     def init_wagon_recolour_colour_sets(self):
+        # wagon recolour liveries can be randomised across multiple colour sets
+        # this is a run-time randomisation, relying on a procedure that takes parameters for the candidate livery numbers
+        # however there are 10 parameters, and calls to the procedure are needed thousands of times per grf,
+        # testing proved that generating thousands of procedure calls with 10 params directly in the nml was expensive in file size, both nml and grf
+        # there are however a finite number of combinations that are actually needed (only 125 as of Sept 2024)
+        # therefore we can provide a compile-time lookup table, and index into it using a procedure call with a single parameter
+        # this does not have the same cost in nml or grf filesize
         seen_params = []
         for wagon_consist in self.wagon_consists:
             for unit in wagon_consist.unique_units:
diff --git a/src/templates/procedures_wagon_recolour_strategies.pynml b/src/templates/procedures_wagon_recolour_strategies.pynml
index 6bc421d26..d8ba0338a 100644
--- a/src/templates/procedures_wagon_recolour_strategies.pynml
+++ b/src/templates/procedures_wagon_recolour_strategies.pynml
@@ -85,7 +85,10 @@ switch (FEAT_TRAINS, SELF, switch_colour_mapping,
     switch_colour_set_use_weathering_1cc_to_1cc;
 }
 
-<!--! switch as lookup table to avoid defining parameterised procedure calls 8300 times for Horse random liveries, as this appears to bloat the grf from 43 MB to 89 MB -->
+<!--! switch as lookup table for combinations of colour set params
+      this is to avoid defining parameterised procedure calls 8300 times for Horse random liveries, as this appears to bloat the grf from 43 MB to 89 MB
+      see roster.wagon_recolour_colour_sets for more info
+      -->
 switch(FEAT_TRAINS, SELF, switch_CABBAGE_WAGON_RECOLOUR_SETS, wagon_recolour_colour_set_CABBAGE_NUM, wagon_recolour_colour_set_CABBAGE_NUM) {
     <tal:CABBAGE_WAGON_RECOLOUR_SET repeat="CABBAGE_WAGON_RECOLOUR_SET roster.wagon_recolour_colour_sets">
         ${repeat.CABBAGE_WAGON_RECOLOUR_SET.index}: return switch_colour_mapping(${CABBAGE_WAGON_RECOLOUR_SET});