MiniMap - HUD Element 0.7.1b addon - Elder Scrolls IV: Oblivion

===================
MiniMap by Kyoma
Version 0.7.1b
Bethsoft.com
===================

1. Description
2. Installing and Requirements
3. Version History
4. Known Issues
5. Trouble Shooting
6. Contact and Feedback
7. Credits

==============
1. Description
==============

Tired of having to open up the local map each time you want to know where you are in a cave? Well, not any more for this mod gives you a MiniMap, like in Morrowind. The layout is fully configurable to suite your taste. Do you want it in the upper right corner? No problem. Do you want it to be as big as half the screen? Once again, no problem. See the MiniMap.ini for more details and settings on the layout of the MiniMap.

The MiniMap now has two different modes: Local and World. They speak for themselves I think but I'll give a short explaination anyway. You'll be able to toggle between them manually or choose to do it automatically on an interior/exterior transition. Zooming is ofcourse possible and there are seperate values used for the two different modes, both values lie between 50% and 200%. Default keys to zoom in and out are the Numpad+ and Numpad- respectively.

The Local mode is basically a copy of your local map. It works by generating textures on-the-fly for the cells around the player and then using those textures to build a complete image of everything within two cells (or just the whole cell when you're inside). There is the option to display door icons, either limited to known or used doors or simply all doors. The appearance of the Local mode texture is determined by your Oblivion ini setting "blocalMapshader". It controls if you have the detailed colored local map or the more vague paper local map. Obviously the latter is less detailed but it also means less (possible) issues (see Known Issues).

The World mode is like your world map, one big texture (the same one that is used by your World Map). It will work for (almost) any worldspace with a unique worldmap. If you are in a world that does not have its own map then the last known world and position is used instead, this is similar to how the World Map works in those cases.

Both modes will have an arrow that rotates according to the direction you are facing. Or if you like something less intrusive you can have a red dot instead of an arrow.

Here's a full list of features for the two modes.
* Local Mode
- Accurate display of surroundings, including all mod added areas.
- Choose between color or paper style, depends on your Oblivion ini "blocalMapshader"
- Display door icons, can be limited to known or found doors only.
- Zoom in and out between 50% and 200%.
* World Mode
- Uses the same map texture as your real World Map.
- Works with all vanilla worlds and mod added worlds with a unique map (the ones I know of).
- Zoom in and out between 50% and 200%.
* Things not (yet) possible
- Quest markers, either in Local or World mode.
- Map markers in World mode.
- Names of the doors next to the door icon, it may be possible for the majority of the doors but available room is still an issue.
- Fog-of-War (the black unexplored areas) in Local mode, I have no way to detect or create such areas on the MiniMap.

==============================
2. Installing and Requirements
==============================

---OMOD---
----------
* Create an OMOD from the archive and activate it. This mod requires:
- OBSE v0018 beta4 or higher. You can find the latest version at Obse.silverlock.org.
- Oblivion v1.2.0.416.
- If you are updating from below v0.6.2 you MUST make a clean save before using this mod.

* When activated follow the instructions on which UI mod you are using.
- Vanilla
- BTmod
- DarNifiedUI
- DarkUI'd DarN
- OblivionXP, Vanilla
- OblivionXP, DarNifiedUI
- OblivionXP, DarkUI'd DarN
- If you have a different UI mod installed you will need to open your "MenusMainhud_main_menu.xml" file and add the following line: . I've uploaded a picture at TESNexus which shows at what line it should be added, If you do not have a "MenusMainhud_main_menu.xml" you should use the Vanilla file as stated above.

* Open and inspect the MiniMap.ini file, some settings WILL need to be changed or verified.
- The "Critical Settings" section MUST be inspected as it contains settings that will be different for each user.
- The rest of the ini file contains details on each setting, probably more than you'll find in this readme.

---Manual---
------------
* Copy the esp, ini file, BSA file and menus folder to your data folder. This mod requires:
- OBSE v0018 beta4 or higher. You can find the latest version at Obse.silverlock.org.
- Oblivion v1.2.0.416.
- If you are updating from below v0.6.2 you MUST make a clean save before using this mod.

* Select the "01 XYZ" folders that corrosponds with the UI mod you are using and copy its content to your data folder. UIs supported:
- Vanilla
- BTmod
- DarNifiedUI
- DarkUI'd DarN
- OblivionXP, Vanilla
- OblivionXP, DarNifiedUI
- OblivionXP, DarkUI'd DarN
- If you have a different UI mod installed you will need to open your "MenusMainhud_main_menu.xml" file and add the following line: . I've uploaded a picture at TESNexus which shows at what line it should be added, If you do not have a "MenusMainhud_main_menu.xml" you should use the Vanilla file as stated above.

* Open and inspect the MiniMap.ini file, some settings WILL need to be changed or verified.
- The "Critical Settings" section MUST be inspected as it contains settings that will be different for each user.
- The rest of the ini file contains details on each setting, probably more than you'll find in this readme.

==================
3. Version History
==================

* 0.7.1b
- Fixed bug with the "iWorldWidth" and "iWorldHeight" settings not being applies.
- Fixed potential bug with the player arrow not being centered in the Local mode.
* 0.7.1
- Fixed problem with the MiniMap being hidden when first installing the mod. Also fixed a few other problems with initializing.
- Fixed problem with empty space appearing on the World MiniMap if you are near the edge of the worldmap, now it will move the arrow away from the center in order to display your correct position without any empty space appearing.
- Fixed bug that could happen when you travel from Cyrodiil to a Shivering Isles interior (e.g. using a teleport spell), where the World MiniMap would display the wrong position.
- Fixed bug with the transparency setting not working completely.
- Added seperate width and height settings for the Local and World mode.
- Expanded the "iAutoMode" setting to now also having a mode where the MiniMap is not re-displayed after each reload. Default behaviour is still that.
* 0.7.0
- Added a world mode that can be used apart from the local mode on the MiniMap.
- New option to automatically switch between local and world mode on transition between interior and exterior.
- Made the zoom in and zoom out steps configurable.
- Added an option to show a red dot instead of an arrow on the MiniMap.
- Reworked the frame a bit and added an optional thicker frame.
- Increased the amount of grids displayed from 9 to 25 (configurable) for when you are playing with either a large MiniMap or zoomed out alot. Grids are only used when their texture already exists.
- The 'Toggle-Key' now toggles between the local mode and the world mode, hold it down for approx. 2 seconds to hide the MiniMap. Press it again to show it, doesn't have to be 2 seconds.
- Corrected a slight positioning error with the local MiniMap, barely noticable unless zoomed in but still worth fixing I guess. :P
- Half a dozen other changes which I forgot to track, mostly tweaks and small bugfixes.
* 0.6.3
- The MiniMap is now hidden when you're viewing your inventory (and stats, skills, factions, etc).
- Removed a leftover debug line
* 0.6.2
- Rewrote everything using the power of OBSE v18. Although no major additions the internal works of the mod have been greatly optimized.
- Changed the way the iWaterHack setting works, the previous implementation was horribly broken. This time I've done extensive testing to ensure it works correctly.
- Reduced the number of files generated in a single sweep from 25 to 9. This results in far less object/tree cutoff aswell as reducing the possible fps hit when textures are being generated.
- Added rudimentory debugging, not really spectacular but better than nothing.
- Fixed a few bugs with the water detection for exterior cells. The amount of false-positives should be reduced to zero.
- Fixed a few (but serious) bugs with the door icon system.
* 0.6.1
- Re-added the precise positioning values from v0.5.3 for users that still experience stretching issues.
* 0.6.0
- Finally a proper fix for people with a widescreen resolution or otherwise problematic. See the ini for a setting (iScreenWidth) that needs to be adjusted according to your resolution.
- Fixed a specific crash when entering the IC Market District, other crashes might have had the same cause so they might be fixed aswell.
- Fixed door icons not appearing when entering a new cell for which the textures needed to be generated.
- Added option to turn off the zoom info displayed on the MiniMap.
- Fixed door icons appearing above the player marker instead of below it. They now also appear beneath the MiniMap frame at the edge.
- Fixed sometimes getting weird blotches on the MiniMap due to the distantLOD being off.
* 0.5.3
- Made the precise positioning values of the MiniMap configurable. Should be used to find the correct values for when you experience stretching on the MiniMap.
* 0.5.2
- Added debug setting to halt all MiniMap script processing. To be used to determine cause of CTD for some.
- Made zoom in/out and toggle keys configurable.
* 0.5.1
- Forgot to pack the textures needed for the MiniMap. Player arrow should now work.
- Last minute change resulted in strange layers appearing over the MiniMap.
* 0.5
- Beta release

===============
4. Known Issues
===============

* This mod uses a command called "OutputLocalMapPictures" (OLMP) which generates textures to the harddrive of the current cells around the player. They will only be generated once per cell (grid) after you visit it. The texture files are located in "TexturesMaps.." and are each 256Kb. A quick overview: A quick runthrough from one side of the Shivering Isles to the other results in a total size of just over 42Mb. A larger overview: I explored all outdoor areas on the Shivering Isles and the total size was around 240Mb, and that's a large area! It is safe to delete these files when they become too large - they will be generated again should it be nessecary.

* There is no Fog-of-War (the black/hidden areas on the Local Map for places you haven't been to yet) on the MiniMap and there's nothing I can do about it. Either accept it or don't use this mod.

* When in or around cities, you may notice black areas or strange gaps on the other side of the city walls. This is, unfortunately, beyond my control as well. It happens because there simply isn't any land at those black areas. Under normal circumstances you never reach those areas and because of the Fog-of-War on the local map you never see it either.

* The appearence of the water on the MiniMap can look a bit odd. This is because the sunglare, fog and the time-of-day affect how the water looks like on the textures from the above. Because the files are only generated once per cell it can result in strange transitions of the water color. Two settings control this to some extend:

- In the ini there is a setting called "iWaterHack". Setting it to 1 will remove the water reflection and sunglare for one frame just before textures are generated. The result is a smooth water color and the only downside is that the water . Setting it to 2 will also force the gamehour to a user-specified value for one frame. This way, the water will always look the same when it comes to how dark or light the color is. Ofcourse this has a visual drawback when textures are generated so you'll have to decide if it's worth it or not.

- In the ini there are two settings called "fFogNear" and "fFogFar". Fog has big influence on the water color, when present, the water will mimic the color of the fog. Very often this results in unnatural looking water. I recommend values of 0 and 250000 respectively, to temporarily move any fog far far away. Set both to 0 to disable changing the fog in any way.

- There is only one thing left I haven't been able to fix and that is being underwater. When you are swimming and the camera is underwater you will get a different color than when the camera is above the water. Maybe in the future I'll be able to fix this last remaining obstacle

* Sometimes the trees can appear to be cut off around the border of a cell grid. I already use code to minimize this as much as possible but if it happens alot or really annoys you, you can set bToggleTrees to 1 in the MiniMap ini. Since version 0.6.2 the tree cutoff has greatly reduced.

* Sometimes you'll see dark objects (most often rocks) on the MiniMap, these are objects which were fading in or out at the time the texture was generated. I can increase this distance to force all objects to be displayed but objects that are already fading won't be updated until you look in the direction they can be found.

* Sometimes when you enter a new exterior cell and the MiniMap needs to generate textures the DistantLOD land stays hidden but the trees and objects are visible as normal. This should go away as soon as you move or look around a little bit. The worse that can happen is that it takes a few seconds to restore the DistantLOD. But most of the time you won't notice the effect.

===================
5. Trouble Shooting
===================

Problem #1: I keep getting an error message saying the XML components couldn't be found but I installed everything correctly.
* Solution 1: First to make absolutely sure the XML components are indeed installed open up your "menushud_main_menu.xml" and look for a line with "". If that line is somehow missing you'll need to add it, instructions can be found at the top and a picture is on the TESNexus page to illustrate it. If the file already has that line please go to Solution #2.
* Solution 2: For some reason the game does not load the XML components even though the XML contains the required line. I've had one report where a user who played Oblivion on a resolution of 1440x900 experienced such a problem, as soon as he changed it to 1280x800 the MiniMap appeared and everything worked fine. I am still not sure how or why but if you play Oblivion with an 'odd' resolution (something other than 640x..., 800x..., 1024x..., 1280x... or 1680x...) I suggest you try changing your resolution and check if the problem persists or not. If it does please go to Solution #3.
* Solution 3: This step is the last thing you can try, go to the forum thread (link is at the top of the readme) and post the content of your "menushud_main_menu.xml", your "MiniMap.ini" and the resolution you are playing at. Maybe there is some hint on the source of the problem I can find in a closer inspection.

Problem #2: The position of the Local MiniMap is off by a (relative) small amount.
* Solution: Let me start by saying you shouldn't compare your position precisely with the real local map, there the player arrow doesn't turn around its center. Still it can be off a bit depending on your configuration and resolution. I tried my best to make it as accurate as possible and it required alot of tweaking. These things are accessable to players in the " Advanced Settings" section. Try adjusting the "iLocalOffsetX" and "iLocalOffsetY" values, best in steps of 5 to 10

Problem #3: The World MiniMap is in a completely wrong place! -OR- I'm using Mod ABC which adds a new world and the MiniMap does not work there!
* Solution: First make sure you are using the correct "iTamrielMap" setting in the MiniMap.ini. For the second part I'll probably need to release a small update. If you come across a mod with a seperate worldmap that is not supported please go do the forum thread (link is at the top of the readme) and post the mod's name. In the future I hope to be able to detect any worldmap by script but for now I need to code each mod in by hand. It's not hard but I just need to know about a mod in order to add it.

Problem #4: I'm seeing black areas with white borders, what's the deal with that!?!
* Solution: This isn't really a problem that can be fixed and it should not happen unless you either have a large MiniMap or are zoomed out alot. It happens when a texture for that grid could not be found and you are moving in that direction but aren't close enough yet for the texture to be generated. As soon as you get closer it should appear. In case you are wondering why they have white borders, well I did that so they are easily distinguished from completely black areas (see problem #5).

Problem #5: I'm seeing completely black areas and those with white borders!
* Solution: If you are inside a city then you'll likely come across those when you venture near the walls. There are black areas simply because there is no normal land over there, only DistantLOD land which is disabled when the textures are generated. I have a plan for the future that will make the MiniMap use textures from Tamriel (or whatever worldspace lies around the city) for those black areas but due to time constraints it was cut from the current version.

Problem #Unknown: I'm having a problem with the MiniMap that is not described by any of the above.
* Solution: Obviously no solution specifically but there is something you can do. Post about it in the forum thread, preferrably with a screenshot depicting the problem. Always helps to have some visual help when giving a bug report.

=======================
6. Contact and Feedback
=======================

Should you have any questions or comments, you can PM me (kyoma) at the Elder Scrolls Forum or post in the forum thread (see top of readme). Alternatively you can email me at daaf(dot)paradox(at)gmail.com

==========
7. Credits
==========

* The OBSE team, for the many many new functions they provided.
* DarN, with help trying to figure out alot of XML problems.
* shadeMe, for support, harassment and suggestions. And ofcourse bumping the mod..... :P
* DragoonWraith, for the mega-help with a translating coordinates system!
* Scanti, for explaining how the ModWaterShader command works.
* wrinklyninja, for help and advice on how the weather and fog works in Oblivion.
* NdranC on TESNexus, his feedback on a beta-beta version led me to great improvements and optimizations!
* All the other people whose name I forgot.