Frequently asked questions
These are the questions players ask most often. If yours isn’t here, ask in the VSPT channel on the official Vintage Story Discord (join the Discord first if the link doesn’t open).
What it is and what it needs
Section titled “What it is and what it needs”What is VSPT?
Section titled “What is VSPT?”VSPT is a mod that replaces Vintage Story’s picture with a real-time path traced one. Sunlight, skylight, torches and lanterns light the world by tracing rays, so shadows, bounced light, reflections, glass and water behave the way light does. NVIDIA’s DLSS Ray Reconstruction turns the few rays traced each frame into a clean picture. On an HDR display the picture is HDR.
It runs only on your computer, for Vintage Story 1.22.7 on Windows and Linux.
What do I need?
Section titled “What do I need?”| Game | Vintage Story 1.22.7 |
| System | Windows 10 or 11, or Linux (below) |
| Graphics card | An NVIDIA GeForce RTX card, desktop or laptop. The Mod DB page suggests an RTX 4060 or better as a starting point |
| Driver | NVIDIA’s own, kept up to date. Setup asks for 535.68 or newer, but DLSS can need a newer one: one tester’s 576.88 was refused (#47) |
| Display | Any. An HDR display is optional |
AMD, Intel and GTX cards are not supported yet (below).
VSPT supports one game version at a time. If the game updates past 1.22.7, VSPT says so once and switches itself off until a VSPT update supports the new version. Nothing is touched meanwhile. Stay on 1.22.7 to keep playing with it.
Why are there several VSPT mods?
Section titled “Why are there several VSPT mods?”Install only VSPT: Path Tracing. Setup downloads the others from the Mod DB for you.
| Mod | What it holds | Why it is separate |
|---|---|---|
VSPT: Path Tracing (vspt) |
The mod, the renderer and setup | Updated most often |
VSPT: Materials (vsptmaterials) |
Material maps for the game’s textures: relief, shine, metal, glow | Large, and changes only when the materials do |
VSPT: Runtime (vsptruntime) |
NVIDIA’s DLSS, Reflex and Streamline libraries and AMD’s FSR 3 frame generation, for Windows | Large, and changes only with a new NVIDIA or AMD release |
VSPT: Runtime (Linux) (vsptruntimelinux) |
NVIDIA’s DLSS for Linux | Linux only. With the Windows libraries in the same zip it would be over the Mod DB’s size limit |
Keeping them separate means a fix to the mod doesn’t make you download over 100 MB of unchanged files again.
Does it work in multiplayer?
Section titled “Does it work in multiplayer?”Yes. VSPT runs only on your computer: a server needs none of it, and you can join servers that don’t have it. Other players are traced, including those drawn by PlayerModelLib. The one exception is far terrain, which works in single player only for now.
How can I support VSPT?
Section titled “How can I support VSPT?”Through Patreon. Bug reports with logs, screenshots and suggestions help too.
Patrons also get VSPT: Builders Pack, a content pack of blocks, overlays and props made to look their best under path tracing.
Installing and updating
Section titled “Installing and updating”How do I install it?
Section titled “How do I install it?”- Install VSPT: Path Tracing from the Mod DB, with the 1-click button or by
putting the zip in your
Modsfolder. - Start the game and open any world. Setup is offered in a world, not at the main menu.
- Press Set up and restart. The game saves and closes, setup downloads VSPT: Materials and the runtime, patches the game’s engine (backing up the original), and starts the game again.
- The first world compiles the path tracing shaders, which can take a minute or more (below).
The settings are under Settings → Path Tracing. If the game is installed under Program Files, setup may need administrator rights.
What does setup change, and how do I undo it?
Section titled “What does setup change, and how do I undo it?”Setup patches one file, the game’s own VintagestoryLib.dll, so that the renderer can reach the world. It patches only
the 1.22.7 builds it recognises, and backs up the original first. A patched game with VSPT disabled or removed plays
exactly as vanilla.
To undo it, open Settings → Path Tracing → Advanced and press Remove VSPT: the original engine goes back and the game restarts. The mods stay installed but do nothing until you remove them in the Mods screen. The game’s own repair, or a reinstall, also puts the original back.
How do I update?
Section titled “How do I update?”At the first main menu after the game starts, VSPT asks the Mod DB whether newer versions are out and offers Update and restart. Not now asks again at the next start. Check for updates on the Advanced page turns the check off.
Some updates change how VSPT hooks into the game. The main menu then asks to patch the game again: press Fix and restart. You can also update from the Mod DB by hand; anything that is then missing or too old is offered the same way.
Does it work with launchers?
Section titled “Does it work with launchers?”| Launcher | |
|---|---|
The game’s own Vintagestory.exe |
Yes |
| MVL | Yes. Setup patches the game folder MVL runs, then asks you to start the game again from MVL. Every modpack on that game folder then runs the patched engine, which plays as vanilla where VSPT isn’t installed |
| Steam, as a non-Steam game | Yes. The Steam overlay shows in worlds but not at the main menu (#15) |
| Optimum | No (below) |
| Flatpak, AUR or Nix on Linux | No: their game folder can’t be written (below) |
The CurseForge app brings Overwolf with it, whose overlay can cause a black screen (below).
Why does the first world take so long to load?
Section titled “Why does the first world take so long to load?”After installing or updating, the first world builds VSPT’s shaders (“Compiling the path tracing shaders” on the loading screen), and the graphics driver keeps them in its shader cache. That can take a minute or more; let it finish. In single player the world waits, paused, so nothing can attack you meanwhile (#62). Changing a setting can also build new shaders in the background, up to about 20 seconds the first time.
If it compiles from scratch on every start, the driver’s cache is being cleared or is too small. In NVIDIA Control Panel → Manage 3D settings, set Shader Cache Size to Unlimited (or 100 GB), and keep disk cleaners such as CCleaner away from it.
Performance
Section titled “Performance”What frame rate can I expect, and how do I make it faster?
Section titled “What frame rate can I expect, and how do I make it faster?”VSPT is limited by the graphics card, so the settings that matter are the ones that change how much is traced. The Mod DB page suggests an RTX 4060 or better as a starting point. On a smaller card, start from the Low or Medium preset.
| Setting | Where | What it does |
|---|---|---|
| Quality preset | Path Tracing → Quality | Has the most effect (see the next table). High is the default |
| DLSS mode | Path Tracing → Quality, Upscaling | Performance is the default. Ultra Performance traces the fewest pixels |
| Frame generation | Path Tracing → Quality, Upscaling | Adds generated frames between traced ones (below) |
| View distance | Graphics | Everything loaded is traced |
| Far terrain, Cloud distance, World curvature | Path Tracing → Quality, World | Off by default. Each costs something when on |
| Preset | Light bounces | Plants in bounced light | Fog | Caustics | Cloud quality |
|---|---|---|---|---|---|
| Low | 1 | What you see and its shadows | Off | Off | Low |
| Medium | 2 | Up to the first bounce | Off | Off | Low |
| High (default) | 3 | Every ray | On | On | Medium |
| Ultra | 4 | Every ray | On | On | High |
Alt+F3 shows the frame graphs. Press it again to add the charts, which include video memory.
My graphics card is fast, but the frame rate is low
Section titled “My graphics card is fast, but the frame rate is low”Check your display’s refresh rate first, in Windows Settings → System → Display → Advanced display. With frame generation on, Reflex holds the frames shown to the refresh rate. A 144 Hz monitor left at 60 Hz in Windows, with 2x frame generation, traces at most about 30 frames a second however fast the card is. The game’s FPS counter shows the traced frames, not the frames shown.
Under path tracing, Game frame rate on the Graphics tab takes the place of Max FPS and VSync. It runs the game on a steady beat at a multiple of your refresh rate, from 0.1x to 2x, with 1x the default. Below 1x it holds the traced view back too. On Linux the traced view also follows the game’s VSync setting.
If none of that explains it, the assistant can read your report zip and look for the usual causes.
Which frame generation should I use?
Section titled “Which frame generation should I use?”| Option | Cards |
|---|---|
| DLSS 2x | RTX 40 and 50 series |
| DLSS 3x and 4x (Multi Frame Generation) | RTX 50 series |
| AMD FSR 3 | Any RTX card, so the choice on the RTX 20 and 30 series |
Frame generation needs DLSS Ray Reconstruction or DLSS Super Resolution as the upscaler. If the game started with it off, turning it on takes effect at the next start. Reflex is on with it. Frame generation in menus (on by default) keeps it running while a menu, the inventory or chat is open; turn it off if menus look warped. Frame generation is Windows only for now (#35).
Distant chunks are missing, or the view distance shrinks by itself
Section titled “Distant chunks are missing, or the view distance shrinks by itself”That is VSPT managing memory. Your View distance setting is an upper limit: when video or system memory runs short, VSPT pulls in how far the server sends chunks, and lets it out again when there is room. Your setting is left alone. When the card is full, the farthest chunks leave the picture first, never those near you.
On 8 to 12 GB cards a lower view distance avoids it. With far terrain on, Near and far terrain sets how much of the room the far terrain may take.
Caves and nights are very dark. Is that a bug?
Section titled “Caves and nights are very dark. Is that a bug?”No. Light comes from real light sources: the sun, the sky, the moon, torches, lanterns, lava and fire. A cave with no light in it is dark, as it would be, and the view adapts to the dark over a second or so, as your eyes do. Carry a torch or lantern, place lamps, or let daylight in through windows and openings.
Candles are dim beside a torch, as they are in life (#57). Lamp brightness (Path Tracing → Materials, 50 to 800%) scales what every lamp gives off if you want more. Leave auto exposure on: the lighting is balanced for it.
VSPT changes only what you see. The game’s own light levels, which decide what spawns and what grows, are untouched.
Two things are bugs, though. If a big cave is lit like daylight from its far end, turn on Dark caves at the view distance (Path Tracing → Quality, World; #23). If a lamp gives no light at all, report it with logs.
How do I get HDR?
Section titled “How do I get HDR?”On Windows, turn on HDR for the display in Windows (Settings → System → Display). VSPT then outputs HDR by itself: HDR output on the Picture page is Auto by default. It gives HDR only where Windows HDR is on for that display, because an HDR picture shown on an SDR display loses its highlights.
The peak brightness and Paper white are read from the display by default. Set your own if highlights clip or the picture looks dim. UI white sets the interface’s brightness on its own. Off (SDR) forces an SDR picture.
On Linux, HDR works on a Wayland session whose desktop has HDR on (KDE Plasma 6, for one), the main menu included. Under X11 the picture is SDR.
The picture doesn’t look like vanilla. Can I change the look?
Section titled “The picture doesn’t look like vanilla. Can I change the look?”Yes, on the Picture page:
| Setting | What it does |
|---|---|
| Tone mapping → Curve | Standard (the default), GT7, Filmic or AgX |
| Vanilla look | Gives back the game art’s saturation and contrast. 30% by default; 100% is tuned against the game without path tracing |
| Reduce harshness | Softens the contrast between sunlit and shaded surfaces, with the Standard curve. 100% by default |
| Highlight whitening | How far the brightest highlights go towards white |
| Exposure | Brighter or darker overall, from -3 to +3 stops |
| Auto exposure | How strongly and how fast the view adapts, and how dark or bright it may go |
Each section has a Reset button that puts it back to its defaults.
Surfaces look too shiny, or torches too red
Section titled “Surfaces look too shiny, or torches too red”Both are on the Materials page. Shine has a slider for each kind of surface: soil and sand, plants and leaves, wood, stone and brick, and everything else. The first four are at 25% by default (#11). 0% is matte, and metal keeps its shine whatever the sliders say.
Light colour sets the colour of torches, lanterns, oil lamps, candles and fire as a colour temperature, from 1,000 to 6,500 K. All the way left is each lamp’s own colour.
Which other settings are worth knowing?
Section titled “Which other settings are worth knowing?”| Setting | Where | What it does |
|---|---|---|
| See-through and Time of day | Beside the page tabs, in a world | Show the world behind the settings, and preview the sky at any hour of today while you change things. The world’s clock doesn’t change (#41) |
| Fog density | Path Tracing → Quality | Fog is traced, and the sun throws shafts through it. The default, 10%, is light: raise it for stronger shafts |
| Cloud quality, Cloud style | Path Tracing → Quality, World | With the game’s Clouds setting at Volumetric: how much of the clouds is worked out each frame, and Smooth or Crisp clouds |
| Cloud distance, World curvature | Path Tracing → Quality, World | Clouds out to the horizon, and far land bending down towards it. Both off by default |
| Far terrain | Path Tracing → Quality, World | Land past the loaded chunks (below) |
| Sea blue | Path Tracing → Picture, Water | How blue the sea is, from the local climate’s colour to the open ocean’s (#18) |
| Shadows, Water steps | Path Tracing → Quality | Shadows and water in the game’s pixel style |
| Whole-view effects | Path Tracing → Picture | How strong bent space, rust, drunkenness, mushrooms, cold and damage look |
| VSPT mouse input | The game’s Mouse tab | Smoother turning, read straight from the mouse. On by default; you may want a slightly lower sensitivity. Windows only |
| Photo mode | F12 | Frames a still with depth of field. The game’s own screenshot moves to Shift+F12 |
Other mods
Section titled “Other mods”Does it work with my other mods?
Section titled “Does it work with my other mods?”Most mods work, because VSPT traces whatever the game draws as blocks, items, creatures and players, modded or not. Mods that draw with shaders of their own may not show. These have been checked:
| Mod | State |
|---|---|
| Combat Overhaul | Works: hits land, and bows and slings are traced as it animates them |
| Spyglass and other zoom mods | Work |
| LibGUI and Scribe | Work: their windows show over the picture |
| PlayerModelLib | Works: you and other players are traced |
| Dense Ground Storage, GlassView and other mods that draw outlines or grids | Work |
| XSkills (Luminiferous) | Works: the skill lights the world round you |
| Salty’s Immersive Lanterns | Works: swinging lanterns give light |
| Place On Slabs | Works. The flames floating over candles and oil lamps on slabs come from the mod itself |
| Conquest VS Edition | Works: its lanterns give light |
| Finder | Works |
| FrameForge TSR | Not needed: its upscaling works on the game’s own picture, which VSPT replaces. VSPT offers to disable it at the main menu |
| Attribute Rendering Library before 3.1.4 | Crashes, often while the handbook loads, with the crash blamed on it, on Farseer or on the game itself (NullReferenceException in FrameProfilerUtil.Enter). Update it from the Mod DB: 3.1.4 removed the calls that crash |
| Optimum | Not supported (below) |
| Ghost Chunks, Farseer and other LOD mods | Their distant land doesn’t show (#24) |
| Chiseled World | Trees, sand and gravel are missing (#68) |
| Salty’s Tool Belt, Modular Backpacks, Walking Stick | Lanterns and lamps carried with them give no light yet (#19) |
| Real Smoke, Seamarks | Support requested (#70, #58) |
If a mod looks wrong, report it with a report zip and the mod’s name.
Do blocks and items from other mods get materials?
Section titled “Do blocks and items from other mods get materials?”Yes. A texture with no material of its own gets one worked out from what the game knows about it, so modded blocks
look right without anything extra. Mod and texture pack authors can add relief, shine, metal and glow with normal maps,
surface maps and small rule files in their own mod. The files do nothing without VSPT, so a mod needs no dependency on
VSPT, and shouldn’t add one. In a world, .vspt materials in chat lists any problems with the material files VSPT
read.
The guides for modders on this site explain the format and the material kit.
Does it work with Optimum?
Section titled “Does it work with Optimum?”No, and it is not planned for now (#17). Optimum runs its own rebuilt copy of the game’s engine, and both change the same parts of it, so they can’t share one. Since 0.2.6, setup recognises an Optimum install and leaves it alone. If an older version left Optimum stuck on its loading wheel, a game reinstall or Optimum’s own repair puts the engine back. To use VSPT, play from a normal Vintage Story install; Optimum can stay in its own folder.
Can I see land past the view distance?
Section titled “Can I see land past the view distance?”Yes, with VSPT’s own Far terrain (Path Tracing → Quality, World; off by default). It draws the land past the loaded chunks from Algernon’s Terrain Sampler, which you install as well. Far terrain distance goes from 512 to 8,192 blocks. It works in single player only for now.
LOD mods such as Ghost Chunks draw their distant land with shaders of their own, which the traced view can’t pick up. Reading their terrain is planned for later (#24).
Can I look at VSPT’s code to make my mod compatible?
Section titled “Can I look at VSPT’s code to make my mod compatible?”VSPT is closed source for now, and making it source available is planned (#61). Until then, decompiling VSPT to add compatibility is fine. Distributing forks of VSPT, or using it commercially, is not. Compatibility questions are welcome in the Discord channel or as an issue.
Does it run on Linux?
Section titled “Does it run on Linux?”Yes, since 0.3.0. Setup works as on Windows: install VSPT: Path Tracing, open a world and press Set up and restart. Setup downloads VSPT: Materials and VSPT: Runtime (Linux), and a desktop notification says what is happening while the game is closed.
| Graphics card | An NVIDIA RTX card with NVIDIA’s own driver |
| The game | Its own Linux download from your account (the .tar.gz and its install.sh), with the .NET 10 runtime from your distribution |
| HDR | On a Wayland session whose desktop has HDR on (KDE Plasma 6, for one). SDR under X11 |
| Not yet | Frame generation (#35) and VSPT mouse input, greyed out in the settings |
| VSync | The traced view follows the game’s VSync setting |
The Linux build needs glibc 2.38 or newer, so it doesn’t run on Ubuntu 22.04 or Debian 12.
Under Wayland, one player found the cursor wasn’t held by the game window with path tracing on, and played through Gamescope instead (#69).
Setup says it can’t set up on my Linux install
Section titled “Setup says it can’t set up on my Linux install”Setup patches the game’s engine file in the game folder, so it needs a folder you can write, and only the game’s own
download gives you one. The Flatpak’s folder is read-only, the AUR package’s /opt/vintagestory belongs to root, and
the Nix store is read-only (#67). To switch:
- Get the Linux
.tar.gzfrom your account on vintagestory.at, unpack it and run./install.shfrom its folder. - Install the .NET 10 runtime from your distribution’s packages if you don’t have it. The AUR package has already installed it.
- Your worlds and mods in
~/.config/VintagestoryDatacarry over. Coming from the Flatpak, first copy~/.var/app/at.vintagestory.VintageStory/config/VintagestoryDatato~/.config/VintagestoryData. - Start the game from the new install, open a world and press Set up and restart.
AMD and other graphics cards
Section titled “AMD and other graphics cards”Does it work on AMD Radeon cards?
Section titled “Does it work on AMD Radeon cards?”Not in any released version. Setup says the card isn’t supported, and changes nothing.
Work has started on a second way to clean up and upscale the picture, with NVIDIA’s NRD denoiser and AMD’s FSR 3.1, so that Radeon RX 6000 and newer cards can run VSPT: on Windows first, then on Linux. It needs players with AMD cards to test it. If you have one, say so in the Discord channel. There is no date yet.
What about GTX, Intel Arc, Macs and laptops?
Section titled “What about GTX, Intel Arc, Macs and laptops?”| GTX cards | Not supported: VSPT needs an RTX card |
| Intel Arc | Not supported |
| macOS | Not supported: there is no hardware ray tracing through Vulkan there |
| Laptops with an RTX card | Supported. Make sure the game runs on the NVIDIA card, not the built-in graphics: in Windows Settings → System → Display → Graphics, set Vintagestory.exe to High performance, and in NVIDIA Control Panel → Manage 3D settings → Program settings, choose the high-performance NVIDIA processor for it (#1) |
Problems
Section titled “Problems”I get a black screen
Section titled “I get a black screen”Work through these in order:
- Check the window mode. Use Windowed or Borderless fullscreen (Settings → Graphics → Window mode), because exclusive fullscreen can’t show the traced picture.
- On the first start after an install or update, the shaders may still be compiling (above). Wait for them before leaving the world.
- Check for Overwolf. It comes with the CurseForge app, so you may have it without knowing. Turn off its in-game overlay for Vintage Story in Overwolf’s settings, or quit it before you start the game (#12). The main menu warns you when it finds Overwolf in the game.
- Install the latest NVIDIA Game Ready driver.
If it is still black, type .vspt report in chat (it works on a black screen) and report it.
VSPT is installed, but the picture looks like the vanilla game
Section titled “VSPT is installed, but the picture looks like the vanilla game”| What you see | What to do |
|---|---|
| A chat line says VSPT is installed but not set up | Type .vspt setup in chat |
| The loading screen counts the shaders, then the world looks vanilla and the settings do nothing | Usually a driver too old for DLSS: install the latest Game Ready driver. In client-main.log it shows as NGX create feature failed 0xbad0000c. That code means the driver is out of date, not that memory ran out (#47) |
| You are on a laptop | The game may be running on the built-in graphics (above) |
| You started through Optimum, or the game isn’t 1.22.7 | VSPT says why once in chat and stays off |
| Path tracing is switched off | Settings → Path Tracing → Quality → Path tracing |
The game crashes or freezes
Section titled “The game crashes or freezes”Make a report zip after it happens (below): the logs of the session that crashed go in it. Since 0.3.0, a single player world is saved before the game exits after a crash. Known cases:
| Case | What helps |
|---|---|
| A crash as a world finishes loading, with Windows HDR on | Set HDR output to Off (SDR). Being looked into (#13) |
| A hard freeze that Task Manager can’t end, with frame generation on | Update the NVIDIA driver and turn off Frame generation in menus. If it still happens, try a session or two with frame generation off (#39). After restarting, attach any files in C:\Windows\LiveKernelReports from around the time of the freeze |
| A crash about a second after the game adds a page of block textures mid-game | A fix is being tested (#46) |
Is my problem already known?
Section titled “Is my problem already known?”These are open on the issue tracker:
| Problem | Issue |
|---|---|
| The item you are knapping or clay forming disappears at some angles | #71 |
| Small hot items put on the ground are invisible until they cool | #72 |
| WorldEdit selections and land claim boxes move the wrong way as you look up and down | #22 |
| Chiseled World’s trees, sand and gravel are missing | #68 |
| The Steam overlay doesn’t show at the main menu | #15 |
| On Linux under Wayland, the cursor isn’t held by the game window | #69 |
| An occasional crash after new block textures are added mid-game | #46 |
| A hard freeze with frame generation on | #39 |
If yours is there, add to that issue rather than opening a new one.
How do I report a bug?
Section titled “How do I report a bug?”- In the game, open Settings → Path Tracing → Advanced and press Package logs for a bug report, or type
.vspt reportin chat. The chat command works even on a black screen and before setup. It writesvspt-report-<date>.zipto thevspt/reportsfolder in your data folder, and Explorer opens with it selected (on Linux, its folder opens). - Open a bug report, say what happened and how to make it happen, and drag the zip in.
If the game won’t start at all, zip the Logs folder from your data folder instead: %appdata%\VintagestoryData\Logs
on Windows, ~/.config/VintagestoryData/Logs on Linux, unless you moved it.
The zip holds the game’s logs, your VSPT settings, a short summary of your PC (graphics card, driver, memory) and a few of the game’s graphics settings. Your Windows user name is taken out, and your game login is never in it. Your in-game player name can appear in the logs.
If you’re not sure what is wrong, the assistant can read your report zip and check the usual causes (refresh rate, window mode, driver, Optimum, other mods). It can also draft a bug report for you to check and submit from your own GitHub account. Its page says what it keeps.
Where can I ask questions or suggest something?
Section titled “Where can I ask questions or suggest something?”Ask questions and share screenshots in the VSPT channel on the official Vintage Story Discord. If the link doesn’t open, join the Discord first.
Send suggestions through the suggestion form. Screenshots help, especially one that shows how you expected it to look. The roadmap shows what is already planned.
VSPT is machine translated into all 32 of the game’s other languages. If a translation is wrong, open an issue with the language, the English text and a better wording.