steam deck Vintage Story on Steam Deck

[mard]

This thread explains how to install, configure, play, mod and update Vintage Story on Steam Deck. Please read carefully, especially if you enjoy playing with mods.

Latest major changes:

• Feb 8, 2025: Added a guide for synchronizing worlds between devices.
• May 14, 2024: Updated the guide for Vintage Story 1.19.7 and fresh SteamOS 3.5.19 installation. Updated most of the screenshots, added more information about accessing the community layout, mesa_glthread fix is not mandatory anymore, added a font cache fix for Asian languages and some more.
• Jan 3, 2024: Added additional explanation regarding downgrading to earlier Vintage Story version, proofed the command when the test version was already installed.
• Aug 11, 2023: Added additional screenshots, --env=mesa_glthread=false elevated to recommended setting, added some clarifications in some sections

 

Introduction

Video game company Valve recently came up with an affordable PC Linux handheld device called Steam Deck. I received mine a while ago, and of course being a fan of the game I installed Vintage Story on it. Vintage Story is not on Steam, but it is a Linux game and it works nicely on Steam Deck as a non-steam game.

Just to be clear, I don't really intend to advertise anything here. I thought if you come here from the search engine, I'll show you how to install and use it on this particular form factor and share my experiences.

 

 

Demo clips

My apologies for poor quality, it's a 1080p webcam but struggling to focus from up close. However most details should be visible.

Clumsy but getting hang of it.

 

Performance overlay in multiplayer game.

 

Installing on SteamOS

Thanks to the Linux Flatpak package available for Vintage Story, installation and updating the game is very easy. The whole process should take no more than a few minutes.

There are some caveats with this flatpak method, I'll explain them later. However, this is the most simple and most convenient way to get Vintage Story running on Steam Deck.

1. Press STEAM button, choose Power then choose Switch to Desktop.
   
   
   
   
   
   
   
   
    
2. You will be in desktop mode. Use the right touchpad to move the mouse, and press it to left click. Alternatively you can use the touch screen.
3. Click the Start Menu. From the System category, click Discover application.
   
   
   
   
    
4. Click the search box in top left, and press STEAM + X to pull up the virtual keyboard. Type Vintage Story, press RT to Enter, then press the button labeled Move to hide the keyboard.
   
   
   
   
    
5. From the list on the right, choose Vintage Story item. Press the Install button to download and install it.
   After a few moments, it should be complete. Be patient, it can hang on 99% for a minute or two.
   
   
   
   
   
   
    
6. Click the Start Menu. From the Games category, right click (press left touchpad) Vintage Story entry and select Add to Steam. Steam Desktop UI dialog window should show up.
   
   
    
7. That's it. You can see that the game should be now be present in your Steam library
   
   
   
   
   
   If something doesn't work correctly, add the non-steam game manually: click Browse and navigate to /var/lib/flatpak/exports/share/applications and open at.vintagestory.VintageStory.desktop. Press Add Selected Programs.
    
8. (Optional) You can use SteamGridDB plugin for Decky Loader to set the game thumbnail directly from Steam Deck's standard user interface.
   Alternatively you can use SteamGrid utility to download and set a matching library thumbnail from SteamGridDB for the game. Refer to its instructions on how to use it, you'll need to generate a SteamGridDB API key.
    
9. You can now go back to Gaming Mode by logging out or double tapping the icon on the desktop.

That's it! Access your Library and navigate to Non-Steam tab.

 

Before you launch

Download a community layout named Vintage Story [Mark 1]. You can always make your own, but this one has an important workaround for mouse wheel registering two scrolls instead of one. It employs a method of cycling through keyboard digits to effectively select items on the hotbar.

Click the controller settings button.

Now click the central button to enter the layout browser.

Navigate to Community Layouts.

Make sure to enable the option Show All Layouts when you switch to Community Layouts tab!

Now find the Vintage Story [Mark 1] layout, press A to select it.

After a short download, you will be shown the downloaded layout. Press X to apply it.

Done, you can now go back to the game item in your library.

When all else fails, you can access this link on desktop mode: (I can't make a link here because forum software prevents me to create working steam:// links)

steam://controllerconfig/2485963017/3246456598

The most reliable way to open it: go to the desktop mode, open Konsole app and type

xdo-open steam://controllerconfig/2485963017/3246456598

The Steam window should open up and you should now be able to apply the layout manually.

 

Launch and configuration

Launch the game. You will be presented a login screen - Press STEAM+X buttons to manually bring up virtual keyboard, you can type your password from there.

For starters, I recommend using Medium preset with Fullscreen and VSync enabled. You can always experiment with higher settings later. However, one user reported that choosing the wrong combination of options may cause the game to get stuck during loading, and you'll need to reset the settings game file manually (more on this later)

If experience any issues with changing or navigating settings, read the troubleshooting part with the --env=mesa_glthread=false launch option.

 

Controls

Here are controls for the game as mapped in the community controller layout Vintage Story [Mark 1], working with the default control configuration inside the game.

Same as above, but in text form:

• Right touchpad or Right joystick - Mouse
• R2 or press right touchpad, or press right joystick - Left mouse button
• L2 - Right mouse button
• Left touchpad vertical swipe - Mouse wheel
• Left joystick - WASD (Walk)
• A - Space (Jump)
• B - Escape (Menu, closing windows)
• Y - C (Character sheet)
• X - E (Inventory)
• R1, L2 - cycle though 0-9 keyboard keys (Change hotbar items)
• L4 - Ctrl (Sprint)
• R4 - Shift (Sneak)
• L5 - Left Alt (Lock/Unlock mouse cursor)
• View - M (Map)
• View Long Press - F6 (Show/Hide Minimap)
• Menu - H (Survival Guide)
• Menu Long Press - J (Journal)
• D-Pad Up - Q (Drop one item)
• D-Pad Up Long Press - Ctrl+Q (Drop all items)
• D-Pad Right - X (Flip left/right hand contents)
• D-Pad Right Long Press - F (Select Tool Mode)
• D-Pad Down - G (Sit)
• D-Pad Down Long Press - F5 (Switch camera mode)
• D-Pad Left - Tab (Show/Hide chat dialog)
• D-Pad Left Long Press - T (Type in chat)

You can modify it to tailor it to your preferences. You can also enable gyroscope mouse aiming in Steam controller settings if you desire. Just remember that if you want to share your scheme, avoid changing default in-game controls.

 

Installing Mods

In Desktop mode, open the Dolphin file manager, in the top right corner of the window press the hamburger menu icon and choose Show hidden files. (see screenshots below)

From your Home location, navigate to .var/app/at.vintagestory.VintageStory/config/VintagestoryData/Mods.

You shall place any mod files here.

 

What about Mod DB 1-click install button?

As of version 1.18.3 - Linux, including SteamOS, is not supported. It could be implemented for Flatpak package and make it work in SteamOS Desktop Mode, but currently vintagestorymodinstall URI schema prevents it from working with XDG. Details in this thread.

 

Known Problems & Troubleshooting

 Help! Game window is too small, unable to close the game or access game Settings

You can safely skip this section if this didn't happen to you.

However, sometimes, when you run the game for the first time, the game window might be set to its minimum possible size, making accessing the Options menu impossible.

To fix this, close the game using Steam overlay (Press Steam, navigate to Exit game, if game fails to close properly, confirm by pressing B button)

In Desktop mode, open the Dolphin file manager, in the top right corner of the window press the hamburger menu icon and choose Show hidden files.

From your Home location, navigate to .var/app/at.vintagestory.VintageStory/config/VintagestoryData.

Find the file clientsettings.json. You have two options now.

1. You can simply remove it using the file manager. "Right" click it, or select it and choose the delete option. Then go back to the gaming mode. The file will regenerate and you'll start the game with all game settings reset, you will need to login again.

2. Alternatively, if you don't want to lose all your settings, double click it to open it with the text editor Kate.

Find the lines containing screenWidth and screenHeight. Edit the values in them so it'll look like this:

"screenWidth": 1280,
"screenHeight": 800,

Save the file and go back to gaming mode.

 

Issues with missing non-English characters

Steam, for some reason, automatically sets LC_ALL environment variable to... C. This leads to font rendering problems for some non-ANSI characters.

To force override Steam's setting of that environment variable, you have to modify the game's launch parameters in game's properties. Add the following to parameters list:

--env=LC_ALL=

The full line should look like this:

run --env=LC_ALL= --branch=stable --arch=x86_64 --command=vintagestory at.vintagestory.VintageStory

To combine it with a LD_PRELOAD fix from section described later, you can do it like this:

run --env=LD_PRELOAD= --env=LC_ALL= --branch=stable --arch=x86_64 --command=vintagestory at.vintagestory.VintageStory

 

Fixing Asian characters

When you change the language to any Asian language in game settings, you can see that the game's fonts are missing.

 

This is of course, not desirable. First, we need to change LC_ALL environment variable to let the game know we want to see Asian characters.

For Japanese language , please use

--env=LC_ALL=ja_JP.UTF-8

Change of locale will force the game to use the font that contains Japanese characters.

In the menu, select Properties, then

It's the same for Korean language , this should also work:

--env=LC_ALL=ko_KR.UTF-8

This applies to other Asian languages, zh_CN.UTF-8 for Simplified Chinese, th_TH.UTF-8 for Thai and so on.

After you re-launch the game, you will see the font situation significantly improved, but there are still some missing fonts.

In order for fonts to run correctly, you'll need to refresh the font cache for Vintage Story flatpak.
Go to the Desktop Mode and launch the Konsole app.

You will need to type the following:

flatpak run --command=fc-cache at.vintagestory.VintageStory -f

Press Enter, it should finish after a couple of seconds without any errors.

Now when you go back to the game, you can enjoy beautiful Asian fonts, here's an example for Japanese language.

This will also fix the fonts on ingame signs. However, not all characters are visible.

 

 Fixing issues with mods / some modded servers

I've noticed that some servers still fail to join, when the game is run using Steam as a non-steam game (either through desktop Steam, or SteamOS gaming mode etc.).

You will need to force the game to exit from Steam UI.

This is because Steam is overriding LD_PRELOAD environmental variable on game launch. Steam sets LD_PRELOAD containing a path to a Linux .so library that is Steam related. I suspect that this confuses Vintage Story, it tries to interpret the .so library as a mod and/or .NET assembly. However, I don't know why it affects only some servers, not all of them.

Anyway, I was able to workaround this, by adding the following parameter to the game's launch parameters in game's properties. This will ensure that the LD_PRELOAD environment variable set by Steam is reset:

--env=LD_PRELOAD=

The full line should look like this:

run --env=LD_PRELOAD= --branch=stable --arch=x86_64 --command=vintagestory at.vintagestory.VintageStory

 

Other miscellaneous problems

If you experience weird graphical problems or crashes, try adding --env=mesa_glthread=false to the game's launch options, as shown below. This will instruct the flatpak not to utilize OpenGL threading, which has been enabled by default for some time. In previous versions, leaving threading enabled was reported to cause substantial issues, including freezing, mouse not working and resolution detection. These long standing issues seem to be fixed in most recent versions but you can still try it if the game misbehaves.

 

Updating and Downgrading

Updating the game (the easy way)

Vintage Story Flatpak is updated by its current maintainer. Keep in mind that the Flatpak maintainers are volunteers for open-source community, and certainly not affiliated with Anego Studios in any way.

Once the new version of Vintage Story releases, the maintainer needs to manually push the release into the stable branch, only then Vintage Story will be available to update.

To update Vintage Story to the most recently published stable version, you'll need to go back to Discover app in the Desktop Mode, go to the Updates section and click the Update button. That's it, nothing else is required.

 

For advanced users: Updating (installing automatically built Flatpaks that not yet published as stable)

I don't recommend going this path, because it's cumbersome and requires the use of the command line. But if you really need it, here's how it can be done.

Sometimes, maintainers don't keep Vintage Story Flatpak package up to date. Because this process is manual, it can take hours or days for them to update. However, there's a way to install and use the most recent Vintage Story version right away. An automated integration system keeps an eye for new Vintage Story releases and builds flatpaks automatically. Before they get confirmed by the maintainer, they're marked as test branch releases.

Now, because "Discover" app offers only basic functionality, you will need to use the command line to install it. Don't worry, the process is easy but not quite ergonomic

So, let's do this. First, you need to set up an account password to be able to use the sudo command.

Then, go to flathub's Vintage Story pull requests and click the version you need. For example, the pull request associated to v1.18.1 update.

Scroll down to the latest comment on the bottom, you will find an example command to install it. Because we need to install the pack for the system just like other flatpaks, you'll need to modify it as follows:

• delete --user parameter
• add sudo command on the beginning:

It should look like this:

sudo flatpak install https://dl.flathub.org/build-repo/19441/at.vintagestory.VintageStory.flatpakref

Type the command into Konsole application, then press Enter. Confirm any subsequent prompts with Y, then press Enter for each of them.

You should see  "Changes complete" in the command line. If you get the error "branch test is already installed", scroll down to the next section and go back here again.

If you see a warning about "not exporting at.vintagestory.vintagestory.appdata.xml of unsupported type", you can safely ignore it.

After successful installation, you can verify it with sudo flatpak list command. It should look like this:

$ sudo flatpak list

Name             Application ID                  Version    Branch    Origin
(...)
Vintage Story    at.vintagestory.VintageStory    1.17.9     stable    flathub
Vintage Story    at.vintagestory.VintageStory    1.18.1     test      vintagestory-origin
(...)

As you can see, both old stable and new stable (test, from the Flatpak's viewpoint) are installed alongside each other.

Now you may notice, that running the game from Steam will still launch the old stable version, instead of newly installed test version. To fix this, you need to go to your Library, find Properties of Vintage Story entry, then find Launch Options. Find the following parameter:

--branch=stable

then, replace it with

--branch=test

That's it! When you run Vintage Story now, it should be the version you've just installed.

Important: Remember to replace test with stable again if you want to go back using the official version you installed from the Discover app.

 

Solving "branch test is already installed" error

Just uninstall the previous test release first. Type

sudo flatpak uninstall at.vintagestory.VintageStory

And from interactive prompt, type the number and Enter for the test package you want to uninstall. You can now proceed with installing the most recent test version again.

(and no, adding --reinstall parameter to the first command won't help because it's ignored so you still need to uninstall manually)

 

Downgrading

Downgrading to older versions is also doable. You just need to set up an account password to be able to use "sudo" command and then type two first commands from the Downgrading section from Flatpak Tips and Tricks page, as such:

flatpak remote-info --log flathub at.vintagestory.VintageStory
sudo flatpak update --commit=<paste-full-commit-hash-here> at.vintagestory.VintageStory/x86_64/stable

For example:

(deck@steamdeck ~)$ flatpak remote-info --log flathub at.vintagestory.VintageStory
(...)
   Commit: 1ca8ec3978821ccd69ca558d0c7d1e5f43af91fe461e6878a4274e3a174f2edc  
  Subject: Add 1.18.1 release description (45a2a801)  
     Date: 2023-04-27 04:38:48 +0000  
  
   Commit: 448497e8b642214fec1b3e3ff930efd37306d0025ed059c55da8b64e0c10895e  
  Subject: Add 1.17.11 release description (d4e9a452)  
     Date: 2023-02-09 00:37:52 +0000
(...)
(deck@steamdeck ~)$ sudo flatpak update --commit=1ca8ec3978821ccd69ca558d0c7d1e5f43af91fe461e6878a4274e3a174f2edc at.vintagestory.VintageStory/x86_64/stable

 

 

What about installing Vintage Story natively instead of using the flatpak?

I think there are some ways to achieve this, especially now that the game uses .NET 7. but for now Flatpak method is the casual, quickest and most convenient way to get the game running.

 

Playing in desktop mode

Sure, but launch the game from desktop mode Steam library, if possible.

The reason for that is you still need these --env launch options you've set on Steam - the easiest way is just use Steam to launch the game for consistency.

 

Synchronizing Worlds

Vintage Story is not a Steam game and doesn't use Steam Cloud, so you'll need a custom "cloud" solution in order to synchronize your worlds between devices.

See the post linked below for details:

https://www.vintagestory.at/forums/topic/8147-vintage-story-on-steam-deck/?page=3#findComment-54781

Thanks @Connor Black for your contribution.

Closing thoughts

After many months of playtesting, I think these are the most common problems with using Vintage Story Flatpak:

• Need to wait for package maintainer to make new versions available. It usually takes a couple of days
• If you don't want to wait, downgrading or upgrading to cutting edge versions is more complicated and must be done from the command line. (but you can install FlatpakUpdater for Decky Loader to update your flatpaks from gaming mode)

Otherwise, the game is perfectly playable. Vintage Story works and plays nice on Steam Deck if with the proper controller mapping.

If you use Discord to voice chat, you can also install it the same way as a Flatpak, add it to Steam and switch between VS and Discord using Steam Deck's UI. You can also map Push-To-Talk key if you need it.

That's it! Let me know what you think.

Also, my first post on this forum. Thanks Tyron et al for this amazing game.

Edited February 8, 2025 by mard
fix typos, add missing screenshots, add controls section, add modding section, add mod issues section, expand the updating with flatpak details, elaborate closing thoughts, add workaround for fonts

[Epihnea]

Hey ! Many thanks for the feedback and the tutorial !!!

[Rhyagelle]

Great work on the very thorough tutorial and feedback! 

[radfast]

Great work @mard

And thank you also to the unsung heroes who made the FlatPak and the community controller layout

[Per Edman]

This worked like a charm. 

[Lucy Demoon]

1 question why flatpack and not from AUR? SteamOS3 is an Arch and without flatpak you can save much space than this flatpack monsters

[mard]

7 hours ago, Lucy Demoon said:

1 question why flatpack and not from AUR? SteamOS3 is an Arch and without flatpak you can save much space than this flatpack monsters

It's easy and convenient!

SteamOS3 is Arch, but its rootfs is immutable + read-only by default. It can be written into, but everything done there is sooner or later wiped by system update images. AUR version of Vintage Story package installs in rootfs, so if my understanding is correct, I would need to repeat the process of installing it every time after the system gets updated. It would make more sense to install mono and then install the game manually in home directory. And then there are solutions like this one.... , but, eh, it's just too much hassle either way.

As for the size argument - if we don't count those beefy shared libraries used by other flatpaks, Vintage Story only comes with a mono runtime library that weights around 80 MB. Less than a native package. So it's not that drastic overhead really.

[JohnMidnight]

I was just thinking of this, thanks for the write up here! 

[Jorhn]

It's so surreal to see Vintage Story on a device that looks like a console!

[TJ Bartlett]

I'm having an issue, I can't connect to modded servers. I tried installing the mods directly into the mod folder but that didn't work. When I try to connect l, it downloads the mods and when I join the game crashes. Any ideas what I can do to overcome this? 

[mard]

On 9/30/2022 at 10:53 PM, TJ Bartlett said:

I'm having an issue, I can't connect to modded servers. I tried installing the mods directly into the mod folder but that didn't work. When I try to connect l, it downloads the mods and when I join the game crashes. Any ideas what I can do to overcome this? 

These problems should be fixed by now. However, you may need a manual workaround, check the OP for up to date findings on this issue.

Edited May 4, 2023 by mard

[BigBadBeef]

If it runs on Linux, it will run on SteamOS... because it IS linux!

[Bobby Ragsdale]

Thanks for the guide.  I have one issue I cant solve no matter what input options I chose or via using the [Mark 1] community template.  How the heck do you use the right stick to turn the camera.  It does nothing so all I can do is WASD with the left stick.  Many thanks for any information

[HebiHydra]

Thank you so much for this lovely guide.

[Ruyeex]

It could theorically work playing with other consoles since it's quite flexible.

[itinerare]

It's worth noting that mono is used within wine and consequently proton, so the game boots just fine from the freestanding executable under proton as well. However, I've still been having some trouble with mods when running it through gaming mode...

[mard]

On 11/26/2022 at 3:33 AM, Bobby Ragsdale said:

How the heck do you use the right stick to turn the camera.

I recommend using the touchpad for looking around and controlling the mouse cursor. It's more precise and accurate, it behaves much like a laptop touchpad which you can press. Still, if you want to use the right stick, you should be able to edit the control layout for yourself. When you have the game launched, press Steam button, then Controller settings. Go to Edit Layout, select Joysticks, and set Right Joystick to behave As Mouse. There are sensitivity options to adjust for that as well.

 

On 12/28/2022 at 10:44 PM, itinerare said:

However, I've still been having some trouble with mods when running it through gaming mode...

These problems should be fixed by now. However, you may need a manual workaround, check the OP for up to date findings on this issue.

Edited May 4, 2023 by mard

[cpstoke]

I can get the game running, but for whatever reason the right joystick or trackpad will not look around in game, (it is set to joystick mouse and works perfectly in menus as a mouse input) I am on steam deck using the Mark 1 community controller input.

[Alcyonaria]

Love panning on the steamdeck, makes the tedious a lot less gross.

[KoopaSlayer]

Thanks I followed your steps and everything is working great even the controls. I did wonder is there a way to play my single player world that I have on my main pc on the steam deck so I can go back and forth between pc and steam deck? 

[Llama King]

Im having some issues getting vintage story to work on the steam deck.  Firstly where exactly do i download the mark 1 community template from and where is it installed to? Also i followed the other instructions but when trying to log in the keyboard is behind the login screen an isnt accessible so i cant input my email and password. Any help would be apricated. 

[mard]

On 4/1/2023 at 7:46 PM, Llama King said:

Firstly where exactly do i download the mark 1 community template from and where is it installed to?

It's easy. When you're in game, you can press STEAM button, then you go to Controller settings. then the big button just under the Current Layout caption. You should be able to see available controller layout on the list.

You can see how it looks like on this video.

On 4/1/2023 at 7:46 PM, Llama King said:

when trying to log in the keyboard is behind the login screen an isnt accessible

You can bring up the keyboard by pressing STEAM + X buttons at the same time.

[mard]

On 3/13/2023 at 5:53 AM, KoopaSlayer said:

I did wonder is there a way to play my single player world that I have on my main pc on the steam deck so I can go back and forth between pc and steam deck? 

Unfortunately, Vintage Story can't use Steam Cloud because it's not a steam game. So you need to find a way to synchronize your saves by yourself.

I never tried it yet, but I think it's possible. What you need is to automatically synchronize select files from Vintage Story data directory. If you use Windows on your main PC, you need to sync:

• C:\Users\YourUserName\AppData\Roaming\VintagestoryData\Saves on your PC
• /home/steamdeck/var/app/at.vintagestory.VintageStory/config/VintagestoryData/Saves on your Steam Deck.

How you do this, is up to you. There are many available solutions, you can try something like Syncthing, Dropbox or some other syncing software.

There are many videos online on this subject, for example: Syncthing can enable multi-device play for your favorite games. - YouTube

Good luck!

[zamtoid]

Anyone know when a 1.18 flatpak might be getting uploaded? I'm itching to play the new update but only have a steam deck currently to play on.

[mard]

20 hours ago, zamtoid said:

Anyone know when a 1.18 flatpak might be getting uploaded? I'm itching to play the new update but only have a steam deck currently to play on.

No idea, you need to contact the current flatpak package maintainer jascrain if you require this information.

However, if you don't want to wait, you can install v1.18 from flatpak's test branch by yourself.

Vintage Story 1.18 flatpak was already built and uploaded with continuous integration system: Update vs_archive.tar.gz to 1.18.0 by flathubbot · Pull Request #36 · flathub/at.vintagestory.VintageStory · GitHub. It's currently awaiting maintainer's manual intervention. As you can see, there's a command included that allows to install it.

Now, because "Discover" app offers only basic functionality, you will need to use the command line. Don't worry, the process is very easy, but not as ergonomic. It'll take a few minutes.

First you need to set up an account password to be able to use "sudo" command. Then, in Konsole application, type the following:

sudo flatpak install https://dl.flathub.org/build-repo/18664/at.vintagestory.VintageStory.flatpakref

Then confirm the interactive prompt with Y, then Enter. Be patient, installing will take a couple of minutes.

Doing so will install Vintage Story 1.18 test version from test branch alongside already existing stable version - this is reflected in installed flatpaks list:

sudo flatpak list

Now, you may notice, that running the game from Steam will launch the stable version, instead of newly installed test version. To fix this, you need to go to your Library, find Properties of Vintage Story entry, then find Launch Options. Find the following parameter:

--branch=stable

then replace it with

--branch=test

That's it! When you run Vintage Story now, it should be v1.18.0.

To return to regular stable mainline Vintage Story version, just replace --branch=test with --branch=stable again.

 

What about "branch test is already installed" error? Just uninstall the previous test release first. Type

sudo flatpak uninstall at.vintagestory.VintageStory

Then, in interactive prompt, type the number and Enter for the test package you want to uninstall.

Edit: I've also updated the OP with the information above.

Edited April 22, 2023 by mard