Current Baseline: 2.04

The MHFramework Project

Table of Contents

* Introduction
* Justification for the MHFramework 2 Project
* Compatibility
* Release History
* Engineering the MHFramework 2 Project
* Comparison to Standard Game Engine Features
* See Also


MHFramework is my home-brewed game engine for creating games using Java Standard Edition technology. As its name subtly implies, it began life as a mere framework of classes that provided a few fundamental features needed in most games, such as sprite animation, image loading, and primitive scene management. But as the requirements of my games grew more sophisticated, so did the framework upon which they were built.

I consider MHFramework 1 to be the experimental version -- the one that let me try out some things and figure out what was missing or in need of improvement. Now MHFramework 2 is underway, guided by my analysis and ongoing notation of the strengths and weaknesses of version 1 plus the documented requirements of my next series of game projects.

Justification for the MHFramework 2 Project

MHFramework 1 was developed gradually over the course of about five years. Its growth was mostly reactionary, since I just added components here and there as they became necessary for whatever project I was doing at the time. Therefore, much of the first version was not well engineered. Its cohesion varied from one place to another, and there were several places where things were less efficient, or at least less convenient, than I thought they should be.

For these reasons, MHFramework needed more than just another piecemeal upgrade. It's getting a pretty severe overhaul because my next projects are going to need much stronger support than my casual games of the past have required.

Back to top


MHFramework 2 will not attempt to maintain backward compatibility because that would unnecessarily bloat the code and require the inclusion of several classes that could otherwise be eliminated from the package. However, some projects will be upgraded as specific releases become available. Older versions of the framework and the engine will be kept in order to maintain compatibility, but there will be no further development, enhancement, or modification of those obsolete versions.

Back to top

Release History

VersionFeaturesAffected classes
  • Framework for particle system.
  • MHGUIDialog hierarchy.
  • Mouse cursor toggle and customization
  • Support for dynamic textures (texture image to iso tile transformation)
  • Isometric tile transformer utility
  • MHFile hierarchy for text and serialized object files.
  • Thread manager
  • Error message display in MHScreen
  • Error reporting and color validation in MHServerModule
  • Fixed windowed mode rotation bug in MHActor
  • Enhanced support for graphical fonts
  • Command Pattern implementation in MHGUIButton
  • Sound effects in MHGUIButton
  • A* path-finding support for tile maps
Affected Classes: MHActor, MHScreen, MHServerModule
New classes: None.
Eliminated classes: None.
  • Added detail layer to tile maps.
  • Changed all tile size constants to reference mouse map size.
  • Made a more advanced application launcher dialog that allows selection of resolution in addition to choosing full screen vs. windowed mode.
  • Created MHSerializable interface to be implemented by objects that must be serialized (passed across a network, written to a file, etc.).
Affected Classes: MHMapCell, MHIsoMouseMap
New classes: MHSerializable
Eliminated classes: None.
  • Support for rotation and translation vectors
  • Refined actor hierarchy
  • Multithreaded client/server modules with standardized message object
  • Standard playing card deck
  • FPS measurement
Affected Classes: MHActor, MHGame, MHDisplayModeChooser
New classes: MHPoint, MHClientModule, MHMessageType, MHNetworkMessage, MHSerializableClientInfo, MHSerializableClientList, MHClientInfo, MHGameServer, MHServerModule, MHRotationLookup, MHPlayingCard, MHPlayingCardDeck
Eliminated classes: MHStaticActor
  • Parameterize MHDisplayModeChooser to allow customization of video mode.
  • Improve support for windowed mode.
  • Simplify use of MHGameApplication.
  • Upgrade all image loading code to use Java's ImageIO class.
  • Upgrade all Graphics parameters to Graphics2D objects.
Affected Classes: MHDisplayModeChooser, MHGameApplication, MHScreenManager, MHDataModel, MHScreen, MHImageGroup, MHFrameSequence, MHAnimationFrame, MHRenderable, MHStaticActor, MHGame, MHActor, MHAppLauncher
New classes: MHVideoSettings, MHFrameworkConstants
Eliminated classes: MHGameWindow

Back to top

Engineering the MHFramework 2 Project

The upgrades to MHFramework are organized into categories that may or may not developed contiguously. The focus and goals of each category are listed below. The numbering and ordering may change, but the general categorizations most likely will not.

Category 0: Improved Video Mode Control

Candidate Tasks:

  • Enable real-time rendering to Image object. (Postponed)
    Workaround: Do not allow users to select screen dimensions that differ from game's native resolution or other explicitly supported modes.

Category 1: Networking

Candidate Tasks:

  • Observer pattern implementation for message handling. (with message listener hierarchy)
  • Categorized system messages.

Category 2: Animation Improvements and Actor System Redesign

Candidate Tasks:

  • Improved frame rate synchronization.
  • New algorithm for pause mode. (Required for discrete motion.)
  • Non-sequential frame sequence numbers in image groups. (Re-test using hashes.)
  • Support for sprite sheets as an alternative to frame sequences.

Category 3: GUI Enhancements

Candidate Tasks:

  • Enhancements to MHGUIDialog.
    • Specify font, border image OR border color and thickness, font color, background color
    • Include button options like OK, OK/Cancel, Yes/No, etc.
  • New user-customizable interface for MHAppLauncher
    • Parameterize with image file, image location, and game title
  • Animated buttons
  • MHGUIToggleButton and MHGUIButtonGroup
  • Pull-down menu (perhaps hidable button menu)

Category 4: Audio System Upgrades

Candidate Tasks:

  • Standardized interface to sound and music classes
  • Volume support in sound class
  • Stereo panning support in sound class
  • Volume support in music class

Category 5: Tile Map System Upgrades

Candidate Tasks:

  • Hex map support
  • Devise new rendering algorithm to accomodate large (multi-cell) objects (easier asset creation)
    OR break into separate wall tiles (more accurate collision detection)
  • Diagnose and repair staggered isometric maps
  • Decouple finely-placed actors from the map data structure.

Category 6: Metrics and Logging

Candidate Tasks:

  • Re-test FPS measurement. It may not be accurate.
  • Debugging constants to set logging level
  • Instance counters for actors

Category 7: Additional Support for Common Game Mechanics

Candidate Tasks:

  • Collision response mechanism -- maybe a collision processor to accomodate discrete time motion.
  • MHCollisionGeometry interface with rectangular, spherical, composite, or custom implementations
  • Generalized inventory system with iterator, search functions, and instance counters for stackable items

Category 8: Artificial Intelligence and Thread Management

All current candidate tasks in this category have been implemented.

Category 9: Optional Improvements

Candidate Tasks:

  • Applet support
  • JDBC encapsulation
  • Gravity constant, hasGravity flag in Actor class
  • Facade for managing global MHFramework singletons
  • General event queue
  • Global singleton keyboard/mouse status structures (like in DirectX)
  • Alpha blended sprites
  • Built-in loading thread for MHScreen classes
  • Isometric adventure starter kit
  • Sidescroller starter kit

Back to top

Comparison to Standard Game Engine Features

Following is a table comparing the features of MHFramework with those commonly found in other game engines.

Feature Currently
2D graphics rendering Yes YesThe current upgrade project will provide additional support for 2D transforms. A system for filters already exists but has not been tested.
3D graphics rendering No YesIt is likely that future versions will support OpenGL, but that is beyond the scope of the current project.
Physics No Yes A pending upgrade is adding built-in support for gravity. Future upgrades will add support for other common physics calculations.
Resource management Yes YesThe sound and music classes encapsulate support for those types of media. Image groups and sprite frame sequences manage image data.
Input detection Yes YesKeyboard and mouse usage has been well-established since the earliest versions of MHFramework. The current upgrade project may involve refining and generalizing the system even further, but that is currently a subject of debate.
Timers YesYesThe engine uses the system clock to calculate frame delays. CornShark has a general timer class for tracking game time. That class will be generalized.
Sprite management Yes YesMHActorList objects maintain collections of all types of actors. This system will be improved with possible inclusion of collision detection.
Audio Yes YesThe upgrade will add more advanced controls and standardization of music and sound interfaces.
Scripting No NoJava's virtual machine allows class files to be added and replaced individually without necessarily requiring a complete recompile. This reason, combined with the loose coupling in MHFramework's actor system, means the engine may never require its own scripting language.
Data structures YesYesJava's collections API works well enough for most cases, but to simplify common requirements, MHF provides actor lists, will soon provide a generalized inventory system, and will eventually include optimization structures like BSP trees.
Artificial Intelligence No YesPathfinding for MHTileMap objects is coming.
Thread management No YesMHFramework will simplify multithreading by establishing a common framework and monitoring services.
Networking Yes YesNetworking support is provided in the package.
User interface componentsYes YesThe engine contains a MHGUIComponent hierarchy which will be expanded and improved.
Collision response No YesA standard interface for communicating and mediating collisions is coming, but the class design is not yet adequate to support all requirements.
Logging and profiling No YesMHF will incorporate standard utilities for these purposes and more.
Editors and utilities Yes YesNew versions of LIME and SpriteTester will be released as the necessary versions of MHFramwork become available. After the implementation of the particle framework, a utility for testing particle effects will follow.

Back to top

See Also

LIME -- Layered Isometric Map Editor

SpriteTester 2 Animation Viewer

MHFramework API Documentation

Back to top