VSUX Framework

Interfaces, themes & effects for Vintage Story 1.22

VSUX Framework

Build the interface your mod needs. Give players a look they can make their own.

VSUX gives mod authors reusable controls, shared themes and visual effects built around Vintage Story's own GUI system. For players, it brings a choice of themes, item pickup notices and richer information displays in supported game and mod interfaces, with tools to customise their look in game.

Installing this for another mod? VSUX supplies the interface tools that mod uses. You can also use VSUX on its own for themes and the built-in authoring tools. Its focus is how the game looks and feels to use; it adds no survival progression.

More time for your mod's ideas

A settings window, a server information panel and a crafting tool all need many of the same things: readable text, useful controls, sensible layouts and clear feedback. VSUX provides those pieces so mod authors can spend more time on what makes their mod useful.

The pieces share a theme, so participating interfaces can feel at home together. They also build on Vintage Story's native GUI lifecycle, keeping its keyboard and mouse input, focus handling and window behaviour.

Make yourself at home

Choose from eight built-in themes: Default, Dark, Light, Evil, Good, Neutral, High Contrast and Reduced Motion. Open the selector with .vsux themes to find a look that suits you.

Your theme remains your choice. Multiplayer servers can share custom themes and recommend one when you join. A theme you explicitly select takes priority over that recommendation.

See what you just picked up

The built-in VSUX pickup HUD shows collected items in the bottom-right corner of your screen. Each themed card pairs the item's icon with its name and the quantity received, so you can check your pickups without opening your inventory.

Pickup notices are enabled by default. To turn them off, set EnablePickupHud to false in ModConfig/vsux-framework/config.json and restart the client. Multiplayer requires the updated framework on both the server and client. Notices cover native pickups and compatible item grants; they clear when you leave the world and do not enter notification history.

More Information where you need it

VSUX powers richer More Information displays with readable text, clickable item references and graphical progress bars. Its information components fit into the game's existing block and entity information panel, item tooltips and handbook, keeping useful details close to what you are looking at.

Time estimates reflect the information available under current conditions; changes in temperature, fuel or work speed can change them. These displays explain the game state without changing recipes, inventories or processing rules.

For mod authors: supply your mod's information through VSUX's shared rich-text and progress components. The framework handles themed presentation inside the existing information display, while your integration controls which facts are shown and which player settings are available.

Notifications you can come back to

A save confirmation, a warning or a task's progress should be easy to follow. The VSUX notification system gives participating mods a shared place for these messages, styled to match your selected theme.

For mod authors: show a short notice or keep one visible while a task runs. Update its text, progress and busy state as work continues, then dismiss it or let it expire. You can supply an icon and control how repeated notices are handled. Updating an existing notice updates its history entry too, keeping progress changes together.

The history covers messages sent through VSUX. It does not collect ordinary game chat or notifications from mods that use their own systems, and it clears when you leave the world.

From a small dialog to a complete mod interface

Start with one component in an existing composer, or build a whole interface with VSUX. Add the services you need as your mod grows.

Your mod controls its layout and behaviour; the shared theme supplies its visual style. Custom components and scoped exceptions to automatic theming give you room for interfaces that need their own rendering.

Create effects while you're in game

Give a button a glow, draw attention to a changing value, or build an effect for the world around the player. VSUX supports layered UI effects and reusable world effects combining particles, sprites, meshes, ribbons, beams, lights and sound.

Effects Studio gives you an in-game workspace for authoring them. Start from a preset, arrange emitters and effect modules, adjust timing on the timeline, and preview changes with undo and redo. Separate GUI and in-game/entity workspaces keep the tools relevant to what you're making.

Join a world and enter .vsux effects or .vsux studio to open it. You can browse installed shapes and textures, then save validated effects locally for testing and export.

Saving in Studio does not publish an effect to a server or add it to a mod automatically. The preview helps you author it; lighting, sound and collision still need testing in the world.

VS Server Panel is the first mod to fully use VSUX Framework.

Getting started

1. Choose the VSUX download for your Vintage Story 1.22 version and place it in the game's Mods folder.
2. For multiplayer, install VSUX on the server and every connecting client.
3. If another mod requires VSUX, check the framework version it needs and install that mod too.
4. Start the game, then use .vsux themes to choose your theme.

Managing server themes? Join a world and use .vsux creator to open the server theme creator. It requires the server's controlserver privilege. If it reports that the connection is not ready, reconnect and check both startup logs if the issue persists; this message does not mean VSUX is disabled on the server.

Modder wiki: coming soon

The public modder wiki isn't live yet. It will cover getting started, components, layouts, themes, effects and the API. In the meantime, ask integration or theme-authoring questions here on ModDB or in the community Discord.

Adding VSUX to your mod? Declare vsuxframework as a dependency, reference VSUX-Framework.dll with copy-local disabled, and obtain the registered client API during client startup. GUI composition belongs on the client; multiplayer installations need the framework on both sides.

A few things to know

How much of the interface will change?

VSUX automatically themes supported native controls, including compatible controls in other mods. A mod with its own custom rendering may keep its own appearance. Installing VSUX does not add new VSUX components or effects to every existing mod.

Can I reduce the visual effects?

Yes. VSUX has player settings for reduced motion and enhanced effects, alongside the High Contrast and Reduced Motion themes. These apply to the presentation VSUX controls.

Another mod says VSUX is missing. What should I check?

Make sure VSUX is enabled, meets that mod's required version and is installed on both sides for multiplayer. The client or server log should identify any dependency error.

Questions, ideas or something that doesn't look right?

Leave a comment here on ModDB or join the community Discord. Whether you're choosing a theme or building your first VSUX interface, you're welcome to ask.

For bug reports, include your Vintage Story and VSUX versions, any affected mod, what you were doing, and the relevant client or server log.