Utils - Modular MiniMap Overlays

[whoward69]

Modularised version of the MiniMap Panel that permits new entries to be added to the Overlays drop-down.

New entries can be inserted into the list or appended to it or replace existing (standard) entries.

Uses the techniques found in Utils - Modular DiploCorner, so an understanding of how that works is an advantage to using the components in this mod.


The following LuaEvents are supported
* LuaEvents.MiniMapOverlayAddin.Add(function OnMiniMapOverlayAddin(tab) ... end)
adds a new tab (or replaces a standard one) in the Overlay drop-down
tab is an associative array with the following entries

• text - the string (or TXT_KEY_) to display in the overlay drop-down
• group - the name of the group to place the entry in (see g_OverlayIndexes below for valid group names)
• call - the method to call when the entry is selected/deselected (receives a single bShow parameter)
• nav - the method to call when the next/previous legend buttons are pressed (omit or set to nil to disable the buttons)
• next_tt - the tooltip string (or TXT_KEY_) for the next button
• prev_tt - the tooltip string (or TXT_KEY_) for the previous button

* LuaEvents.MiniMapOverlayLegend.Add(function PopulateLegend(title, info) ... end)
sets the legend panel title and defines the boxes to draw in the legend key

• title - the string (or TXT_KEY_) to display at the top of the legend panel
• info - a list of Name and Color entries to populate the legend key with

* LuaEvents.MiniMapOverlayHideLegendNav.Add(function OnHideLegendNav(bHide) ... end)
hides/shows the legend next/previous buttons

* LuaEvents.MiniMapOverlayResizeLegendOptions.Add(function OnResizeLegendOptions(sizeX, sizeY, offsetCallback) ... end)
resizes the options "space" in the Legend side panel

• sizeX/sizeY - the dimensions of the space to allocate
• offsetCallback - the method to call to receive the offsetX/offsetY location of the "hole"

The following mods use the components of this mod

• UI - Continents - basic example of an overlay with and without a legend key
• UI - City Limits - basic example with a legend key
• UI - Barbarians - intermediate example with a legend key and next/previous buttons
• UI - Resources - complex example replacing a standard overlay and adding additional controls to the legend panel

 

[whoward69]

Example of how to use the components of this mod in your own mod ...

Create a new project
Assuming this will be a self-contained, standalone mod, uncheck the "Affects Saved Games" option

NOTE: All occurances of {ModName} or {MODNAME} MUST be replaced with the name of your mod EXCLUDING SPACES AND PUNCUTATION, eg, for a mod called "UI - Continents" use "UIContinents"

Add an XML folder
Add the MiniMapPanel.xml file to this folder
Add an "OnModActivated->UpdateDatabase" action for this file

Under the XML folder create a new XML item called "{ModName}Text.xml" (where "{ModName}" is the name of your mod!)
Add an "OnModActivated->UpdateDatabase" action for this file
The contents of this file is just

  <?xml version="1.0" encoding="utf-8"?>
  <GameData>
    <Language_en_US>
      <Row Tag="TXT_KEY_OVERLAY_{MODNAME}">
        <Text>My Overlay</Text>
      </Row>
    </Language_en_US>
  </GameData>

(where "{ModName}" is the name of your mod and "My Overlay" is relevant to your mod!)

Add a UI/InGame/WorldView folder
Add the MiniMapPanel lua and xml files to this folder
Set "Import into VFS" to true for both these files

Under the UI folder create a new LUA item called "{ModName}_MiniMapOverlayHook.lua" (where "{ModName}" is the name of your mod!)
Set "Import into VFS" to true for this file
From the "Content" tab, add a "MiniMapOverlayAddin" entry for this file
The contents of this file is just

  function OnMiniMapOverlayHook(bShow)
    LuaEvents.{ModName}Display(bShow) 
  end

  LuaEvents.MiniMapOverlayAddin({text="TXT_KEY_OVERLAY_{MODNAME}", call=OnMiniMapOverlayHook})

Under the UI folder create a new XML item called "{ModName}.xml" (where "{ModName}" is the name of your mod!)
Set "Import into VFS" to true for this file
From the "Content" tab, add an "InGameUIAddin" entry for this file
The contents of this file is just

  <?xml version="1.0" encoding="utf-8" ?>
  <Context Name="{ModName}" Hidden="1" />

Under the UI folder create a new LUA item called "{ModName}.lua" (where "{ModName}" is the name of your mod!)
Set "Import into VFS" to true for this file
The (basic) contents of this file is just

  function On{ModName}Display(bShow)
    if (bShow) then
      print("Show my overlay")
    else
      print("Hide my overlay")
    end

  end
  LuaEvents.{ModName}Display.Add(On{ModName}Display)

To display the legend key, add code at the start of the "{ModName}.lua" file similiar to the following (taken from "UI - Continents")

  include("FLuaVector")

  local highlights = { Green   = Vector4(0.0, 1.0, 0.0, 1.0), 
                       Yellow  = Vector4(1.0, 1.0, 0.0, 1.0)}             

  local colourAmerica = highlights["Green"]
  local colourAsia    = highlights["Yellow"]

  local myInfo = {
      {Name="TXT_KEY_CONTINENT_AMERICA", Color={R=colourAmerica.x, G=colourAmerica.y, B=colourAmerica.z}},
      {Name="TXT_KEY_CONTINENT_ASIA",    Color={R=colourAsia.x,    G=colourAsia.y,    B=colourAsia.z}}
  }

and then in the "On{ModName}Display(bShow)" function, add

    ...
    if (bShow) then
      LuaEvents.MiniMapOverlayLegend("TXT_KEY_OVERLAY_{MODNAME}", myInfo)
      print("Show my overlay")
    else
    ...

The main ModBuddy screen will look similiar to


The Actions tab will look similiar to


The Content tab will look similiar to


Save and build your mod

The .modinfo file will be similiar to

<?xml version="1.0" encoding="utf-8"?>
<Mod id="5b3ac2ad-73e4-42da-af9e-5bd8febff3cd" version="1">
  <Properties>
    <Name>UI - Continents</Name>
    <Teaser>Highlights landmasses belonging to the same continent</Teaser>
    <Description>Highlights landmasses belonging to the same continent.

An example of how to use the Modular MiniMap Overlay</Description>
    <Authors>William Howard</Authors>
    <HideSetupGame>0</HideSetupGame>
    <AffectsSavedGames>0</AffectsSavedGames>
    <SupportsSinglePlayer>1</SupportsSinglePlayer>
    <SupportsMultiplayer>1</SupportsMultiplayer>
    <SupportsHotSeat>0</SupportsHotSeat>
    <SupportsMac>1</SupportsMac>
    <ReloadLandmarkSystem>0</ReloadLandmarkSystem>
    <ReloadStrategicViewSystem>0</ReloadStrategicViewSystem>
    <ReloadUnitSystem>0</ReloadUnitSystem>
  </Properties>
  <Dependencies />
  <References />
  <Blocks />
  <Files>
    <File md5="8EEDCCABF4020C9CF8EE12460A2AED34" import="1">UI/Continents_MiniMapOverlayHook.lua</File>
    <File md5="B1C61C3BF7890125A76CEE668977B948" import="1">UI/InGame/WorldView/MiniMapPanel.lua</File>
    <File md5="85F70B15813E745128BF8CB78E3FAF0E" import="1">UI/InGame/WorldView/MiniMapPanel.xml</File>
    <File md5="8DC95B6D22B6603CB9E23E1856C6D36D" import="1">UI/Continents.lua</File>
    <File md5="CE351008A15913E60C7CFAF94C027293" import="1">UI/Continents.xml</File>
    <File md5="26B4CA382FB46E2F40C92A570E66A47E" import="0">XML/MiniMapPanel.xml</File>
    <File md5="A408291545AF2EC9D7060C233DFE4EFD" import="0">XML/UIContinents.xml</File>
  </Files>
  <Actions>
    <OnModActivated>
      <UpdateDatabase>XML/MiniMapPanel.xml</UpdateDatabase>
      <UpdateDatabase>XML/UIContinents.xml</UpdateDatabase>
    </OnModActivated>
  </Actions>
  <EntryPoints>
    <EntryPoint type="InGameUIAddin" file="UI/Continents.xml">
      <Name>Continents</Name>
      <Description>
      </Description>
    </EntryPoint>
    <EntryPoint type="MiniMapOverlayAddin" file="UI/Continents_MiniMapOverlayHook.lua">
      <Name>Continents MiniMap Overlay Hook</Name>
      <Description>
      </Description>
    </EntryPoint>
  </EntryPoints>
</Mod>

The mod "UI - Continents" can be downloaded as a working example

Basic overlay


Overlay with legend key