The contents of this website are Copyright (c)2004 by Brian Manning <brian at antlinux dot com>. Please do not reuse any of the content on this website without permission from the author.

Other things on this page: Project Names :: TODOs/Program Ideas ::

Related pages: SVGmap :: EncounterMarkupLanguage :: MapMakingLinks :: QuickHook :: carto.net

Scope and Objectives:

• Why QuickMap?
• What will QuickMap do?
• How will QuickMap do it?
• How will you know QuickMap works? (Testing)
• What tools and resources will be used/needed?
• What will the user see when they run the program?
• What kinds of problems could be encountered?

More information about the user experience...

• splash screen
• tooltips
• Main User Interface
  • tools panel
  • layers panel
  • objects panel
  • drawing objects panel
  • colors panel
  • main drawing window
• Context (right click/control click) Menu
• Keybindings
• Misc actions

Project names:

• Encounter Tool
• Ed (Encounter daemon)
• Game Tool
• Encounter Construction Set
• Encounter Builder

Another name for QuickMap... Virtual Graph Paper?

TODOs/Program Ideas

Startup:

• do Operating System determination in the constructor for the quickmap program; build an OS object that contains information that other parts of the program may need
• build a program start object, which shows the user how far along the program is in it's initialization process
• Have QuickMap discard error messages that Java throws unless the user asks for them by passing in a -logfile command on the command line, and specifying a valid file/directory that can be written to
• Create an Init object on startup, which goes through and gets various pieces of information about the system, like platform, OS version, network address, SWT libs version, Java version. Have Init object dump state/settings if program is started up in Debug mode.
• Try to catch exceptions related to SWT libraries so that you can warn the user that something is wrong with the SWT libs install. Maybe see if there's a SWT.version attribute you can read prior to doing any heavy lifting (like creating a shell), and erroring out if something goes wrong. Put this in the init code, add the SWT version to the init object

User Experience:

• Switch between metric and standard measurement systems as requested by the user. Maybe change the scale of the maps to decimal-less units when changing measurement systems.
• Create a user's guide written in HTML as the specs for the project (RAD development???). Use the GIMP tools as the basis of the QuickMap toolset. The user's guide should show how to install QuickMap, as well as basic usage for all of the tools located in the toolbox. Layers should be discussed, as well as how to change properties of an object, and how to bind an object to an encounter.
• create (wizards/druids/familiars/daemons/helping hand, or "The Hand", as in, "Give yourself the hand!") to assist the user when the user is creating new complex objects.
  • when creating stairs for example, have the user select the material of the stairs (wood, stone, iron), whether the stairs are straight, circular, or irregular, meaning they follow the contours of the room
• add a printing pre-setup dialog, which will determine how the user wants the map to print (all the map on one sheet or use multiple sheets to print the maps to a certain scale, whether or not to print map re-assembly keys in the map margins or inside the maps)
• File -> New should give the user a choice between Map and Shape, and ???
• keep a transaction log of actions for undo/redo
  • for each object that's added to the main drawing panel, create an object tracking code, and then every time that object is touched, the transaction log has a record of that object's touching via the transaction code. This way, you could actually run undo on individual objects by replaying the object's transaction log, or undo programwide by replaying the program's transaction log
• as objects are added/moved/resized in the main drawing panel, use coarse graphics for the user interaction (for speed), then once the user has completed their interaction with the object (usually by releasing a mouse button), perform the fine graphics drawing on the object that was changed
  • create a list of things you can do to an object, so that objects know what they can do to/for themselves as well as possibly coming up with a binary transaction log format of some kind
    • create object
    • delete object
    • move object
    • change object attribute (attribute name=new value)

Debugging:

• write a profiler that wraps method calls to other objects, the profiler will keep track of elapsed time and maybe calls to other functions
• write JUnit? tests for all QuickMap objects

Internals:

• Use gcj to compile SWT2?.0, and use the holoman.org SWT 2.0 Java2D? interface to provide the 2d graphics. Maybe even try the 3.0 version of the Holoman toolset?.
• Maybe write a JNI binding between Java and librsvg?
• The Cairo SVG drawing libraries have Java bindings written for use with SWT. The project is called CairoJava
• use JAR files for storing QuickMap files that the user creates
  • use the file extension .qm for saved files
  • have an object reference format, which saves only references to shape objects and attributes of those objects. Since the objects don't get saved with this format, if the saved file gets put on a different computer that does not have those objects installed, the user will have to be notified
  • have an object inclusion format, which saves objects as well as attributes of those objects. This allows the saved files to be portable across different workstations
  • Also allow exporting in raw SVG format, but warn the user that all object information will be lost
• have object bindings in the program so that object A knows that it's related to object B and vice-versa. For example, a wall and a set of stairs know about each other, when the wall gets moved/reshaped, the stairs get told and update themselves as well.

QuickMap Scope and Objectives

Why QuickMap?Why not CC2? or Dundjinni or some other mapping program? (Identify current problems)

• The idea for QuickMap is to create maps quickly, not to create beautiful maps; beautiful maps are good, but take a while to make.
  • Quick maps can allow the game master to concentrate more on the game, and less on the tools used to create the game
  • QuickMap should allow someone who has never used the program before to generate a simple map in 10 to 15 minutes or less. Creating a map should be as simple as dragging a few shapes from a stencil bin to the drawing area. More complex manipulations should be easily possible as well.
• Existing mapping programs for RPG's (CC and Dunjinni) cost money, and are closed source. Not too much incentive there for people to get interested in taking ownership of the toolchain and making changes to it so it's more of what they need as a game master. For example, there's no toolchain dedicated to the Gamma World setting yet.
• Use vector graphics to draw objects instead of raster graphics (bitmaps). Raster based mappers are all over the place. Using vector grapics will help a lot with scaling and zooming, as well as storage and rendering of the maps themselves, as vector graphics are basically groups of numbers, manipulating them is a lot faster than flipping bits in a bitmapped image, and the file sizes involved for vector graphics are smaller as well.
• No mapping tool that allows you to use the tool in a game. For example, a 'fog of war' layer can be added so that game masters can reveal sections of the map as players encounter it, or spell radiuses can be added or put onto player maps to project the effects of a cast spell
• Not currently any end-to-end solutions for RPG generation; mapping, encounter and campaign generation, and adventure logging. Most of the effort has been concentrated on mapping, when it takes an encounter to drive what's on the map into becoming part of the campain.

What will QuickMap do? (Define criteria, goals and objectives)

• QuickMap will allow for quickly mapping indoors or outdoors encounters for Role Playing Games (RPGs?).
• QuickMap may also have hooks for "encounter areas", so that an encounter area can be saved with the map data, and an external program can be used to create the encounters that go with that map. This external program could also use the monsters listed in the SRD to help "flesh out" encounter areas. There's an RTF->XML SRD conversion tool located on the pcgen-xml group somewhere (Andaragor has created an XML D20 package).
• Using QuickMap to build a map of an encounter area should only take as much time as it takes for players to go get a soda or take a biobreak during a session. QuickMap would be ideal for use by players for mapping out an adventure.
• QuickMap should scale the maps so that maps can be printed out on one page, or parts of the map can be zoomed and printed large enough to be used with miniatures.
• QuickMap should be extensively documented so that people are motivated to hack on it; if people see how things work, they may come up with new ways of doing it, or new ideas that are related to the exisisting work
• An interactive tutorial should be part of the release; the tutorial can run in a window alongside the drawing area or stencil bin; as the user follows the directions in the tutorial window, they can advance the tutorial in steps as they feel ready. Tutorial would also allow the user to bookmark parts of the tutorial that look interesting to them, so the user can come back and view a tutorial item at a later date

How will QuickMap do it? (Plan of action)

Scalable Vector Graphics (SVG) will be used to draw shapes that will be used in mapping. SVG is good because it you can change sizes of your objects (as in zooming in and out on a map), and the SVG objects will scale accordingly. SVG also has a compressed file format called SVGZ, compressed data is good! As far as what programming language will be used to interact with users, looks like right now Java will be chosen, as there are SVG libraries and viewers already written in Java. Java runs on many platforms without too many issues, so porting across platforms should much easier. Speed gains could be realized if you use GCJ to make native copies of all the binaries.

• Build an SVG Shape editor (Using SWT) as the first program, then use QuickMap to place the shapes created with the editor. QuickMap should load itself as packages on top of a simple SVG editor, so that the editor can be used as a standalone application without having all of the extra RPG tools around to clutter up the user interface or loaded into memory.
• users can build their own shapesets by using SVG, and then loading the resulting SVG files into QuickMap
• use SVG/XML comments to hide the undo steps in the saved file. Or maybe there's some way that this could be done with the XML itself.
• use the XML spec that PCGen? is developing to describe encounter data for encounter areas. See EncounterMarkupLanguage page for more details and links.

How can QuickMap be tested to verify it does what it's supposed to do? (Plan of action/feasibility)

Existing SVG graphics can be used to test the functionality of QuickMap, but new graphics files will need to be written. Preferrably, the application will allow the creation of files that it will also display for testing purposes.

What kinds of tools and/or resources will QuickMap need to do what it's supposed to do? (technical feasibility)

See the [SVGmap] page. In particular, Batik looks promising (Java SVG browser), and maybe svgImage (small SVG application). Tools for converting the SVG data to "raster images" will be needed, so that the SVG data can be exported to something like Adobe's Portable Document Format (PDF) and/or placed on dead tree.

Possbile Problems

• Printing
  • How do you print a map that's larger than what a laser/inkjet can fit (either 8x10.5 or 10.5x16.5, or any of the euro page sizes minus a 1cm border on each side of the page)
  • how good is java printing in any case?
• 2D interaction with GTK/SWT
  • can you build an interface that bridges Java 2D and the user interacting with map objects?

What will the user see when they start a QuickMap session? (Plan of action, physical design)

The overall look and feel will be patterned after The Gimp, the GNU Image Manipulation Program. GIMP is a graphics editor that is loosely modeled after Adobe Photoshop. The images for tool buttons from GIMP can be used to present a similar interface to users who have previously used any of the mentioned applications. The keybindings in GIMP should also be used if possible.

More details about the user experience...

1. Splash screen: shows the loading of QuickMap resources, including shapes and modules that will be used for implementing mapping functionality.
   • 200 point Perry font used with Neon Gimp plugin (not Alien Glow), #171cdb glow, #ffffff background. Copyright and URL text is 42 point Romeodn with #171cdb colordrop shadow
2. Tooltips will be used for menu items/objects to show what each object is/does. Tooltips will be used in the main object drawing area to show a small stat block about that object (object's real name (Somecity, high priest's living chamber), type (small city, rectangular room), and other related data (population, monsters, encounter key, encounter name)
3. Program tips - a list of tips that are shown one at a time when the user starts the program, and again in the help menus or user/developer's guides/tutorials. memorize which tips have been shown in the user's preferences file
4. Status bar text can be used to describe a tool, then describe tool actions once that tool is selected. Any help topics that are related to the text in the status bar can be highlighted and linked so that the user can click on them and read the information contained from the hyperlink
5. Main user interface, with a collection of panels that allow the user to build maps. All of the below panels will be detatchable, so that the user can rearrange them to suit their preferences
   • tools panel
     • pointer tool (arrow pointer)
     • select tool (box, circle, polygon selection shapes)
     • paint brush tool
     • pencil tool
     • zoom slider? either put the zoom slider here or at the bottom of the main drawing window
   • layers panel
     • background layer, will act as the fill for any layers that do not cover the background layer
     • grid layer
       • selectable grid pattern (square or hexagonal)
       • adjustable spacing between grid elements
       • the grid layer should stay locked on top of other layers, unless the user unlocks it from it's position
       • multiple grid line styles, dotted, dashed, solid, morse code-y
       • multiple grid colors and/or opacity
       • all of the above attributes can be selectable in the properties for that layer
       • user layers, where the user can group objects together and give the layer custom names.
       • the layers can be moved up/down among the other layers. The topmost layer is always seen, the bottommost layer will be covered by all overlapping objects
       • different layers can be locked together by the user, so that when a layer is moved up or down around the locked layers, the layer being moved will move around the block of locked layers instead of moving between the locked layers
   • Colors panel, showing 16 or 32 user selectable colors; dockable or detatchable; when it's docked, the color swatches are lined up in one single row, when undocked into it's own dialog, the colors are lined up into rows and columns depending on how big the user has sized the the color dialog
   • Drawing objects panel, a list of pre-created SVG objects that users can place on the map and resize/rotate as desired
   • Objects panel, a list of objects that have been placed in the mapping area. Objects can be dragged/dropped on top of other objects so as to create a heirarchy. A room object might contain a few door objects, a table object and a trap object, as well as an encounter object. Objects can also be moved among layers by drag/drop. The objects dialog should also have several "views", where the objects are sorted in different ways. For example, sort by level, sort by room, or do a custom order sort.
     • Allow loading and unloading of different groups of objects. This is so the user can keep the object space uncluttered, and also so as to try and conserve memory as the program is running. The objects that the user places in the main drawing window either get saved with the file or references to those objects get saved, depending on what the user selects at save time
     • For each object, have a properties window show the properties of that object. Read-only properties are shown in a different color than the properties that can be written to. Advanced properties (object_internal_name for example) can be shown, but should be shown in a different color again from the basic properties.
   • main drawing window, will hold all of the objects dragged from the drawing objects panel. the objects will be layered according to the order listed in the layers panel. A 'zoom' slider will be placed at the bottom of either the main drawing window or at the bottom of the tools panel. Zoom slider should go at the bottom of the main drawing window, as each drawing window can be at a different zoom factor, having the zoom slider go in the toolbox might confuse people when they move from drawing window to drawing window

• Context menu (right click, or Ctrl-click on Macs)
  • group/ungroup objects
  • cut/copy/paste
  • snap to grid, don't snap to grid
  • properties of object(s) dialog; the properties menu should be customizable so it only shows the data that the user wants to see, not every piece of data about the object, including stuff the user may not care about
  • merge/unmerge objects; merging objects will take two objects and create one object, with overlapping lines being erased. Merging objects would be a good way to create irregular sized/shaped rooms that can be then resized/reshaped as needed.
• Keybindings
  • Carry across as many of the Gimp keybindings as practical.
• Misc actions
  • fog of war?
  • spell area radius
  • live mode/preview mode: live mode will have a minimum of controls, or be a completely different application built using a subset of the classes needed to build QuickMap; live mode lacks editing tools, it's only purpose is to be used in play for displaying maps/encounter areas. Live mode should also be able to run as an applet over the web.
  • have a programwide variable that tracks the last dialog that was used by the user, and when the user calls Help, bring up the help screen for that dialog first before bringing up the main help dialog. Have this quickhelp be turned off via the preferences screen.