Minecraft in GTA 5.
Two games, one window, running at once.

What the Minecraft × GTA V mod actually is

Three claims travel with this mod, and only one of them is close to right. The upstream example is called a passthrough mod, and that word is the whole point.

• It is not Minecraft ported into GTA V. A real Minecraft Java client runs at the same time as GTA V, in its own window, and the mod makes the two communicate. GTA's camera drives Minecraft's camera; Minecraft's picture is composited into GTA's frame.
• It is not a game an AI generated from nothing. The mod is written code — a Fabric mod on one side, a ScriptHookV script and a ReShade add-on on the other. The upstream credits say it was written with Claude Code; the example folder contains the source implementation.
• The two worlds are genuinely linked, not layered as a video. Blocks you place in Los Santos become real GTA collision, so people and cars stop at your walls. That linkage is what separates it from a recording played back on a screen.

If what you want is to build your own game mod rather than read about this one, start with the ten-stage workflow instead. This page documents one upstream example.

How the passthrough works

The upstream readme draws the architecture as two halves talking over a local WebSocket. Reproduced here in outline:

GTA V (story mode)                            Minecraft 26.3 + Fabric
  MCPassthrough.asi                             dev.rehan.passthrough
    script.cpp  -- WebSocket 127.0.0.1:25599 -->  cam / ground / key / slot / cmd
                <------------------------------  explosion events
    compositor.cpp (ReShade add-on)  <-- shared memory --
    MCPassthrough.fx                   world RGBA + depth, overlay RGBA

The pieces, in the order they run:

1. Camera. Every GTA frame, the script sends the camera GTA actually rendered with, plus the player's feet position and heading. Minecraft renders from that camera with no sky, fog or clouds, and Steve stands where the hidden GTA player stands.
2. Ground. The script probes GTA's ground around the player — 40 blocks out, 160 probes per frame — and sends it as ground. The mod fills those columns with barrier blocks, so blocks, mobs and items rest on GTA's terrain.
3. Frames. The mod copies Minecraft's colour and depth buffers into named shared memory, and the hand, HUD and screens as a separate overlay. The ReShade effect draws Minecraft wherever it is nearer than GTA's depth buffer, re-projects it to GTA's current camera, then relights and colour-grades it to match.
4. Events back. Explosions, projectiles, sword swings, ender pearls, mobs and the Nether's hot blocks go the other way, and the plugin acts them out in GTA.
5. Input. GTA keeps focus. The plugin forwards the mouse buttons, the wheel and the number keys to Minecraft and stops GTA acting on them.

Coordinates are mapped one-to-one: 1 GTA metre equals 1 block, with F8 re-levelling the ground under you. The upstream readme documents the exact axis and yaw/pitch conversion if you intend to touch that code.

Sources: Passthrough example readme ↗

What you need before starting

This is a two-game build, not a plugin install, and it was built and tested upstream on GTA V Legacy (Steam, game build 3889) with ScriptHookV 3889.0 and ReShade 6.8.0 in September 2026. Version numbers below are theirs, not a guarantee for your machine.

Paths default to a single working folder and are read from environment variables, so you can move the build without editing scripts. The upstream readme lists every variable and its default.

Build, install and run

Five stages based on the upstream instructions. Obtain the example from the upstream repository and run the shell steps from its examples/minecraft-gta5-passthrough/ directory in WSL.

gta/fetch_deps.sh   # ScriptHookV SDK + ReShade headers and runtime DLLs
gta/build.sh        # builds build\MCPassthrough.asi with MSVC
gta/install.sh      # copies it into the GTA V folder

Controls

GTA keeps the controls. Only the Minecraft-specific actions are forwarded:

Everything else — walking, driving, the camera, the view key — is GTA's own, and Minecraft follows it.

Limits, and the rules you do not bend

The interesting part of this example is how carefully it stays inside its own boundaries. Read these before you spend a weekend on it.

• Story mode only, never GTA Online. The install passes -nobattleye, which also keeps GTA Online out. That is not a limitation to work around — taking a modded client online is how people get banned, and this example does not do it.
• Block placement has a ceiling. Each block you place or break comes back as a GTA prop, capped at 400. GTA crashes at around 1500 script objects, so the cap exists to keep you below the crash line. Treat 400 as the wall it is.
• The Enhanced edition is not supported. The example targets GTA V Legacy (GTA5.exe). A GTA update can also outrun your ScriptHookV until a new one ships.
• Performance is honest, not smooth. Minecraft renders unfocused, its window is resized to GTA's picture, and the ReShade effect re-projects every frame to hide link latency. Expect a heavy machine to be the difference between playable and not.
• It is a source example, not a release. There is no download button here or upstream for this folder — it is code you build. Check the source and provenance of downloads offered elsewhere rather than assuming they match this example.

Windows with WSL, GTA V Legacy, ScriptHookV, ReShade with add-on support, JDK 25 and MSVC are a real setup cost. If you only want to understand how the mod works, the architecture section above is the whole idea; the build is for people who want to run it.

Sources: Passthrough example readme ↗ · Project repository ↗

Build your own first mod →CLI command reference →