Skip to content

README.md

Latest commit

 

History

History
220 lines (170 loc) · 6.68 KB

README.md

File metadata and controls

220 lines (170 loc) · 6.68 KB
Raw

The Puzzle Pits

A classic DOS puzzle game from 1995, modernized to compile and run on contemporary systems.

About

The Puzzle Pits is a puzzle-platform game originally developed in 1995 for DOS. This repository contains the original source code along with a comprehensive compatibility layer that allows the game to be compiled and run on modern operating systems using the Zig compiler.

Current Status

✅ COMPILATION SUCCESS - The game now compiles cleanly with modern tools!

What Works

  • ✅ Complete compilation with Zig CC
  • ✅ DOS compatibility layer implemented
  • ✅ Memory management abstractions (farmalloc/farfree → malloc/free)
  • ✅ Port I/O and interrupt stubs
  • ✅ Flexible build system (SDL or stub builds)
  • ✅ All header dependencies resolved
  • ✅ Function signature compatibility fixed

In Progress

  • 🔄 SDL2 graphics implementation (partial)
  • 🔄 Runtime testing and debugging
  • 🔄 Audio system integration

Known Limitations

  • Runtime may crash with stub implementation (expected behavior)
  • SDL implementation incomplete - needs finishing for full functionality
  • Game assets not included (requires original PITS95 directory)

Quick Start

Prerequisites

  • Zig compiler (tested with 0.11+)
  • Optional: SDL2 development libraries (for graphics/audio)

Build Options

Option 1: Stub Build (No Dependencies)

git clone <repository>
cd The-Puzzle-Pits
./build.sh --no-sdl

This creates executables that run but don't display graphics (useful for testing compilation).

Option 2: SDL Build (Full Functionality - When Complete)

# Install SDL2 development libraries first
# Ubuntu/Debian: sudo apt install libsdl2-dev
# Fedora: sudo dnf install SDL2-devel
# macOS: brew install sdl2

./build.sh --sdl

Running the Game

cd compiled-version
./run_pits.sh    # Main game
./run_demo.sh    # Demo version

Development Environment

Using Nix (Recommended)

nix develop                    # SDL development shell
nix develop .#nosdl           # No-SDL development shell

Manual Setup

  1. Install Zig compiler
  2. Optionally install SDL2 development libraries
  3. Run build script

Project Structure

The-Puzzle-Pits/
├── *.C, *.H              # Original game source files
├── compat.h               # Main compatibility header
├── nosdl_compat.h         # Stub implementations (no SDL)
├── sdl_compat.h/.c        # SDL2 implementations (partial)
├── gfxa_stub.c            # Assembly function replacements
├── build.sh               # Build script
├── flake.nix              # Nix development environment
├── build/                 # Compiled object files
├── compiled-version/      # Final executables
└── compiled-version/PITS95/  # Game assets (not included)

Technical Details

Compatibility Layer

This project implements a comprehensive DOS-to-modern compatibility layer:

  • Memory Management: farmalloc/farfree → malloc/free
  • Port I/O: inp/outp → stubbed functions
  • DOS Interrupts: interrupt handlers → stub implementations
  • Video: VGA mode 13h → SDL2 or stub buffer
  • Input: DOS keyboard/mouse → SDL2 or stub events
  • File I/O: DOS paths → POSIX paths with compatibility

Build System

The build.sh script supports two build modes:

  1. Stub Mode (--no-sdl): No external dependencies, functions execute but no I/O
  2. SDL Mode (--sdl): Full SDL2 integration for graphics and audio

Original Architecture

  • Written in C for DOS (1995)
  • Used DOS-specific libraries (conio.h, interrupt handlers)
  • Direct VGA memory access
  • Assembly routines for graphics primitives
  • Sound Blaster audio support

File Descriptions

Core Game Files

  • PITS.C - Main game logic and menu system
  • DEMO.C - Demo mode implementation
  • GFX.C - Graphics and display routines
  • FILE.C - File I/O and utilities
  • DIG.C - Digital audio system
  • LOAD.C - Asset loading routines
  • ENV.C - Environment variable handling
  • DMA.C - Direct Memory Access for audio

Headers

  • GFX.H - Graphics function declarations
  • FILE.H - Core type definitions and file functions
  • TILEDEFS.H - Game constants and tile definitions
  • OLDSOUND.H - Audio system structures
  • ENV.H - Environment handling
  • SB.H, DIG.H, DMA.H - Audio subsystem headers

Compatibility Layer

  • compat.h - Main compatibility interface
  • nosdl_compat.h - Stub implementations
  • sdl_compat.h/.c - SDL2 implementations
  • gfxa_stub.c - Assembly function replacements

Known Issues

Compilation Warnings

  • Unused variables (legacy code artifacts)
  • Array subscript type warnings
  • Unknown pragma directives from DOS compiler

Runtime Issues

  • Stub build executables may crash (expected - no real I/O)
  • SDL build needs completion for stable execution
  • Asset loading paths may need adjustment

Missing Components

  • Game asset files (levels, graphics, sounds)
  • Complete SDL2 graphics implementation
  • Audio mixing and sound effects
  • Input mapping configuration

Contributing

Priority Tasks

  1. Complete SDL2 Implementation

    • Finish graphics rendering pipeline
    • Implement audio mixing
    • Add input event handling

  2. Runtime Debugging

    • Test execution with SDL build
    • Fix crashes and compatibility issues
    • Verify asset loading

  3. Code Cleanup

    • Address compilation warnings
    • Optimize compatibility layer
    • Add error handling

Development Workflow

  1. Fork the repository
  2. Create a feature branch
  3. Test both build modes: ./build.sh --no-sdl and ./build.sh --sdl
  4. Ensure no new compilation errors
  5. Submit pull request

Coding Standards

  • Maintain compatibility with original C style
  • Add comments for new compatibility functions
  • Preserve original game logic wherever possible
  • Test changes with both build configurations

Historical Context

This is a preservation project for a 1995 DOS game. The original used:

  • Borland C++ compiler
  • DOS-specific libraries and system calls
  • Direct hardware access (VGA, Sound Blaster)
  • Assembly language optimizations
  • 16-bit memory model with far pointers

The modernization maintains the original game logic while replacing system-dependent code with portable alternatives.

License

Original game code copyright (c) 1995 Abe Pralle. Compatibility layer and build system modifications for preservation and educational purposes.

Acknowledgments

  • Original game by Abe Pralle (1995)
  • DOS-to-modern porting by compatibility layer development
  • Community preservation efforts for classic games

Status: Compilation successful, runtime implementation in progress.
Last Updated: December 2024