Educational ESP Overlay Example

Overview

This project demonstrates the technical principles behind ESP (Extra Sensory Perception) overlays in game design, using custom 2D game simulations and direct memory reading. It is intended for educational purposes only and does not interact with any commercial games.

• mock_game.py: Runs a simple 2D game and exposes player/item positions via a local HTTP API.
• esp_overlay.py: Polls the API and displays player/item positions in an overlay window.
• test_exe.py: Simulates a rich game environment with multiple players, objects, and terrain features. Automatically writes memory addresses to object_addr.txt for use in hooking.
• esp_hook.py: Hooks into the running test_exe.py process, automatically reads memory addresses from object_addr.txt, and displays all entities (players, objects, terrain) in an overlay window.

Dependencies

• The memory hook demo (esp_hook.py) requires pywin32 and psutil.
• Install all dependencies with:

  pip install -r requirements.txt

Features

• FPS-style simulation: player (WASD movement, mouse aim, shooting), enemies (AI, health, alive/dead), objects (pickups), walls (terrain/obstacles).
• All entities (player, enemies, objects, walls) are exposed in memory for ESP overlay.
• ESP overlay displays positions, health, alive/dead status, and movement paths.
• Automatic address detection for memory hook via object_addr.txt.
• Transparent, click-through overlay window matching monitor resolution.

Controls (FPS Simulation)

• Move: W/A/S/D
• Aim: Mouse
• Shoot: Left mouse button

ESP Hook Overlay Window Features

• The ESP overlay window automatically detects and uses your current monitor's resolution for full-screen coverage.
• The overlay window is borderless, transparent (black is fully transparent), and click-through, allowing you to interact with windows and games underneath.
• All ESP features (players, objects, terrain, labels, paths, distances) are displayed over your desktop/game without interfering with mouse input.

FPS Simulation Entities

• Player: Moves with WASD, aims with mouse, shoots with left click. Has health, position, direction, and a visible field of view (FOV).
• Enemies: Move around, chase the player, can be shot. Each has health, position, alive/dead state, and a movement path.
• Objects: Represent pickups (health or ammo) scattered on the map.
• Walls: Simulate terrain/obstacles.
• Bullets: Fired by the player, can hit enemies.

ESP Overlay Entity Visualization

• Player: Shown as a directional triangle or rectangle, with health and FOV arc.
• Enemies: Shown as colored rectangles/circles, with health and alive/dead status.
• Objects: Shown as colored dots (health/ammo).
• Walls: Shown as rectangles.
• Bullets: Shown as small circles.
• Highlighting: Nearest player to each object is highlighted with a yellow rectangle and line.

How to Run (API Overlay)

1. Install dependencies:

   pip install -r requirements.txt

2. Start the mock game:

   python mock_game.py

3. In a separate terminal, start the ESP overlay:

   python esp_overlay.py

How to Run (Memory Hook Demo)

1. Open a terminal and run:

   python test_exe.py

   This will create/update object_addr.txt with the memory addresses for players, objects, and terrain.
2. Open another terminal and run:

   python esp_hook.py

   The overlay will automatically read addresses from object_addr.txt and display all entities (players, objects, terrain) with labels, movement paths, and relative positions in real time.

How to Run (Transparent Overlay)

1. Run the simulation:

   python test_exe.py

   This will create/update object_addr.txt with the memory addresses for players, objects, and terrain.
2. Run the transparent ESP overlay:

   python esp_hook.py

   The overlay will automatically detect your monitor resolution, use a transparent window, and display all entities (players, objects, terrain) with labels, movement paths, and relative positions in real time.

How to Run (FPS Simulation + ESP Overlay)

1. Start the FPS simulation:

   python test_exe.py

   This will create/update object_addr.txt with the memory addresses for player, enemies, objects, and walls.
2. Start the ESP overlay:

   python esp_hook.py

   The overlay will automatically read addresses and display all entities in real time.

Note:

• The overlay window is transparent and click-through, so you can interact with other windows and games beneath it.
• For multi-monitor setups, the overlay will use the primary monitor's resolution. You can adjust the code to support other monitors if needed.
• Reading memory from other processes requires administrator privileges. Only use this with your own test applications or open-source games.

Troubleshooting

Memory Read Error (299)

If you encounter the error:

Memory read error: (299, 'ReadProcessMemory', 'Only part of a ReadProcessMemory or WriteProcessMemory request was completed.')

This means the requested memory region could not be fully read. This is common if:

• The process is running as a different user or with different privileges.
• The memory region is partially paged out or protected.
• The requested size is too large or misaligned with the actual structure in memory.

Solutions:

• Run both scripts as administrator to ensure full access to process memory.
• Check that the structure sizes and counts in esp_hook.py match those in test_exe.py. If you change the number of players, objects, or terrain, update both scripts accordingly.
• Ensure the memory addresses in object_addr.txt are correct and up-to-date. Restart both scripts if needed.
• Try reducing the number of entities or the path length if your system has limited memory.
• If the error persists, try reading smaller chunks of memory and handling partial reads gracefully in the code.
• This error is caught in esp_hook.py and will print a message but not crash the overlay. The overlay will skip drawing for that frame and continue running. See the exception handling around ReadProcessMemory in your code (e.g., line 155).
• Tip: You can add more robust error handling in your code to skip frames or retry with smaller reads if needed.

Ethical Note

This project is for educational purposes only. Do not use these techniques to cheat in commercial or online games. Respect game developers and communities by following their terms of service.

Homework Extension

As a homework project, students can:

• Add more features to the overlay (e.g., display object types, highlight nearest player/object, advanced terrain visualization).
• Implement overlays for other open-source games or simulations.
• Reflect on the ethical implications of game modification.

ESP Overlay Menu & Feature Selection

A menu is available in the ESP overlay window to toggle features in real time:

• F1: Show/hide player, enemy, and object trajectories (paths).
• F2: Show/hide item values (e.g., Health/Ammo) above objects.

The menu appears in the top-left of the overlay window, showing the current ON/OFF state for each feature. Press the corresponding key to toggle the feature and update the overlay immediately.

How to Use the Menu

• Start the ESP overlay as described below.
• Use F1 and F2 to toggle features while the overlay is running.
• The menu overlay will update to reflect the current state of each feature.