Map Shading toolbar entries are placed into wrong toolbar
I have experienced that in already two modules. One of them just a synthetic module for testing.

Quite easy to replicate.

* Add a Map Shading with Button Text defined.
* You will have a new entry in the toolbar
* Create a Toolbar Menu and add an entry with the same text as the Map Shading Button Text property

The expected result is that the menu option to toggle the Map Shading appears in the Toolbar Menu, but is continues to appear in the toolbar straight.

It can be very annoying if you have multiple Map Shadings
diff --git a/vassal-app/src/main/java/VASSAL/build/module/map/MapShader.java b/vassal-app/src/main/java/VASSAL/build/module/map/MapShader.java
index 7620b4a25..ceb8e8521 100644
--- a/vassal-app/src/main/java/VASSAL/build/module/map/MapShader.java
+++ b/vassal-app/src/main/java/VASSAL/build/module/map/MapShader.java
@@ -20,32 +20,6 @@ package VASSAL.build.module.map;
 
 import VASSAL.build.AbstractFolder;
 import VASSAL.build.AbstractToolbarItem;
-import VASSAL.configure.TranslatableStringEnum;
-import VASSAL.tools.LaunchButton;
-import java.awt.AlphaComposite;
-import java.awt.BasicStroke;
-import java.awt.Color;
-import java.awt.Composite;
-import java.awt.Dimension;
-import java.awt.Graphics;
-import java.awt.Graphics2D;
-import java.awt.Image;
-import java.awt.Paint;
-import java.awt.Rectangle;
-import java.awt.Stroke;
-import java.awt.TexturePaint;
-import java.awt.geom.AffineTransform;
-import java.awt.geom.Area;
-import java.awt.image.BufferedImage;
-import java.io.File;
-import java.util.Arrays;
-import java.util.Collection;
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.List;
-
-import org.apache.commons.lang3.builder.HashCodeBuilder;
-
 import VASSAL.build.AutoConfigurable;
 import VASSAL.build.Buildable;
 import VASSAL.build.GameModule;
@@ -59,11 +33,13 @@ import VASSAL.configure.Configurer;
 import VASSAL.configure.ConfigurerFactory;
 import VASSAL.configure.IconConfigurer;
 import VASSAL.configure.StringArrayConfigurer;
+import VASSAL.configure.TranslatableStringEnum;
 import VASSAL.configure.VisibilityCondition;
 import VASSAL.counters.Decorator;
 import VASSAL.counters.GamePiece;
 import VASSAL.counters.Stack;
 import VASSAL.i18n.Resources;
+import VASSAL.tools.LaunchButton;
 import VASSAL.tools.NamedKeyStroke;
 import VASSAL.tools.UniqueIdManager;
 import VASSAL.tools.image.ImageUtils;
@@ -71,6 +47,30 @@ import VASSAL.tools.imageop.AbstractTileOpImpl;
 import VASSAL.tools.imageop.ImageOp;
 import VASSAL.tools.imageop.Op;
 
+import org.apache.commons.lang3.builder.HashCodeBuilder;
+
+import java.awt.AlphaComposite;
+import java.awt.BasicStroke;
+import java.awt.Color;
+import java.awt.Composite;
+import java.awt.Dimension;
+import java.awt.Graphics;
+import java.awt.Graphics2D;
+import java.awt.Image;
+import java.awt.Paint;
+import java.awt.Rectangle;
+import java.awt.Stroke;
+import java.awt.TexturePaint;
+import java.awt.geom.AffineTransform;
+import java.awt.geom.Area;
+import java.awt.image.BufferedImage;
+import java.io.File;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+
 /**
  * Draw shaded regions on a map.
  *
@@ -93,6 +93,8 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
   public static final String EXC_BOARDS = "No, exclude Boards in list"; //NON-NLS (really)
   public static final String INC_BOARDS = "No, only shade Boards in List"; //NON-NLS (really)
 
+  public static final String ADD_TO_MAP_TOOLBAR = "addToMapToolbar";
+
   protected static final UniqueIdManager idMgr = new UniqueIdManager("MapShader"); //NON-NLS
 
   /** @deprecated use launch from the superclass */
@@ -153,6 +155,18 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
   protected AlphaComposite borderComposite = null;
   protected BasicStroke stroke = null;
 
+  protected String version = ""; //NON-NLS
+
+  /**
+   * Should the toolbar button for this shader be added to the Map toolbar instead of the Global toolbar?
+   * Map Shader buttons SHOULD be added to the Map Toolbar, but have mistakenly been added to the GLobal
+   * Toolbar since before the dawn of time. Changing this will break existing module that have already
+   * added Shader buttons to global toolbar menus.
+   * Existing Map Shaders will have addToMapToolbar default to false to maintain compatibility
+   * New Map Shaders will have addToMapToolbar set to True
+   */
+  protected boolean addToMapToolbar = false;
+
   public MapShader() {
     setButtonTextKey(BUTTON_TEXT);
 
@@ -438,6 +452,7 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
       BUTTON_TEXT,
       TOOLTIP,
       ICON,
+      ADD_TO_MAP_TOOLBAR,
       HOT_KEY,
       BOARDS,
       BOARD_LIST,
@@ -464,6 +479,7 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
       String.class,
       String.class,
       IconConfig.class,
+      Boolean.class,
       NamedKeyStroke.class,
       BoardPrompt.class,
       String[].class,
@@ -490,6 +506,7 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
       Resources.getString(Resources.BUTTON_TEXT),
       Resources.getString(Resources.TOOLTIP_TEXT),
       Resources.getString(Resources.BUTTON_ICON),
+      Resources.getString("Editor.MapShader.addToMapToolbar"),
       Resources.getString(Resources.HOTKEY_LABEL),
       Resources.getString("Editor.MapShader.shade_boards"), //$NON-NLS-1$
       Resources.getString("Editor.MapShader.board_list"), //$NON-NLS-1$
@@ -776,6 +793,12 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
       }
       buildBorderComposite();
     }
+    else if (ADD_TO_MAP_TOOLBAR.equals(key)) {
+      if (value instanceof String) {
+        value = Boolean.valueOf((String)value);
+      }
+      addToMapToolbar = (Boolean) value;
+    }
     else {
       super.setAttribute(key, value);
     }
@@ -831,6 +854,9 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
     else if (BORDER_OPACITY.equals(key)) {
       return Integer.toString(borderOpacity);
     }
+    else if (ADD_TO_MAP_TOOLBAR.equals(key)) {
+      return String.valueOf(addToMapToolbar);
+    }
     else {
       return super.getAttributeValueString(key);
     }
@@ -889,14 +915,24 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
       parent = ((AbstractFolder)parent).getNonFolderAncestor();
     }
 
+    map = (Map) parent;
+
+    // Create a launch button and add to correct toolbar.
     final LaunchButton lb = getLaunchButton();
-    GameModule.getGameModule().getToolBar().add(lb);
     lb.setAlignmentY(0.0F);
+    if (addToMapToolbar) {
+      map.getToolBar().add(lb);
+    }
+    else {
+      GameModule.getGameModule().getToolBar().add(lb);
+    }
+
     GameModule.getGameModule().getGameState().addGameComponent(this);
-    map = (Map) parent;
     map.addDrawComponent(this);
+
     idMgr.add(this);
     validator = idMgr;
+
     setAttributeTranslatable(NAME, false);
   }
 
@@ -932,4 +968,13 @@ public class MapShader extends AbstractToolbarItem implements GameComponent, Dra
   public List<String> getPropertyList() {
     return Arrays.asList(boardList);
   }
+
+  @Override
+  public Configurer getConfigurer() {
+    if (map == null) {
+      // New shader being created, change default for add to Map Toolbar to True.
+      addToMapToolbar = true;
+    }
+    return super.getConfigurer();
+  }
 }
diff --git a/vassal-app/src/main/resources/VASSAL/i18n/Editor.properties b/vassal-app/src/main/resources/VASSAL/i18n/Editor.properties
index ebda5acb4..c3280bf9b 100644
--- a/vassal-app/src/main/resources/VASSAL/i18n/Editor.properties
+++ b/vassal-app/src/main/resources/VASSAL/i18n/Editor.properties
@@ -1411,6 +1411,7 @@ Editor.MapShader.image=Custom image
 Editor.MapShader.all_boards=Yes
 Editor.MapShader.exc_boards=No, exclude boards in list
 Editor.MapShader.inc_boards=No, only shade boards in list
+Editor.MapShader.addToMapToolbar=Add to map-level Toolbar
 
 # MapWidget
 Editor.MapWidget.component_type=Map
diff --git a/vassal-doc/src/main/readme-referencemanual/ReferenceManual/Map.adoc b/vassal-doc/src/main/readme-referencemanual/ReferenceManual/Map.adoc
index 003e910a3..7a62d02b5 100644
--- a/vassal-doc/src/main/readme-referencemanual/ReferenceManual/Map.adoc
+++ b/vassal-doc/src/main/readme-referencemanual/ReferenceManual/Map.adoc
@@ -524,6 +524,11 @@ Otherwise, visibility is controlled by a button on the Toolbar.
 
 *Button icon:*::  Icon for the Toolbar button.
 
+*Add to map-level Toolbar:*:: Untick this box to add the button to the Module level Toolbar instead of the current Maps Toolbar. Affects which <<ToolbarMenu.adoc#top,Toolbar Menus>> the button can be added to.
+
+NOTE: Map-level components are normally added to the Toolbar on their own Map, but in older versions of Vassal (pre 3.7), Map Shader buttons where added to the Module Toolbar. This option is provide for backwards compatibility.
+
+
 *Hotkey:*:: <<NamedKeyCommand.adoc#top,Keystroke or Named Command>> for the Toolbar button.
 
 *All boards in map get Shaded:*::  Allows you to select which <<Board.adoc#top,Boards>> in the map to apply the shading to.
diff --git a/vassal-doc/src/main/readme-referencemanual/ReferenceManual/ToolbarMenu.adoc b/vassal-doc/src/main/readme-referencemanual/ReferenceManual/ToolbarMenu.adoc
index 3d981681b..ef6e92cdd 100644
--- a/vassal-doc/src/main/readme-referencemanual/ReferenceManual/ToolbarMenu.adoc
+++ b/vassal-doc/src/main/readme-referencemanual/ReferenceManual/ToolbarMenu.adoc
@@ -10,6 +10,9 @@
 The Toolbar Menu component lets you group buttons from the <<Toolbar.adoc#top,Toolbar>> of the main <<GameModule.adoc#top,Module>> window or a <<Map.adoc#top,Map>> window into a drop-down menu.
 Each button named in this component will be removed from the Toolbar and instead appear as a menu item in the drop-down menu.
 
+NOTE: Buttons defined in a Map or any subcomponents of a Map can only be added to a Toolbar Menu defined on that Map. +
+Buttons defined in any other Components can only be added to a Toolbar Menu defined at the Module level.
+
 [width="100%",cols="50%a,^50%a",]
 |===
 |
diff --git a/vassal-doc/src/main/readme-referencemanual/ReferenceManual/images/MapShading.png b/vassal-doc/src/main/readme-referencemanual/ReferenceManual/images/MapShading.png
index 97fd9c14d..b83b952da 100644
Binary files a/vassal-doc/src/main/readme-referencemanual/ReferenceManual/images/MapShading.png and b/vassal-doc/src/main/readme-referencemanual/ReferenceManual/images/MapShading.png differ
['vassal-doc/src/main/readme-referencemanual/ReferenceManual/Map.adoc', 'vassal-app/src/main/resources/VASSAL/i18n/Editor.properties', 'vassal-app/src/main/java/VASSAL/build/module/map/MapShader.java', 'vassal-doc/src/main/readme-referencemanual/ReferenceManual/ToolbarMenu.adoc']