Minimap Component

From Multiverse

User Interface Development

Overview  •  Managing Widgets  •  Event Handling  •  Using Widget Templates  •  Customizing Key Bindings  •  Localizing UI Text  •  Character Creation Framework  •  Minimap Component  •  Scripting Avatar Appearance

Reference

Widgets  •  Property Elements  •  Imageset Files

Tutorials

Hello World  •  Creating a Button  •  Creating a Menu  •  Creating a Help Dialog  •  Using Radio Buttons

Contents 1 Procedure 2 Creating a minimap image 2.1 Capturing the map image 2.2 Tools 3 Importing Minimap asset files 3.1 User interface files 3.2 Imageset files 3.3 Image files 4 Modifying minimap asset files for your world 4.1 User interface files 4.2 Imageset files 5 Customizing the minimap 5.1 Map decorations 5.2 Other customization 5.3 Notes

Procedure

To create a minimap using the Multiverse minimap component:

1. Create the minimap image for your world.
2. Import the Sampleworld minimap asset files to your asset repository.
3. Modify the files as appropriate for your world and minimap image.
4. Customize the minimap further as desired (optional).

Creating a minimap image

To create the map image for your world:

1. Start World Editor and open your world file.
2. Determine the two boundary points (upper left and lower right) that will define your map area, the area of your world represented in the minimap. This can be the entire world area or a subset. World Editor, displays the x,y, and z coordinates of the terrain point that the mouse pointer is over (at lower left in the bottom bar).
3. Record the x and z coordinates of the boundary points. The accuracy of the minimap is directly related to the accuracy of the values you use.
4. Turn off display of fog: Choose View | Display Fog Effects and uncheck the option.
5. Zoom the world view way out, in other words, move the viewpoint very high up. Use the Page Up key to move the viewpoint up quickly. How high depends on the size of the area you want your map to cover; at some point you will start to see the edges of the world.
6. Orient the world view so that north is up (and west left). To determine which direction is north, set the Skybox object to Direction Skybox, orient the view up, and look for NORTH.
7. Create a map image screenshot of your world extending from the upper left point to the lower right point. See the next section for details.
8. Add a one-pixel black border around the minimap image. When the player moves near the map edge, the minimap will display the same color pixel as the last image pixel. Thus, the color of the edge pixels will be displayed when there is no longer a map area to display. Therefore, you must convert the edge pixels of the map image to black. That is, the final image should have a one-pixel wide black border: this will make the image appear to be displayed over a black background. You can use another color to display that as the "background" color.

Capturing the map image

Take a screenshot from a distance that allows you to see both the boundary points. You may want to use large landmarks, or create two temporary markers visible from a distance to ensure that the image covers the appropriate area. Don't forget to orient the minimap image so that north is up.

Use a screen capture utility to create a a Targa (.tga), JPEG (.jpg), or DDS (.dds) file. A DDS file is most efficient and is preferable for production games, but Targa and JPEG will work for development and testing. You may need to crop the image so that its edges exactly align with the two boundary points.

NOTE: Each dimension of the map image must be a power of two; for example 256 px x 512 px.

Tools

In addition to World Editor, you will need some image capture and manipulation tools. See Third-Party Tools for more information.

NVIDIA provides a set of tools for viewing and working with DDS files: See NVIDIA Texture Tools. The DirectX Texture Editor is available in the DirectX SDK. NVIDIA also makes a DDS plugin for Adobe Photoshop. Recent releases of Photoshop support DDS without the plugin, but the plugin provides more functionality. One of the more useful features of the plugin is the ability to set a 1 texel border on your image. This lets you have a border that is one color. Without this feature, since the map image is scaled, the mipmapped versions (which are based on samples of surrounding pixels) would not have a uniform border.

Importing Minimap asset files

To use the minimap component, add the files from the Sampleworld asset repository listed below to your asset repository. Then modify them as described in the next section.

User interface files

Copy the following files from the Sampleworld Interface/FrameXML directory to the corresponding directory in your asset repository:

• MvMinimap.py script file.
• MvMinimap.xml FrameXML file.

Imageset files

Copy the following files from the Sampleworld Interface/Imagesets directory to the corresponding directory in your asset repository:

• MvMinimap.xml: references MvMinimap.tga containing the map decoration images.
• MvMapImage.xml: references the minimap image (MvSampleMap.dds in Sampleworld).

Image files

Copy the following files from the Sampleworld Imagefiles directory to the corresponding directory in your asset repository:

• MvMinimap.tga contains the images for the minmap decorations.
• MvSampleMap.dds: Replace this file with your minimap image file. You may want to use a different name: if your image is not called MvSampleMap.dds, edit MvMapImage.xml to reference your file name.

Modifying minimap asset files for your world

User interface files

First edit your theme (.toc) file and add MvMinimap.xml. For example, Sampleworld uses mars.toc; you may be using a different theme file.

Edit MvMinimap.py script file and enter the size of the minimap image in pixels in the XImageSize and YImageSize variables, for example:

 XImageSize = 1024
 YImageSize =  512

Then enter the x and z coordinates of the two boundary corners of the map area, upper left (ULx and ULz) and lower right (LRx and LRz), for example:

 ULx = -674785.7
 ULz = -511844.4
 
 LRx =  238214.3
 LRz =   94686.2

Note that LRx is greater than ULx and LRz is greater than ULz. This is because x increases to the East, and z increases to the South.

NOTE: If you know the GIS standard values FalseEasting, FalseNorthing, Xmpp and Ympp for your image map then comment out the formulas and replace them with your corresponding values.

Imageset files

Edit MvMapImage.xml, and set the following:

• Name of your minimap image file. Change the Imagefile attribute of the Images tag to reference your image
• Width and height in pixels of your minimap image. In the Imageset tag, change NativeHorzRes and NativeVertRes attributes to the width and height of your image in pixels. In the Image tag, change the Width and Height attributes to the width and height of your image in pixels.

So, change:

<Imageset Name="MvMapImage" 
          Imagefile="MvSampleMap.dds" 
          NativeHorzRes="1024" NativeVertRes="512" 
          AutoScaled="false">
  <Image Name="MinimapMapTexture" 
         XPos="0" YPos="0" 
         Width="1024" Height="512" />
</Imageset>

To:

<Imageset Name="MvMapImage" 
          Imagefile="yourMinimapImage" 
          NativeHorzRes="widthInPixels" NativeVertRes="heightInPixels" 
          AutoScaled="false">
  <Image Name="MinimapMapTexture" 
         XPos="0" YPos="0" 
         Width="widthInPixels" Height="heightInPixels" />
</Imageset>

Where:

• yourMinimapImage the filename of your minimap image.
• heightInPixels and widthInPixels are the height and width of your minimap image. NOTE: Both of these values must be powers of two (512, 1024, and so on).

Customizing the minimap

This section describes how to further customize the minimap component.

Map decorations

The image assets for map decorations are in Interface/Imagesets/MvMinimap.xml.

• map_edge defines the edge and corner images for the minimap frame.
• up_arrow, down_arrow, left_arrow and right_arrow define the compass decorations for the minimap frame.
• plus and minus define the images for the zoom in and zoom out buttons.
• avatar defines the image used to represent the character on the minimap.

The other image assets are currently unused but are reserved for other items of interest that could appear on a minimap.

To create alternate decorations:

• Create a new version of Imagefiles/MvMinimap.tga
• Update Interface/Imagesets/MvMinimap.xml with the new file name and layout information
• Update Interface/FrameXML/MvMinimap.xml with any layout name changes.

Other customization

To customize other aspects of the minimap component, edit Interface/FrameXML/MvMinimap.py and change settings described in the following table.

To change...	Set the values of...	Description
Size of the minimap display	XMinimapSize YMinimapSize	Minimap horizontal size (pixels) Minimap vertical size (pixels)
Base color of avatar icon	RAvatar, GAvatar, and BAvatar	Red, green, and blue color values, respectively. Must be between 0.0 and 1.0.
Zoom effects	MinZoom, ZoomInc and ZoomLevels	Minimum zoom value, zoom increment, and number of zoom levels, respectively. Zoom value of 1.0 means each pixel of the minimap image file is displayed at x1 scale.
Initial zoom	MinimapScale	The forumla for MinimapScale places the initial zoom factor in the middle of the zoom range. To use a different initial zoom factor, replace the formula with your desired value.
Size of the border in pixels	FrameEdgeBuffer	Defines a buffer around the minimap widget where the map image is not displayed. This allows you to have a minimap frame with fancy alpha at the edges.

Notes

The MvStatus.py script was modified for sampleworld to move the status window below the minimap. You may need to make a similar change for your world.