Guide · Getting started

Using YSM models on a server (Freesia plugin)

Freesia is an open-source proxy plugin that enables plugin-based Minecraft servers (such as Paper or Spigot networks) to support the Yes Steve Model (YSM) mod. Because YSM normally requires a modded server to handle model synchronization and data generation, Freesia bridges the gap by routing YSM network traffic through a Velocity proxy and a lightweight background Fabric server. Please note that Freesia is a community project licensed under the Mozilla Public License 2.0, not an official YSM release.

How the Freesia Architecture Works

To bring modded YSM features to standard plugin servers without rewriting the entire mod for Bukkit/Paper, Freesia splits server responsibilities across three separate components: Velocity, Worker, and Backend sub-servers. Understanding how these three parts interact is essential before you start editing configuration files.

The Velocity proxy acts as the traffic controller for all YSM network packets. When a player connects, Velocity intercepts their YSM data and forwards it to the right destination while sending their normal gameplay packets to your playable servers.

The Worker is a stripped-down Fabric 1.21 server that runs the actual YSM mod in the background. Players never actually play on the Worker; its only job is to synchronize models, update entity states, and generate NBT data on behalf of the network.

The Backend sub-servers are your actual playable plugin servers where players build and explore. By installing the Freesia-Backend plugin on these sub-servers, they can communicate player tracking data back to Velocity so everyone sees the correct custom models.

Setting Up the Velocity Proxy

On the Velocity side, Freesia relies on two core internal services to manage traffic: the master_control_service communicates with the Worker node to control its behavior, while msession forwards player YSM packets to the Worker for cache synchronization.

You must configure the Velocity plugin so it knows where your Worker server is hosted and how to handle players who join without the mod. Note that the language setting supports both zh_CN and en_US, and the ports you define here must match your Worker configuration later.

[functions]
# Whether to kick players who do not have the YSM mod installed
kick_if_ysm_not_installed = false
# Handshake timeout duration (in milliseconds)
ysm_detection_timeout_for_kicking = 30000

[messages]
# Language option, supports "zh_CN" and "en_US"
language = "en_US"

[worker]
# Master control node address
worker_master_ip = "localhost"
worker_master_port = 19200
# Worker server address (must match server-port and server-ip in Worker's server.properties)
worker_msession_port = 19199
worker_msession_ip = "localhost"
Never add the Worker server to Velocity's playable sub-server list, and never expose the master_control_service (19200) or msession (19199) ports to the public internet, as doing so creates severe security risks.

Configuring the Fabric Worker Node

The Worker node must be a Fabric 1.21 server with both the YSM mod and the Freesia-Worker mod installed. This is where you will place your YSM model files so they can be synced to connected players.

To keep resource usage low, the Worker automatically disables almost all standard Minecraft gameplay features and world saving. It only processes login packets and YSM packets, running a basic server tick loop to handle YSM logic. Although YSM processing on the Worker could theoretically become a bottleneck, Freesia uses asynchronous processing to keep the performance impact minimal.

You need to configure two files on the Worker: the Freesia Worker config file and the standard Minecraft server.properties file. Both the master control port and the Minecraft server port must match the values you set in your Velocity configuration.

# Worker Freesia configuration file example:
[worker]
# Must match the Freesia-Velocity configuration
worker_master_ip = "localhost"
worker_master_port = 19200
# Reconnect interval to the control node (in seconds)
controller_reconnect_interval = 1
# Expiration time for player data cache (in seconds)
player_data_cache_invalidate_interval_seconds = 30
# Worker server.properties configuration:
# Must match the worker_msession settings in Freesia-Velocity
server-ip=127.0.0.1
server-port=19199
Make sure your Velocity proxy machine has network access to connect to the Worker server's Minecraft port (19199 in the example).

Setting Up Playable Backend Sub-Servers

Your playable sub-servers (where players actually log in to play the game) do not run the YSM mod directly. Instead, every playable plugin sub-server must have the Freesia-Backend plugin installed.

Why does the sub-server need a plugin if the Worker does all the heavy lifting? Freesia-Backend handles player Tracker check requests from Velocity and notifies the proxy whenever a player's Tracker needs to be updated. Without this component, the proxy wouldn't know when players come into view of one another on the gameplay server, and models wouldn't render for nearby players.

Quick Start with Template Scripts

If setting up a three-part network from scratch feels overwhelming, you can use the official freesia-template.zip archive to automate the initial download and folder setup.

The template includes automated scripts for both Windows and Linux environments that fetch the required files and prepare the directory structure for you.

  1. Download and extract the freesia-template.zip archive into a clean directory on your host machine.
  2. Run install-freesia.bat (on Windows) or install-freesia.sh (on Linux) to automatically download the necessary server and plugin files.
  3. Wait for all downloads to finish, then verify the IP and port settings in the generated configuration files.
  4. Navigate into each respective server folder (Velocity, Worker, and Sub-server) and run start.bat (Windows) or start.sh (Linux) to launch your network.

Questions

Can players without the YSM mod join a Freesia server?

Yes. As long as kick_if_ysm_not_installed is set to false in the Velocity configuration, vanilla players can join and play normally, though they will only see default Minecraft skins instead of custom YSM models.

Will running a whole extra Fabric server for the Worker lag my machine?

No, the Worker has very low overhead. Freesia disables world saving and almost all normal Minecraft game logic on the Worker, leaving only login handling, YSM packet processing, and a basic tick loop running asynchronously.

Should I add the Worker server to my Velocity servers list in velocity.toml?

Never add the Worker to Velocity's sub-server list. Players should never be routed to the Worker as a playable server; Velocity communicates with it privately through the master_control_service and msession ports.

Which Minecraft version is required for the Worker server?

The Worker node must be set up on a Fabric 1.21 server with both the YSM mod and the Freesia-Worker mod installed.

Next: What is Yes Steve Model? Features and how it works →

More in Getting started

S
All Yes Steve Model Commands (/ysm and /ysmclient)Yes Steve Model includes built-in commands for managing player models, handling server permissions, and debugging animations. Most server commands start with /ysm and require OP permission level 2, while client-side creator tools use /ysmclient. Every command supports in-game auto-completion for player names and model IDs.
S
How to Install Yes Steve Model and Use Custom ModelsYes Steve Model (YSM) replaces the default Minecraft player avatar with custom models and animations. To unlock its full feature set, you must install the mod on both the client and the server, though a client-only workaround exists for vanilla servers.
S
What is Yes Steve Model? Features and how it worksYes Steve Model (YSM) is a Minecraft mod that replaces the vanilla player avatar with custom Minecraft Bedrock Edition models and animations. Designed with multiplayer servers in mind, it combines high-performance rendering with built-in model synchronization and file encryption. Whether you want expressive emotes, custom character designs, or third-party combat animations, YSM provides a complete framework for players and creators.
S
YSM model formats: folder, zip and encrypted .ysmYes Steve Model (YSM) loads custom player models in three different container formats: unpacked folders, compressed archives, and encrypted .ysm files. Understanding how each format works and where to place your files inside the game directory is the essential first step for both players installing models and creators distributing them.
S
Yes Steve Model Config File ExplainedYes Steve Model (YSM) provides both an in-game settings menu and TOML configuration files so players can tweak visual settings and administrators can manage server performance. Understanding where these files live and what each setting does helps you fix rendering glitches, hide default models, and control server bandwidth.
S
Yes Steve Model FAQ and Common ProblemsThis troubleshooting guide covers everything a beginner needs to know to install, configure, and fix Yes Steve Model (YSM) for Minecraft Java Edition. From adding custom models to solving rendering glitches and crashes, follow these steps to get your character models working smoothly.