Utils - Modular MiniMap Overlays

Discussion in 'Civ5 - Mod Components' started by whoward69, Apr 9, 2012.

  1. whoward69

    whoward69 DLL Minion

    Joined:
    May 30, 2011
    Messages:
    8,581
    Location:
    Near Portsmouth, UK
    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
     
  2. whoward69

    whoward69 DLL Minion

    Joined:
    May 30, 2011
    Messages:
    8,581
    Location:
    Near Portsmouth, UK
    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
    Code:
      <?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
    Code:
      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
    Code:
      <?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
    Code:
      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")
    Code:
      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
    Code:
        ...
        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
    Code:
    <?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
     

Share This Page