V64TNG
Game Engine re-creation of The 7th Guest.
- Type: PC port
- Game: The 7th Guest
- Runs on Windows
- By mattseabrook
- Latest release 1.0.20261115.1, 2026-11-16
- Source: https://github.com/mattseabrook/v64tng
README
v64tng
Current release: 1.0.20261115.1
v64tng.exe is a Windows x86_64 executable that is an attempt at re-creating the complete 7th Guest game engine from scratch. It is written in C++23 and uses Vulkan or DirectX for graphics, WASAPI for PCM and software-synthesized audio, WinMM for General MIDI output, and Win32 input handling. The game engine is designed to work placed into the original game directory (regardless of where you purchased it/what version you have), and it is required to be used with the original game data files.
Semantic Disassembly Progress
Current source inventory: DOS 283/283 (100.0% entry-role coverage), Windows 174/336 (51.8%), and Mac 55/80 (68.8%) jump-table entries, with 207 verified Mac records including internal routines. The DOS total includes all 22 entries recovered beyond the analyzer seed, including indirect bank handlers, interrupts and callbacks. Newly discovered entries will be added to the denominator. Entry-role coverage does not establish complete code/data ownership, original symbols, external-driver internals, or full gameplay correctness. All executable source changes preserve the canonical artifact hashes.
| Original executable | Verified semantic roles | Provisional roles remaining | Verified entry-role coverage | Lossless source-byte coverage |
|---|---|---|---|---|
V.EXE 1.30 | 283 / 283 | 0 | 100.0% | 101,624 / 101,624 bytes (100%) |
v32tng.exe 1.02b1 | 174 / 336 | 162 | 51.8% | 144,896 / 144,896 bytes (100%) |
T7GMac 1.0 (Classic Mac) | 55 / 80 table-backed entries | 25 | 68.8% role coverage | 1,830,912 / 1,830,912 bytes (100%; byte-identical) |
The DOS inventory includes recovered interrupt/callback entries and grows when new entries are found. The current data pass identifies cursor pointer tables, palette/stream state, XMS descriptors and control pointer, embedded DIGPAK command/state data, cache controls and 200 entries, microscope fields, and the encoded empty-save caption. Seventeen additional video-bank/probe entries are now included in DOS coverage. Data is organized by subsystem; mixed regions and unproven gap ownership remain explicitly unresolved.
v64tng defaults to recovered DOS logical hotspot geometry and cursor values
(grvHotspotPolicy: "dos"), feeding the existing responsive window-coordinate
transform. "windows" retains the previous logical geometry independently of
save format and grvMicroscopePolicy.
Window sizing, coordinate scaling, the intentional 640×320 crop without the
original top/bottom bars, and the top-bar shortcut remain in place. Original logical hotspot accuracy and modern responsive scaling are separate
steps; recovery does not override the presentation choices. Full gameplay and
platform equivalence remain human review work.
The grooviev1 modding guide documents media, archives,
fonts, Mac resources and the new shared-decoder GRV listing/assembly commands.
Auxiliary automated test harnesses have been removed at the maintainer's
request. Each original disassembly retains one build.sh containing its
canonical byte-identity gate. Builds are permitted; engine/toolkit testing is
performed by the maintainer.
Quick Navigation:
-
Developer wiki catalogue → The 7th Guest Developer Wiki
-
Want to play the new version? → Running the Game
-
Building
v64tng.exesource? → Quick Start Guide -
Build
V.EXEfrom source → DOSV.EXE1.30 NASM project -
Build
v32tng.exefrom source → Win32v32tng.exe1.02b1 NASM project -
Mac disassembly and reconstruction → Classic Mac
T7GMacsource project -
CD-i disassembly and reconstruction → Philips CD-i source project
Table-of-Contents
- v64tng
- Disclaimer
- Usage
- Game Engine Architecture
- RL
- GJD
- GRV
- VDX
- Header
- Chunk Header
- Chunk Types
- 0x20 Bitmap
- 0x25 Delta Bitmap
- Opcodes
- Tile Alteration Using Predefined Map (0x00 - 0x5F)
- Tile Fill Using Individual Palette Entries (0x60)
- Line Skip and Tile Reset (0x61)
- Tile Skipping within a Line (0x62 - 0x6B)
- Solid Tile Filling with a Single Color (0x6C - 0x75)
- Multiple Tile Filling with Different Colors (0x76 - 0x7F)
- Variable Palette Tile Coloring (0x80 - 0xFF)
- Encoder Preference Profile
- Original-player
25hpath
- Opcodes
- 0x80 Raw WAV data
- 0x00 Frame Duplication
- Notes
- XMI
- SPHINX.FNT
- Cursors
- LZSS
- Historical Development / Technology
- Developers
Disclaimer
This project is an academic endeavor, created as a technical study and homage to the original software The 7th Guest. It is important to clarify that this project is not officially affiliated with, connected to, or endorsed by the original creators or any of its subsidiaries or its affiliates. This project's primary aim is to serve as an educational resource and a platform for learning and research. It seeks to explore the underlying technology, software architecture, and design principles that informed the creation of The 7th Guest. In replicating the engine, it pays tribute to the groundbreaking work of the original developers and aspires to provide a springboard for further study, innovation, and appreciation within the realms of game development and computer science. This project does not intend to compete with or infringe upon the intellectual property rights of the original software or its creators. Its use, modification, and distribution are intended strictly for non-profit, educational purposes. All trademarks and registered trademarks mentioned herein are acknowledged as the property of their respective owners.
Usage
Running the Game
Running v64tng.exe with no arguments opens the launcher, where the essential
video and audio settings can be changed before selecting PLAY. The command
line can still bypass the launcher and start the game directly with an
exclamation mark:
v64tng.exe !
The engine must be placed in the original 7th Guest game directory alongside the game's data files (.GJD, .RL, etc.). It is compatible with all known releases of The 7th Guest, regardless of where purchased (Steam, GOG, original CD-ROM).
During gameplay, Escape opens the in-game menu; from its main page, Escape
resumes the game. This also applies after entering the cheat room selector or
foyer through SCRIPT.GRV. The title screen retains its own New/Load/Quit
controls. Gameplay uses an 80% music mix, reduced to 35% while PCM dialogue or
effects play; menu music remains at 100%. These levels multiply the configured
MIDI volume and do not change PCM volume.
Win32 Asset Browser and GRV Editor
The native Win32 application exposes a top-level Tools menu. Asset Browser
tab scans every matching T7G .RL/.GJD pair in a selected folder, combines
them into one sortable and filterable catalog, and displays the archive,
resource type, offset, and size. Double-click a .VDX entry to open it in the
existing VDX Info tab, where its bitmap, palette, delta frames, and audio
chunks can be inspected and played with Previous, Play/Pause, Stop, and Next.
Right-click any catalog row and choose Save VDX As... (or Save Resource
As...) to copy exactly that RL-indexed byte range from its GJD archive to a
chosen file. Export does not decode, normalize, or re-encode the resource.
The Tools window supports edge/corner resizing and maximize. The fullscreen button has been removed; F11 remains available to fill the current monitor. Escape exits Tools fullscreen and restores its previous placement. In VDX Info, drag the dividers to size the preview, bitmap details, palette/delta area, and audio table. Double-click a divider to reset it. The preview scales with its aspect ratio preserved, and all tabs use compact 9-point Segoe UI with DPI scaling. Table columns remain manually resizable; Tab/Shift+Tab navigate the controls.
Alpha Mode in the VDX preview keeps only pixels written by the selected frame. The square beside it selects transparent, magenta (#FF00FF), blue (#0000FF), or green (#00FF00). Transparency appears as a checkerboard in the preview and is saved as actual PNG alpha. This extracts encoded delta writes, with no automatic actor segmentation: rewritten background tiles remain, still frames are fully opaque, and duplicate or palette-only frames are empty in Alpha Mode.
Brush beside Alpha Mode enables alpha and pauses playback. Click or hold
left-drag over missing areas to reveal the fully decoded frame's original RGB.
The size button selects a square brush of 1, 4, 8, 16, or 32 source pixels.
Right-click/drag marks pixels as background; Shift-right-drag restores the
original delta mask at the brush location;
Reset Brush clears all corrections on the current frame. Corrections stay
with their individual frames while navigating the clip and are included in
both PNG export actions when Alpha Mode is on. Masks autosave after each stroke,
after Reset Brush, and once per second during painting. Reopening the same clip
reloads its edits, including when opened from a GJD archive. Projects live in
.\ActorMasks\<content-key>\: a source VDX snapshot plus
versioned .vdxmask files containing complete masks and editable overrides.
The status bar shows the save location. A save failure retains edits in memory
and blocks changing clips or closing Tools until saving succeeds.
See mask project format and actor recovery design.
Choose the transparent background for RGBA samples. Brushing restores opacity;
it does not remove background colour already blended into the source actor.
Save Frame... exports the displayed frame at its native resolution.
With Alpha Mode off, indexed VDX frames are saved as indexed PNGs preserving
all 256 palette entries and the exact pixel indices. Transparent RGBA exports
preserve original RGB beneath transparent pixels as well. PNG writing performs
no quantization, gamma conversion, resizing, or alpha premultiplication.
Dump PNGs... asks for a parent folder and creates a folder named after the
VDX, containing 00000.png, 00001.png, and so on, including duplicate frames
to preserve sequence timing. Choose a new destination if that folder already
exists. With Alpha Mode off, both actions export the complete composited frames.
Previous/Next and chunk-row selection stop playback at the selected frame;
Play/Pause uses the VDX timing and resumes audio from that frame. Stop returns
to frame zero; reaching the end holds the final frame.
Tools -> GRV Editor scans the same asset root for .GRV files, sorts them
alphabetically, selects SCRIPT.GRV by default, and decompiles the selected
file directly from its real bytes into an editable in-memory assembly listing.
Its scene pane resolves the input loop's packed RL/GJD VDX reference, decodes
the animation, and draws the real GRV hotspot rectangles over the original
640x320 frame on a 640x480 coordinate canvas. Because one loop can serve
several views, a separate scene selector exposes the statically reachable VDX
candidates rather than asserting a false one-loop/one-scene mapping. Input
loops, scene candidates, and frames can be selected or played without
launching the game.
Right-click a script and choose Decompile... to save a .grv.asm listing,
or use Assemble As... to reconstruct a .GRV from the listing's raw-byte
column. The current assembler is deliberately lossless rather than symbolic:
editing raw instruction bytes is authoritative; changing only mnemonic text
does not yet relocate branches or rewrite operands.
When SCRIPT.GRV exists beside the executable, that directory is cataloged
automatically. A development checkout also recognizes a local T7G
subdirectory. The browser uses only the T7G RL/GJD and VDX decoders; the
Clandestiny code supplied for UI study did not introduce Groovie 2 resource or
playback behavior.
GitHub and updates
The game window's Help menu contains About, a separator, GitHub, another separator, and Check for Updates.... GitHub opens the project repository in your default browser.
Check for Updates... reads the official public GitHub releases and shows the newest release's title, version, publication date, author, complete release notes and asset links in a selectable, formatted text box. Headings, emphasis, lists and code are formatted l