Upgrade Guide

Migrating from older HGE versions to newer releases.

General Upgrade Process

When upgrading HGE versions:

  1. Backup your project — Keep your working version safe
  2. Read release notes — Check for breaking changes
  3. Update files — Replace headers, libraries, and DLLs
  4. Rebuild — Compile and fix any errors
  5. Test — Verify all features work correctly

Common Changes Between Versions

Header Changes

If you get compilation errors about missing declarations:

  • Check for renamed functions or classes
  • Look for moved functionality between headers
  • Verify include paths are correct

Library Changes

If you get linker errors:

  • Ensure you're using matching lib and DLL versions
  • Check for renamed or removed functions
  • Verify library paths are correct

Runtime Errors

If your game crashes or behaves differently:

  • Check for changed default values
  • Verify resource file compatibility
  • Test with verbose logging enabled

Version-Specific Notes

Upgrading from 1.6.x to 1.8.x

Key changes to watch for:

  • Some helper class implementations moved
  • Minor API signature changes
  • Updated BASS audio library

Upgrading from Earlier Versions

For very old HGE versions:

  • Expect more significant changes
  • Consider a gradual migration
  • Test thoroughly at each step

Compatibility Tips

Conditional Compilation

For code that must work across versions:

#if HGE_VERSION >= 0x180
    // New API style
#else
    // Old API style
#endif

Feature Detection

Test for features rather than versions when possible:

// Check if a texture loaded successfully
HTEXTURE tex = hge->Texture_Load("test.png");
if (tex)
{
    // Feature works
    hge->Texture_Free(tex);
}

Troubleshooting

Compilation Errors

  • Clean and rebuild entirely
  • Check header include order
  • Verify preprocessor definitions

Linker Errors

  • Match Debug/Release configurations
  • Use consistent calling conventions
  • Check for duplicate symbols

Runtime Errors

  • Enable logging: hge->System_SetState(HGE_LOGFILE, "hge.log");
  • Check the log for initialization failures
  • Verify DLL versions match

See Also