README

DOS Game Engine

A retro DOS multimedia engine written in Turbo Pascal 7.0 (1994-era), featuring VGA Mode 13h graphics, AdLib/OPL2 music, and Sound Blaster digital audio. Perfect for demoscene-style programming, retro game development, and learning classic DOS systems programming.

📸 Screenshots

Tilemap Rendering

<small>TMXTEST.PAS</small>

</td>
<td align="center">
  [![Variable-Width Font Test](/catalog-images/08/085d093501892ca58cfac3d6.png)](https://github.com/DynartInteractive/DOS-Game-Engine/blob/HEAD/IMAGES/XICLONE.png)

Example Game

<small>XICLONE.PAS</small>

</td>

</tr>
<tr>
  <td align="center">
    [![Sprite Animation Test](/catalog-images/6a/6a894ff1868a97451b9150da.png)](https://github.com/DynartInteractive/DOS-Game-Engine/blob/HEAD/IMAGES/SPRTEST.png)

Sprite Animation

<small>SPRTEST.PAS</small>

</td>
<td align="center">
  [![Setup Utility](/catalog-images/c9/c9386106cea7d981b1bb3ffd.png)](https://github.com/DynartInteractive/DOS-Game-Engine/blob/HEAD/IMAGES/SETUP.png)

Setup Utility

<small>SETUP.PAS</small>

</td>

</tr>

🚀 Quick Start

Prerequisites

• Turbo Pascal 7.0 (TPC.EXE in %PATH%)
• DOSBox-X, 86Box or real DOS/FreeDOS
• HIMEM.SYS loaded (for XMS extended memory support, default in DOSBox)

First Run

# Compile & try the example game (WIP)
cd ..\XICLONE
CXICLONE.BAT
XICLONE.EXE

Controls:

• Left/Right: Move the stack left and right
• Down: Falling faster
• Space: Rotate stack
• ESC: Pause

✨ Features

🎨 Graphics

• 320×200 VGA Mode 13h with double-buffering
• Variable-width bitmap fonts (PCX + XML)
• UI widget toolkit (buttons, labels, checkboxes, line edits)
• PCX/BMP image loading (Aseprite, GIMP compatible)
• TMX tilemap support (Tiled Map Editor)
• Delta-time sprite animation system
• Dirty rectangle optimization

🔊 Audio

• HSC music (AdLib/OPL2, interrupt-driven)
• XMS-based sound bank (VOC format, 8-bit PCM)
• Sound Blaster DSP driver (DMA-safe mixing)

🎮 Input

• Hardware keyboard handler (INT 9h)
• Mouse support (INT 33h, 3-button)

🧠 Memory & Performance

• XMS extended memory manager (>1MB RAM)
• RTC high-resolution timer (IRQ8, no HSC conflict)
• Dirty rectangle rendering

📦 Resources

• XML-based resource manager (lazy/eager loading)
• Unified game loop framework
• Lightweight XML parser/writer
• INI configuration system
• String hash map (O(1) lookup)
• Linked list utilities
• CRC32 hash (ISO 3309, PHP compatible)
• High score system with tamper protection

🛠 Tools

• Sound card setup utility
• Text-mode UI toolkit
• Debug logger (startup/shutdown safe)
• Comprehensive test suite

📚 Documentation

Core Graphics

• VGA.PAS - Mode 13h graphics driver (320×200, 256 colors)
• PCX.PAS - PCX image loader/saver
• BMP.PAS - Windows BMP image loader/saver
• VGAPRINT.PAS - Embedded 8×8 bitmap font
• VGAFONT.PAS - Variable-width font system
• SPRITE.PAS - Delta-time sprite animation
• DRECT.PAS - Dirty rectangle optimization

User Interface

• VGAUI.PAS - VGA widget toolkit (buttons, labels, checkboxes, line edits)
• TEXTUI.PAS - Text mode UI system (SETUP utility)

Audio

• SBDSP.PAS - Sound Blaster DSP driver
• SNDBANK.PAS - XMS sound bank manager
• PLAYHSC.PAS - HSC music player (AdLib/OPL2)
• HSC Format - HSC file format specification

Input

• KEYBOARD.PAS - Hardware keyboard handler (INT 9h)
• MOUSE.PAS - Mouse driver (INT 33h)

Tilemaps

• TMXLOAD.PAS - TMX tilemap loader (Tiled Map Editor)
• TMXDRAW.PAS - TMX rendering system

Memory & Timing

• XMS.PAS - Extended memory manager (HIMEM.SYS)
• RTCTIMER.PAS - RTC high-resolution timer (IRQ8)

Resources

• RESMAN.PAS - XML-based resource manager
• MINIXML.PAS - Lightweight XML parser/writer
• CONFIG.PAS - INI configuration system

Utilities

• GENTYPES.PAS - Generic pointer and array types, alignment constants
• MATHUTIL.PAS - Math utilities (Clamp, Lerp, Min/Max, 16.16 fixed-point)
• STRUTIL.PAS - String conversion utilities
• STRMAP.PAS - String hash map (O(1) lookup)
• LINKLIST.PAS - Doubly-linked list
• CRC32.PAS - CRC-32 hash (ISO 3309, PHP compatible)
• HISCORE.PAS - High score management with tamper protection
• LOGGER.PAS - Debug file logger

Game Framework (DGE - DOS Game Engine)

• BASEGAME.PAS - Game framework core (TBaseGame object, subsystem integration)
• SCREEN.PAS - Screen/state management (TScreen base object)

Guides

• Build Guide - Compilation instructions
• Asset Creation - Creating PCX, VOC, HSC, TMX assets
• Example Program - Complete game example walkthrough

📁 Project Structure

D:\ENGINE\
????????? DOCS\           Documentation and design notes
????????? TESTS\          Test programs (IMGTEST, TMXTEST, SPRTEST, FNTTEST, etc.)
????????? SETUP\          Sound card setup utility
????????? UNITS\          Core engine units (VGA, SBDSP, Keyboard, Mouse, XML, Sprite, etc.)
????????? VENDOR\         Third-party libraries (SBDSP, XMS, HSC)
????????? XICLONE\        Example game (Columns/Xixit clone, WIP)

🎨 Creating Assets

PCX Images:

• Aseprite (recommended): File → Export → .pcx (8-bit indexed color mode)
• GrafX2 (good palette handling): File → Save → .pcx
• GIMP: Image → Mode → Indexed (256 colors) → Export as PCX
• Photoshop: Image → Mode → Indexed Color → Save As PCX (8 bits/pixel)
• Common sizes: 320×200 (full screen), 32×32 (sprites), 16×16 (tiles)

VOC Sounds: Use Audacity → Mix to Mono → Resample 11025Hz → Export as VOC (Unsigned 8-bit PCM).

HSC Music: Use Adlib Tracker II or HSC-tracker.

TMX Tilemaps: Use Tiled (see TILEMAP.md for restrictions).

📜 Credits

• SBDSP: Romesh Prakashpalan (1995)
• XMS Driver: KIV without Co (1992)
• HSC Player: Glamorous Ray (1994)

🤝 Contributing

Contributions welcome! This engine preserves 1990s DOS demoscene techniques while remaining hackable and educational.

🔒 Asset Licensing

Some DATA files (images and tilesets) are © 2025 Dynart Kft. Free for non-commercial use with credits. Commercial use requires separate license. See ASSETS_LICENSE.md.

Made with 💾 for retro DOS enthusiasts