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:

• Aug 11, 2023: Added additional screenshots, --env=mesa_glthread=false elevated to recommended setting, added some clarifications in some sections.
• Jun 8, 2023: Added a section about fixing the issue with mouse click not working / resolution issues / game hanging other miscellaneous problems with graphics and input
• May 17, 2023: Added controls cheat sheet in Controls section
• May 16, 2023: Fix for missing non-English latin characters - details in Issues with missing non-English characters section
• May 4, 2023: Game is no longer crashing when joining modded servers, but requires an additional launch parameter. Details in Issues with mods section

 

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.
   
   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.
2. Click the Start Menu. From the System category, click Discover application.
   
   
   
3. 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 B to hide the keyboard.
4. 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.
   
5. 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.
   
6. Vintage Story item should be on the list, select it.
   If it's not on the list, click Browse and navigate to /var/lib/flatpak/exports/share/applications and open at.vintagestory.VintageStory.desktop. Press Add Selected Programs.
   
   
   
   1. (Optional) I recommend using 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.
7. Logout or click Return to Gaming Mode from the desktop.

That's it! Vintage Story should be in your Non-Steam category in your Steam library now. Here's how it looks like on my Deck UI, with a nice graphic imported from SteamGridDB.

 

Before you launch

1. 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.

 

 

2. Very important! Add --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. Leaving threading enabled was reported to cause substantial issues, including freezing, mouse not working and resolution detection.

I also recommend adding --env=LD_PRELOAD= --env=LC_ALL= for some other different reasons, it is explained later in the post.

 

 

 

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.

In the menu, choose Settings, select Quality Preset - Low. Enable Fullscreen and VSync, make sure that the God Rays setting is disabled. Also don't use FPS limiter in game options - use the one built into Steam Deck performance options.

I strongly recommend trying settings below for now. You can always experiment with higher settings later. One user reported that choosing the wrong combination of options may cause the game to get stuck during loading.

If you have issues changing or navigating settings, go back to "Before you launch" section, make sure you added the --env=mesa_glthread=false launch option.

 

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 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 the default settings. 

2. Alternatively, if you don't want to lose all your settings, open it with text editor of your choice (I recommend Kate or KWrite, if not already installed, you can find them in Discover app)

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.

 

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.

 

Modding

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/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.

 

Issues with mods / joining 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.).

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, related to Steam overlay. 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=mesa_glthread=false --env=LD_PRELOAD= --branch=stable --arch=x86_64 --command=vintagestory at.vintagestory.VintageStory

 

Issues with missing non-English characters

Running the game from steam sets LC_ALL environment variable to... C. We don't want that, because this leads to font rendering problems for 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=mesa_glthread=false --env=LC_ALL= --branch=stable --arch=x86_64 --command=vintagestory at.vintagestory.VintageStory

To combine it with a fix from section above, you can do it like this:

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

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.

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

--env=LC_ALL=ko_KR.UTF-8

 

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)

Sometimes, maintainers don't keep Vintage Story Flatpak package up to date. Because this process is manual, it can take hours, days or weeks 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 very easy, but not as ergonomic. It'll take a few minutes.

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-commit-id-here> at.vintagestory.VintageStory

 

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

It needs a lot of more tinkering, especially on an immutable system that is SteamOS. I think there are some ways to achieve this, 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.

 

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.
• You can only update the game from the desktop mode (but you can install FlatpakUpdater for Decky Loader to update your flatpaks from gaming mode)
• The game freezes during exit, but can be forced to be closed down manually with the B button.

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

Gameplay is stable. There's a slight frametime jitter but in my opinion, doesn't impact negatively on the overall experience. You can map all the essential controls you need.

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 seamlessly. 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 October 28 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 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

[SerpTheJester]

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 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 by mard