diff --git a/bin/buildfx.sh b/bin/buildfx.sh
index d08678fb1..73f29c4cf 100755
--- a/bin/buildfx.sh
+++ b/bin/buildfx.sh
@@ -1,18 +1,28 @@
 #!/bin/bash
 
+# create or truncate merged-effects file
 :>| "$3"
+
+# make temp file with list of effect names
 records=$(mktemp)
 grep -v "^$" < "$1" | grep -v "^#" | grep -v "^\[" > "$records"
+
+# make temp assembly source file that represents the binary OKVS data structure
 source=$(mktemp)
-(echo "*=0"
- echo "!le16 $(wc -l <"$records"), 0"
+(echo "*=0"                            # dummy program counter for assembler
+ echo "!le16 $(wc -l <"$records"), 0"  # OKVS header
  while read -r key; do
-     echo "!byte ${#key}+5"
-     echo "!byte ${#key}"
-     echo "!text \"$key\""
-     echo "!be24 $(wc -c <"$3")"
-     cat "build/FX/$key" >> "$3"
+     echo "!byte ${#key}+5"            # OKVS record length
+     echo "!byte ${#key}"              # OKVS key length
+     echo "!text \"$key\""             # OKVS key (effect name)
+     echo "!be24 $(wc -c <"$3")"       # offset into merged-effects file
+     cat "build/FX/$key" >> "$3"       # add effect code into merged-effects file
+                                       # (all effects were previously assembled)
  done < "$records") > "$source"
+
+# assemble temp source file to create binary OKVS data structure
 acme -o "$2" "$source"
+
+# clean up
 rm "$source"
 rm "$records"
diff --git a/bin/buildhelp.sh b/bin/buildhelp.sh
index 89dd0e0df..3645e4887 100755
--- a/bin/buildhelp.sh
+++ b/bin/buildhelp.sh
@@ -2,19 +2,21 @@
 
 # run from project root directory
 
-:>| "$1"
+# make in-memory array of game filenames
 games=$(grep "," res/GAMES.CONF | grep -v "^#" | cut -d"," -f2 | cut -d"=" -f1 | sort)
+
+# first help text is the 'TODO' placeholder screen
 cp res/GAMEHELP/STANDARD "$1"
 for c in {A..Z}; do
-    echo "group$c"
+    echo "group$c"                                  # group games by first letter
     for game in $(echo "$games" | grep "^$c"); do
-        echo "!byte ${#game}"
-        echo "!text \"$game\""
+        echo "!byte ${#game}"                       # key length
+        echo "!text \"$game\""                      # key (game filename)
         if [ -f "res/GAMEHELP/$game" ]; then
-            echo "!be24 $(wc -c <"$1")"
+            echo "!be24 $(wc -c <"$1")"             # value (3-byte big-endian offset into merged help file)
             cat res/GAMEHELP/"$game" >> "$1"
         else
-            echo "!be24 0"
+            echo "!be24 0"                          # if game has no help, reuse placeholder at offset 0
         fi
     done
 done > "$2"
diff --git a/bin/buildokvs.sh b/bin/buildokvs.sh
index 09a7a201a..6d78145f6 100755
--- a/bin/buildokvs.sh
+++ b/bin/buildokvs.sh
@@ -2,18 +2,25 @@
 
 # run from project root directory
 
+# make temp file with just the key/value pairs (strip blank lines, comments, eof marker)
 records=$(mktemp)
 grep -v "^$" < "$1" | grep -v "^#" | grep -v "^\[" > "$records"
+
+# make temp assembly source file that represents the binary OKVS data structure
 source=$(mktemp)
-(echo "*=0"
- echo "!le16 $(wc -l <"$records"), 0"
+(echo "*=0"                            # dummy program counter for assembler
+ echo "!le16 $(wc -l <"$records"), 0"  # OKVS header
  while IFS="=" read -r key value; do
-     echo "!byte ${#key}+${#value}+3"
-     echo "!byte ${#key}"
-     echo "!text \"$key\""
-     echo "!byte ${#value}"
-     echo "!text \"$value\""
+     echo "!byte ${#key}+${#value}+3"  # OKVS record length
+     echo "!byte ${#key}"              # OKVS key length
+     echo "!text \"$key\""             # OKVS key
+     echo "!byte ${#value}"            # OKVS value length
+     echo "!text \"$value\""           # OKVS value
  done < "$records") > "$source"
+
+# assemble temp source file to create binary OKVS data structure
 acme -o "$2" "$source"
+
+# clean up
 rm "$source"
 rm "$records"