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"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=19199Setting 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.
- Download and extract the freesia-template.zip archive into a clean directory on your host machine.
- Run install-freesia.bat (on Windows) or install-freesia.sh (on Linux) to automatically download the necessary server and plugin files.
- Wait for all downloads to finish, then verify the IP and port settings in the generated configuration files.
- 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.