Skip to content

xStarbound v4.5.5.3: The UI Modding Update™ ... and crash fixes

Choose a tag to compare

View all tags
@FezzedOne FezzedOne released this 04 Oct 22:34
v4.5.5.3
6b6bb14

Before reporting issues with xStarbound, please scroll down (and click Read more if needed) and read any sections appropriate to your setup or issues.

🪟 Windows users: The MSVC build will be available shortly. Just want to get v4.5.5.3 released now because technical issues delayed the release for a day.

  • v4.5.5.2 [Crash Fix::Asset Loading] [@FezzedOne] Fixed a potential out-of-bounds memory access that could occur when loading .2functions asset files (like the one used for armour protection) that are malformed due to Y-axis row array with fewer than the two required elements (a Y-axis value, a number, and an array of as many point values, also numbers, as the first array value in the .2functions array grid. Also made asset loading errors for .functions, .2functions and .configfunctions asset files a lot less cryptic.

  • v4.5.5.2 [Bugfix::Mechanics] [@Bottinator22] Fixed a bug where the game wrongly assumed a given elemental type did not exist in the assets if a damage type of that name didn't exist in the assets, even if the elemental type existed (though it still correctly threw an exception for nonexistent elemental types).

  • Docs::v4.5.5.1r1 [Docs::lua.md] Fixed a typo and some unclear wording around xpcall usage.

  • v4.5.5.1 [Crash Fix::xClient::Lua/UI] [@FezzedOne] Fixed a crash that happens when a pane script deletes any items in a list widget during the invocation of the Lua callback for that widget, such that the newly selected item ends up out of bounds after the callback is run. With this fix, if that edge case happens, the selection is simply cleared. This crash was first reported by @GrayShip (Sergey on the Steam Workshop) and sometimes occurred when shift-clicking items out of Forgemaster's Inventory via the item icons. See GrayShip's OpenStarbound patch for the equivalent fix for OpenStarbound v0.1.15.1 (plus extra functionality to allow modded script panes to replace or substitute for the retail inventory pane).

  • v4.5.5.1 [Change::xClient] "allowAnyItemInBags" (under /player.config:inventory) now no longer allows items to automatically be picked up, spawned, etc., into bags not matching their filters, presenting less «available» inventory space for item pickup purposes, while still letting you (or a script using player.setItem) manually put items into any bag. This should avoid item pickup issues with mods (like Forgemaster's Inventory) that use hidden inventory bags internally (and avoid mass item pickups making a mess of your inventory) while keeping the actual intended behaviour of "allowAnyItemInBags" for players (and modders).

    For modders and hoarders: Enable "disableBagPreferences" via a patch to disable bag filter checks entirely and have item pickups just go into the first available bags with space in them (in order of configured priority).

  • [NEW::xClient::Lua/Pluto::pane/widget] [@KrashV] Added the following pane and widget bindings from OpenStarbound v0.1.15:

    • pane.anchor
    • pane.setAnchor
    • pane.anchorOffset
    • pane.setAnchorOffset
    • pane.getScreenPosition
    • pane.setScreenPosition
    • widget.clearListSelected
    • widget.getScrollOffset
    • widget.setScrollOffset
    • widget.getMaxScrollPosition

    See $docs/lua/scriptpane.md and $docs/lua/widget.md for more information.

  • [Bugfix::xClient::UI/Building] [@KrashV] Objects without a specified "placementImagePosition" offset in their parameters or asset config no longer kick the player to the main menu when visually held for placement. Instead, an offset of [0, 0] is now assumed in that case.

  • [Bugfix::xClient::Lua/Pluto::widget] [@FezzedOne] Fixed an inconsistency where a few widget bindings would throw a Lua dereference error when used (via «Lua smuggling») after the associated parent pane is destroyed while most other widget bindings didn't (instead doing nothing instead). Now all widget bindings do nothing when their associated parent pane no longer exists.

    Caution: Don't rely on this behaviour on non-xClient clients! Make sure to gate it behind an xsb or paneLoaded check if your mod is intended to work on OpenStarbound, retail, etc.

  • [Performance::xClient] [@Bottinator22] xClient now has an OpenStarbound optimisation where the client no longer internally creates a cloned item every time an item with associated blueprints is picked up, even when the blueprint is already known. The internally cloned item is now only created when a UI notification with its display name is displayed. This should help with any remaining lag from picking up items.

  • [Documentation::widget.md/directives.md] [@FezzedOne] Added missing documentation for text escape codes to $docs/directives/directives.md and fixed a formatting issue affecting the widget.setData entry in widgets.md. Curse you, auto-formatter! Also, the font=<font> and directives=<directives> operations are non-retail and only available on xStarbound, oSBM and OpenStarbound, but I forgot to mention that in the new documentation before release.

  • xSBCompat::v4.5.5 [Compatibility Bugfixes] [@FezzedOne] Fixed the following issues:

    • Persona Roleplay Suite: Fixed an issue that resulted in visually glitchy duplicate wheel interfaces when holding down the FastSelect key while multiple player characters are loaded.
    • Improved Inventory Stack Management: Fixed an oversight that prevented the patch from working as advertised when multiple players are loaded.
📂 Info on attached files

Attached files

The attached files contain the following:

  • docs.zip: Contains the full Lua API documentation for xStarbound v4.5.5.3, as well as documentation for xStarbound's build permissions system, JSON patch features and image directives.

  • linux.tar.gz: This contains (64-bit) dynamically linked Linux versions of xServer and xClient v4.5.5.3, as well as a required libsteam_api.so library, the required xsbinit.config file, a steam_appid.txt file required for Workshop support, and xclient.sh and xserver.sh scripts needed to start up xClient and xServer, respectively, without going through a launcher.

    If you use Fedora or an Arch-based distribution (not SteamOS!) and you have a CPU that supports x86-64-v4, you should download and use this release. NixOS users should use the Nix flake. Ensure you have GLEW installed through your distribution's package manager (glew on Arch/Fedora-based distros, libglew on Debian/Ubuntu/Mint and the like, media-libs/glew on Gentoo, etc.).

    On other distros, use the statically linked release below. Extract all files from the .tar.gz archive into a new ${starbound}/xsb-linux directory — on Steam installs, your Starbound install is usually in ~/.local/share/Steam/steamapps/common/Starbound/ — and optionally set up your Steam or other launcher to run xclient.sh instead of starbound or run_client.sh.

  • linux-static.tar.gz: This contains (64-bit) Linux versions of xServer and xClient v4.5.5.3 that have most of their dependencies statically linked in, as well as the required files mentioned above.

    Use this version if you use SteamOS or any «non-bleeding-edge» distribution — e.g., Zorin OS, Linux Mint, Ubuntu, Debian, CentOS, etc. — or your CPU is too old to support x86-64-v4, if you're running xServer in a container or on a server instance, or if you get a library versioning error when you try to run the standard dynamically linked version of xClient or xServer.

    If you don't use the provided launch script for xClient, check if the device /dev/dsp exists on your system. If not, launch xClient with padsp — this command goes after gamemoderun, prime-run, etc.

  • linux-utils.tar.gz: This contains Linux versions of xStarbound's asset_packer, asset_unpacker, make_versioned_json and dump_versioned_json, as well as a Linux-native mod_uploader and a mod_uploader.sh script to start up the mod_uploader. Drop these into the folder you put xclient and xserver in. The executables are statically linked, so they should run on any Linux system that isn't archaic.

    The mod_uploader requires Steam (obviously) with Starbound on your account; to use the mod_uploader, have Steam open, make sure you have Starbound's steam_appid.txt in the same folder, and then run the startup script (mod_uploader.sh, not the binary!) — there's no option to launch it directly from within Steam on Linux.

  • windows.zip, windows-msvc.zip and windows-msvc-pdbs.zip: This all-in-one ZIP archive contains everything needed to run xClient and xServer v4.5.5.3, including assets and Lua documentation (which will replace your stock docs!). Simply extract this into your Starbound directory to install xStarbound. The executables included in windows.zip are built with MinGW; note that joining and hosting P2P sessions via Steam and Discord are not supported by this build. For this reason, the MSVC / Visual Studio build, which does have P2P support (and significantly smaller binaries), is provided as windows-msvc.zip. The PDBs for the MSVC build are included in windows-msvc-pdbs.zip, which should be extracted into the new xStarbound install's xsb-win64\ after installing xStarbound. Make sure to install these PDBs when reproducing crashes or bugs for reports (so it's a good idea to have them installed anyway).

    • On Steam installs, your Starbound install is usually in C:\Windows\Program Files (x86)\Steam\steamapps\common\Starbound\. If that folder doesn't exist, try removing the (x86) (including the space before it). Normally, you will need to double-click xclient.exe to play with xStarbound. If you want to use Workshop mods, simply copy steam_appid.txt from win64 to xsb-win64 and make sure Steam is running before you start xClient.

    • On Xbox Game Pass installs, your Starbound install is usually in C:\Program Files\ModifiableWindowsApps\Starbound\. Before installing xStarbound, make sure to click the small menu button next to PLAY GAME in the Xbox launcher and select Enable Mods. Normally, you will need to double-click xclient.exe to play with xStarbound. If you want to play it through the launcher, rename win64 to win64-vanilla, then xsb-win64 to win64, then rename xclient.exe to starbound.exe; do not rename any other files or folders. To use your existing Starbound saves, open %starbound%\xsb-win64\xsbinit.config in Notepad or another text editor and change the "storageDirectory" to "C:\\Users\\%username%\\%username%\\Documents\\Starbound\\"; replace %username% with your Windows username.

    • On GOG installs, your Starbound install is in C:\GOG Games\Starbound\ by default.

    • The MinGW version of xClient requires discord_game_sdk_stub.dll to have that name instead of its usual name, but it's the same DLL otherwise.

  • windows-install.exe and windows-msvc-install.exe: This is an installer for xStarbound v4.5.5.3. New xStarbound users on Windows should use the installer — it will install all required files and (if desired) add a Start menu shortcut for you. The installer supports English, Russian and several other languages. The installer may be used to update an existing xStarbound install as long as your install has the folder structure contained in windows.zip. The executables installed by windows-install.exe are built with MinGW; note that joining and hosting P2P sessions via Steam and Discord are not supported by this build. For this reason, an installer for the MSVC / Visual Studio build, which does have P2P support (and significantly smaller binaries), is provided as windows-msvc-install.exe. See windows-msvc-pdbs.zip above for installing the PDBs after installing the MSVC build of xStarbound.

    • Xbox Game Pass note: If you own Starbound through Xbox Game Pass, you will need to click the small menu button next to PLAY GAME in the Xbox launcher and select Enable Mods before running the installer. Xbox Live installs are usually found in C:\Program Files\ModifiableWindowsApps\Starbound\, which may be marked as hidden, so you probably need to paste this path into the path field. To use your existing Starbound saves, open %starbound%\xsb-win64\xsbinit.config in Notepad or another text editor and change the "storageDirectory" to "C:\\Users\\%username%\\Documents\\Starbound\\"; replace %username% with your Windows username.

  • xSBassets.pak: This contains assets required by xStarbound. On Linux, drop this into a new $starbound/xsb-assets/ directory — i.e., a new xsb-assets folder beside the assets and mods folders. If you're updating from xStarbound v4.5.4 or later, you do not need to update the assets. If you're updating from an earlier version of xStarbound, you must update the assets. Windows users, note that windows.zip already comes with the xStarbound assets.

  • xSBassets.zip: Same as above, but not in a .pak file. On Linux, extract this into a new $starbound/xsb-assets/ directory — i.e., a new xsb-assets folder beside the assets and mods folders. Windows users, note that windows.zip already comes with the xStarbound assets.

  • xSBCompat.pak and xSBCompat.zip: This is xSBCompat v4.5.5, a compatibility shim for xStarbound that mostly targets OpenStarbound mods. Install this if you're using any mods on the compatibility list (mostly «[oSB]»-tagged mods) listed as requiring this mod on xStarbound.

    Drop the .pak file or extract the .zip into your $xStarboundInstall/xsb-assets/ folder. The patch should be installed in xsb-assets/, as it currently has a hard xStarbound requirement due to its usage of xStarbound-only features. Please report any issues with xSBCompat in the repo's Issues tab or on Discord.

  • xServerHelper.pak and xServerHelper.zip: This is xServer::Helper v4.5.4, a utility mod for xServer that adds user commands for its world protection system and server account registration, as well as admin commands for server configuration. Drop the .pak file or extract the .zip into your $xStarboundServerInstall/xsb-assets directory, as xServer::Helper obviously has a hard xServer requirement. The version number (sans any «r1», «r2» suffixes, etc) is also the minimum version of xServer required by xServer::Helper.

Certain users should consider reading the following before installing xClient. Click the links with drop-down arrows to expand the appropriate collapsed section(s).

🐧 For Linux users with mouse scrolling issues

Info for Linux users with mouse scrolling issues

If you're experiencing mouse scrolling issues on xClient: Try adding the statically linked Linux build of xStarbound (or any Windows build) as a non-Steam game to Steam (select the xclient binary or, for Windows builds, xclient.exe, not xclient.sh). If you're using the linux-static build, make sure to enable compatibility tools and select the Steam Legacy Runtime; Windows builds should use the default newest Proton. Run xStarbound from Steam when you want to play. This workaround may also fix other input issues related to SDL2.

📦 For Steam Flatpak users

Info for Flatpak Steam users

xClient will not load your Workshop mods if launched while Steam is running as a Flatpak, unless launched directly through Steam. Additionally, the Steam Flatpak is not supported by Valve or your distro's maintainers anyway. So do yourself a favour by uninstalling that Flatpak and installing Steam through your Linux distro's package manager instead.

Attempting to work around this issue by symlinking the Steam Flatpak's config directory to ~/.steam may cause a Steam-related crash when launching xClient. Any GitHub issues or Discord bug reports about crashes, mod loading failures, P2P networking issues, etc., directly related to the Steam Flatpak will be met with this recommendation and closed, as they are not caused by or relevant to xStarbound itself.

⚙️ For OpenStarbound users

Info for OpenStarbound users

Do NOT install xStarbound into an existing OpenStarbound installation directory, as OpenStarbound dumps its assets in /assets and xStarbound is NOT compatible with OpenStarbound's assets. On xClient, this incompatibility manifests as a client shutdown before anything loads with a Path to 'unifont' is not absolute error in xclient.log. On xServer, this incompatibility will not prevent the server from starting, but may lead to unwanted server-side behaviour. If you have mods that check for OpenStarbound's assets, install xSBCompat to bypass these checks.

If you insist on installing xStarbound into an existing OpenStarbound installation directory anyway, follow these instructions to ensure that xStarbound does not load OpenStarbound's assets.

Any issues or bug reports that show 'opensb_base' as a loaded asset source in xclient.log or xserver.log will be closed or responded to with a pointer to the above notice. «Don't make me tap the sign!»

🪟 For Windows users (NVIDIA users experiencing crashes, check here!)

Info for Windows users

While Windows builds will remain available, xStarbound is now a Linux-first project. Windows users should read the following before submitting pull requests, bug reports or suggestions.

Visual Studio builds

xStarbound's Visual Studio toolchain and build scripts are not currently actively maintained. That said:

  • For developers and modders on Windows: Follow the Windows instructions in the readme to set up a working Visual Studio toolchain for xStarbound. We're looking for a Windows maintainer; feel free to volunteer!
  • For players on Windows: The Visual Studio build supports Steam and Discord P2P networking, unlike the MinGW build. However, due to ongoing issues with the Visual Studio toolchain, players who use P2P networking are advised to use a tunnelling service or switch to Linux to host their Starbound server. This applies to any Starbound fork, whether it's xStarbound, OpenStarbound or something else.

NVIDIA driver issue on Windows 10/11

Recent NVIDIA drivers for Windows may crash xClient with an «access of address 0x18» error due to a bug in NVIDIA's «threaded optimisation» feature. To prevent this, open the NVIDIA Control Panel, go to Manage 3D settings, then switch to the Program Settings tab. Click Add, browse to:

  • Steam: C:\Program Files (x86)\Steam\steamapps\common\Starbound\xsb-win64\xclient.exe
  • GOG: C:\GOG Games\Starbound\xsb-win64\xclient.exe
  • Xbox Game Pass: C:\Program Files\ModifiableWindowsApps\Starbound\xsb-win64\xclient.exe

... and add it to the list. If the Starbound installation where you installed xStarbound is located elsewhere, browse to the installation folder's xsb-win64\ directory to find xclient.exe.

Once added, locate Threaded optimization in the settings list and set it to Off, then click Apply. This change will disable the feature specifically for xClient, preventing driver-related crashes.

Any GitHub issues or bug reports on the Discord server for this driver crash will be ignored unless it occurs after you've disabled «threaded optimisation» for xClient. We already know about it, and it's a problem on NVIDIA's end, not xStarbound's. On the other hand, if you're a Windows developer or programmer, feel free to submit a pull request with a better workaround for the bug. If you're wondering, OpenStarbound doesn't run into this driver bug, but the exact reason why is not known even by OpenStarbound's developers.

Contributors

KrashV, FezzedOne, and 2 other contributors
Assets 14
Loading