BgMapper .162 (perpetual beta) for DOS - SNES Savestate viewer and mapper
Written in assembly by Peekin; compiled using Nasm and WDOSX.

--------------------------------------------
Minor, insignifigant changes to this version
--------------------------------------------
--===Ver 0.16x===---
- Nicer looking scene viewing keyhelp
- VRAM graphics exporting, all sprites and tilesets
  (by pressing 0 in graphics viewer or selecting from scene export menu)

-------------------
To be added soonest
-------------------
- 16x16 tiles such as those used in "Yoshi's Island" backgrounds
- Scene sides clipping

-------------------
1. What is this silly prog
2. Disclaimer
3. Thanks
4. Requirements
5. Features
6. Future plans
7. Things left out
8. History
9. Contact me
-------------------

-----------------------
What is this silly prog
-----------------------
 BgMapper is a simple program which can recreate the still scene from an
emulator's savestate, tell miscellaneous technical details about the
display, and show the hidden scene graphics used to build the scene.
Currently it is only a curiosity for those who might be interested in
seeing some of what programmers do so well to hide from you. Its eventual
intended purpose is to output tilemaps from the scene that can be pieced
together to make complete levels. This should lead to a new a new idea:
complete map collections of all those classic SNES games. My favorite video
game system is the Super Nintendo, so excuse me for my favortism to it, but
BgMapper might someday be rewritten to include other console classics (if
I'm ambitious enough to get familiar with how they all work). For now, it
supports the ZSNES emulator savestates.

 The basic idea of BgMapper is that all those levels you see while playing
a game have to be stored somewhere, and that if you could just find where,
you could get the complete maps. Unfortunately, it's difficult to find
where in the cartridge that games store their levels and exactly how (does
anybody out there know?). They are often compressed, with each game having
its own format and storing its levels wherever in the ROM it wants. While
the game is running though, everything is in an expanded state in either
memory (WRAM) for faster access or the scene itself (VRAM). So the best
alternative way to get at the map data is to grab it from an instant in
time that the game is running, like an emulation savestate (it would be a
little difficult to grab it from a real SNES!). Some games store the entire
current level in memory, like in Mario 2&3, Mario World, Yoshi's Island,
Zelda 3, and Metroid 3. They simply generate new parts of the scene based
on the level in memory when they need to (like when the scene is scrolled
or you enter a new area). Others insist on being a little more difficult to
map and must read directly from the ROM or something, so only the tiles
that you can visibly see are mappable. That means visiting every little
screen of a level and saving its state to map it all (just a bit tedious!).

----------
Disclaimer
----------
 This program is provided free, and no guarantees are given that it is
incapable of doing damage to your computer. I have made sure that it does
not have any known problems before releasing it; however that does not
except it from undiscovered errors, so you use it by your own choice.
Please tell me if you encounter a problem so I can fix it. After all, I
these on my own computer too!

 All mentioned games are property of their designers and copyrighted. This
program (or really, this author) was not intended to lessen the realism and
pure fun of them by revealing how they work or secrets that could be found
out, only to preserve their memory. Let the SNES not die yet :)

------
Thanks
------
- Yoshi for his informative docs that got me started.
- Vilewrath for writing the example SNES tile translating code in
   BASIC.
- ZsKnight for sending me the ZSNES savestate format
   and info on screen addition and subtraction!
- Qwertie for organizing his conversations with various emulator
   authors and writing his own very helpful doc.
- All the authors of emulators.
- All the places out there that keep info, like 'The Emulation
   Center', 'Zophar's Domain', 'Snes Programmer's Resource'...
- Michael Tippach for WdosX, a 32bit DOS extender.
- Authors of NASM for a great compiler.
- Gaz for his useful assembly library.

------------
Requirements
------------
 To completely recreate a scene, BgMapper needs to be completely able to
handle all video modes and most tilemap settings. So it is sort of like
just the graphics core of an emulator (not that the graphics code of any
emulator is a small part!). The high memory and speed requirements of an
emulator do not apply here, because the entire ROM does not need to be
loaded (just a much smaller savestate), and there is no CPU to emulate
(only a tile based graphics scene to build).

- IBM PC 25MHz+ You have that covered (unless you're a Mac user)
- 4Mb           It doesn't really even use one megabyte of that
- VGA           SVGA is not supported, just 320x200:256 (mode 13h)
- Keyboard      Always handy to have one of these things
- Mouse         Not really useful yet

 It has been tested out on my 25Mhz 386 and a 300Mhz Pentium. It works fine
on both and should work fine on anything in between. No problems have been
encountered under simple MS-DOS, Win 3.1, and Win 95. No guarantees for
anything else. Actually, no guarantees with even those!

--------
Features
--------
 Ok, here is why you bothered to download this program:

- Still Scene Viewing   (the coolest:)
- Graphics Viewing      (semi-cool, not really there yet)
- Graphics Exporting
- Technical Information (I'm sure nobody cares about this)
- Palette Info          (does not exist yet)

-=Still Scene Viewing=-
 The main part of the prog. The scene is the same one you would see on the
screen of your emulator when you saved the state, unless the game is using
any realtime effects that change the scene midframe (as most annoyingly
do). It currently supports:

    Bitplane video modes 0-6
    Mode 7 as flat scene
    8x8 tilesize (not 16x16 yet)
    32x32 32x64 64x32 64x64 tilemaps
    Tile flipping, paletting, and priority
    Subscreen/mainscreen layering
    Background color constant
    Separate color palettes per bg in mode 0

 It displays the extra wide screens of modes 5&6, but the tiles are the
wrong size (they should be genuine 16x8 tiles). Color addition/subtraction
is absent, and sprites are also missing.

 One important note on what you see in the scene: When you save it
determines what you get. Sadly (for our mapmaking purposes), the majority
of games use at least some type of HDMA effects. That means that in a split
screen mode like that of 'Secret Of Mana' in the beginning will show either
only the sky or only the ground depending on what scanline the state was
saved. Oddly ZSNES .400 saves on scanline 0 while ZSNES .815a saves on 223.
To save it at the scanline you want, you will have to use the debugger.
Just trace through it until the Y count goes a little beyond the vertical
line you where think the change is happening.

 You can pan around the scene and see the junk you weren't supposed to,
turn on/off bgs (even ones that are purposely disabled), and then export a
snapshot when you have the picture you want visible.

  Keys:
    Up Down Left Right   Scroll by a single tile (eight pixels)
    PgUp PgDn Home End   Scroll by half a page (128 pixels)
    * / + -              Fine adjustment (1 pixel)

    1-4          Toggle on/off mainscreens. You can even turn on bgs
                 that the game turned off, although you will likely
                 just see junk.
    Shift+(1-4)  Toggle on/off subscreens.
    6            Restore all bgs to as they were before you started
                 messing with them.
    7            Merge all screens into main layer. Can be very useful
                 for improving visibility in some scenes that use
                 transparency. Was mainly added for "Metroid 3". Too

          bad ZSNES did not have such a key.
    0            Bring up export menu to allow exporting image of scene,
                 game palette, or graphics.
    F1           Little reminder if you forget the keys

-=Graphics Viewing=-
 The graphics are sort of interesting to look at if you like to see what
building blocks make up the scene and how games pack their graphics. You
can also see the 256 color palette and select which palette group to view
the graphics in. It can only view 4 bitplane mode though. 

  Keys:
    Up Down      Scroll one row
    Left Right   Change palette
    0            Save graphics in current color palette 

-=Graphics exporting=-
 Have any of you ever wanted to build a game on an existing tile set,
rather than draw your own by hand. Maybe you have wanted to use familiar
characters in your little odyssey. You can export all of VRAM to a bitmap
(something I'm surprised emulators do not have an option for), to do
whatever you want with. Of course, you are (or at least should be) well
aware that they are copyrighted. Therefore, I do not consider myself
responsible for you getting yourself in trouble by ripping off some game
company's graphics and putting them in your own game ;)

-=Technical Information=-
 For now, this is really more of just a debugging screen for the scene than
a real info page. To display the information about a savestate without
starting up BgMapper, use the '-info' switch.

-=Palette Info=-
 Here you can see the 256 colors and background color constant, with each
color's RGB and hex values, or at least when I get it done.

------------
Future plans
------------
Things to be done that I'm probably too lazy to finish.

- Map exporting (sort of the purpose for making this prog)
- Sprites in Scene Viewing
- A few more details added to Scene Info
- Those 16x16 and rare 8x16 tiles
- Transparency (color addition and subtraction)

-=Map Exporting=-
 I'll come up with my own little format for map files, and eventually a
separate map editor. This simple program is supposed to only be for simply
getting the map out of the savestate, nothing more. The map files will have
to be able to hold multiple maps, tile sets, palettes, and have some sort
of compression method for keeping the filesize down. It will also need to
include multiple layering for those maps that use two overlayed planes such
as "Zelda", "Secret of Mana", "Mario RPG"... It could even have a way to
link separate maps together and mark special areas of the map with text
comments, but don't get your hopes up. Something like that that would not
come for quite a while, unless one of you out there wants to write it ;-)

-=Sprites=-
 It does not really need to show them, but why not?

-=More info=-
 Some more scene information like what the windows are set to, what DMA
channels are active, and the values in the mode 7 registers would be nice
to know (to me anyway, none of you likely care:).

-=16x16 tiles=-
 The uncommon 16x16 tiles need to be added, for the sake of "Yoshi's
Island: MW2" backgrounds. 16x8 tiles such as the ones in the main menu of
'SOM', although very rare, will be added. They are the double wide tiles
used the for the 512 column video modes.

-=Transparency=-
 It isn't necessary, but it makes thing look so much better. Then again, is
it really worth the coding?

 If I didn't mention something above, then I don't plan to add it (but I
guess if it is something good, you can ask anyway).

---------------
Things left out
---------------
 Certain things have been intentionally left out, since they are not
important in the purpose of mapmaking. They include mode 7 rotation and
scaling, windowing, pixelation (that scrambling, mosaic effect), and HDMA
effects. Windowing and HDMA effects could be added, but it would be
difficult since they are real-time effects that would require BgMapper to
be even more of an emulator and simulate a complete frame. The lack of HDMA
means that a lot of scenes will not appear exactly as they do in emulation,
(with no wavy effects, skewing, midframe palette changes, and such) but
will instead look flat and plain. Of course, that is exactly what we want!
Ironically what the emulation authors strive so hard to perfect is the very
thing that I've intentionally removed.

-------
History
-------
 This should contain nothing interesting for most of you, but for those
that can get anything out of it, here it is:

--Ver 0.0-- (Aug 5,1998)
- Start writing viewer in Qbasic. Figure out where certain registers
  of the SNES were stored in ZSNES savestates.
- Write code for simple GUI parts (menus and lists).
- Create main menu and file loading window.
- Add mouse support (it was a must).
- Able to load VRAM, OAM, and scroll registers but not able to
  display even a single tile yet.
- Get the scene info page right after some trial and error. Tells
  the tile size, map size, and scroll registers.
- Add palette viewing window.
- Map tiles are now flipped vertically and horizontally.
- Added mosaic, vertical scan line, and cycle count info. Verified
  that other games can be viewed with ZMapper in addition to Zelda.
- Added different colorbases for each plane while using mode 0.
- Start to add sprites (to the Sprites page at least, not the
  scene).
- Add checking that files to be loaded are indeed ZSNES savestates.
  That means it will not load a non-savestate file even if the name
  ends with the 'zst' extension.

--===Ver 0.01===--
- Write a tile translator (SNES tile => linear bitmap).
- Try to figure out how tilemaps are arranged with simple colored
  blocks. They are messed up! Instead of 64x64 tilemaps being normal,
  simple arrays they are four separate 32x32 tilemaps.
- Replace the blocks with real tiles (at least for non-mode 7 8x8
  tiles).
- Add palette colormapping.
- Replace the tilemap debugger with the real one to draw scene
  layers.
- Add sprites list with details (they might not be right though).
- Get the tilemaps to wrap correctly!
- Add View scene scroll with arrow keys.
- Beat Mario RPG and decide I want to make a map of it!

--===Ver 0.02===--
- Added background color, now the skies in 'Mario World' and
  'AllStars' look as they should!
- Metroid scenes now display correctly. I had the tilemap
  height/width bits reversed, so 32x32 and 64x64 tilemaps worked
  fine, but 32x64 and 64x32 were not wrapping right at the edges.
- Fixed bug where tilemaps that point to tiles past VRAM wrap
  around to the front (for 'Yoshi's Island').
- Found the first game yet to use 16x16 tiles (also Yoshi's Island)
- now I can finally test them out...ok, they work.
- Add background color to palette viewer.
- My compiler just told me that ZMapper's source code was too big,
  so I guess it is time to convert it to some other language.

--===Ver 0.10===--
- It now draws boxes (oh yeah) and has two types of neat fonts, but
  there isn't even a title page yet. How did ZsKnight do it all?
- Mouse and keyboard routines written.
- The menu now works (or at least it is drawn right and reacts to
  key input), and rather nicely too for being written in tedious
  assembly.
- Do some major revising of the readme, maybe because I'm so tired
  of coding.
- Get the mouse to work with the menus, both clicking on the
  choices and moving over it the them.
- Time tested several tile translators and think I've found the
  fastest one. It is not necessarily as fast as an emulator's tile
  translator(s) because it works for any bitplane mode (color depths
  1,2,3,4,& 8), rather than having individual ones for each different
  depth, but it isn't meant to beat emulators!
- Decide to change the name of this prog to BgMapper in case people
  get it confused with ZSNES and think it was written by the same
  people. It was named after Zelda, but this program applies to much
  more than just one game, so this name should be more fitting. A
  month has gone by and this is all I've done?

--===Ver 0.11===--
- Get the complete format for ZSNES savestates from ZsKnight
- Get info from ZsKnight on color addition/subtraction
- It finally loads ZSNES savestates! A cheap test blit some VRAM tiles
  onto the screen. Compared the tile blitting with Naga, and it's
  about twice as fast. That's good enough for me.
- Take a break and work on side project 'SpriteView'
  Actually Sv was spawned from a downsized BgMapper :)

--===Ver 0.12===-- (Nov 19)
- Add a simple palette window to VRAM viewer.
- Add -sd "status display" switch.
- Added dumb scene info output - not finished by any means.
- Add raw tilemap viewer page.
- Adapt tilemap viewer code to make simple multilayered scene
  viewer. It can accept 2,4,8bit modes.
- It finally renders the resemblance of a scene, but still need to
  add tile paletting, flipping, priority, and other tile sizes.
- Scene viewer can scroll bgs, supporting 32x32, 32x64, 64x32, and
  64x64 tilemaps sizes.
- Added mode flat mode 7 scene viewing.

--===Ver 0.13===-- (Feb 10)
- Tile priority,
- flipping, and
- paletting all work now

--===Ver 0.14===-- (April 8)
- Tile cache added to speed things up
- Starts out viewing scene rather than needing to select it from
  the menu
- Fixed background color constant addition. The skies look right
  now, although it seems that ZSNES might not always save the color
  constant in the savestate for some reason.
- Added scene export to a bitmap

--===Ver 0.15===---
- Subscreen/mainscreen layering fixed
- Allow mainscreens and subscreens to be toggled on/off
- Set key for merging screens of games that use transparency.
  Should greatly improve viewing in some cases (press '7')
- Add little messages to let you know what happens
- Palette exporting (also by pressing 0)
- Different color palettes for each bg in mode 0
- '-info' startup switch

--===Ver 0.16===---
see above...

----------
Contact me
----------
 If you do not like the prog, you did not have to download it. So please
refer such comments to nobody@nada.com, and go find something else that you
do like :) Friendly email otoh is loved.

    Email:    FDwR@hotmail.com (Dwayne Robinson)
    Homepage: http://members.tripod.com/FDwR/snes.htm
