SnDevelopmentInstallation
SnCompanions is a licensed Sn plugin. Install it, boot once to generate the license file, paste your key, then restart.
- Download the latest
sncompanions-v*release from Sn-Releases. - Place the
.jarfile into your server'splugins/folder. - Start the server once. The plugin creates
plugins/.Sn-License/license.yml. - Open that file and paste your Sn license key in place of the placeholder line.
- Restart the server. The plugin validates the key at startup.
SnLib is required and must be installed as its own plugin in plugins/. This build targets
com.sn:snlib 1.31.0, so run that version or newer. SnLib is never bundled inside the jar.
1.31.0 is what the drop key (Q) in the storage menu needs, and it is a requirement the startup API check cannot enforce: SnLib 1.31.0 grew no new Java surface, so its API level is the same as 1.28.0's. On an SnLib older than 1.31.0 SnCompanions still enables normally and everything else works - only Q over a stored companion does nothing.
The key file at plugins/.Sn-License/license.yml is shared by every Sn bundle plugin on the
server. One key unlocks all of them, so you only paste it once, no matter how many bundle
plugins you run. Without a valid key the plugin refuses to enable and disables itself during
startup.
Dependencies
| Plugin | Required |
|---|---|
| SnLib | Yes |
| packetevents | Yes |
| PlaceholderAPI | No |
| BetterModel | No |
| EdTools | No |
| Floodgate | No |
SnLib is the engine behind the config, language, database, item, menu and command layers.
packetevents draws every companion and sends the formation updates, so the plugin cannot run
without it. PlaceholderAPI adds the %sncompanions_...% expansion. BetterModel lets a companion type
render as an animated model instead of a head. EdTools lets an equipped companion grant currency and
global-enchant boosters, and unlocks the EDTOOLS_BLOCK_BREAK experience source so a companion can level
from the blocks an omnitool consumes. It is reached through only two isolated classes, and a server
without it never loads an EdTools type: the break listener is not even registered. Floodgate
identifies the players who came in through Geyser, which is what lets each of them be sent a
substitute companion their Bedrock client can actually draw instead of the Display entities Geyser
discards in silence. It is asked about a player exactly once, on their join, never from the animation
tick, and a server without it never loads an org.geysermc class.
Without Floodgate every player is treated as a Java client. The bedrock: band of config.yml
then does nothing at all, so on a Geyser server the Bedrock players keep seeing nothing where their
companions are, with only the name plate hanging in the air. Nothing breaks and nothing warns: the
plugin simply has no way to tell the two kinds of client apart. See Bedrock players see a substitute
companion.
Adding or removing Floodgate does not need a restart. Either one is handled live: the plugin re-asks every online player and rebuilds every formation one tick later, so the substitutes appear or disappear on their own.
If you run BetterModel and Floodgate together, give every companion a head-texture. A Bedrock
viewer receives the companion as its HEAD and never as the animated model - the substitute's helmet is
always built from head-texture, whichever backend the companion renders with - so a companion that
declares a model: and no head-texture dresses its substitute in the default head. All three
shipped companions already declare one.
Folia is not supported. The plugin does not declare folia-supported, so run it on Paper.
The plugin targets Paper 1.20.4 and newer, and both the 1.20 and 1.21 lines are supported. Java 21 or newer is required, since the jar is compiled at release 21.
What the first boot creates
On a clean install the plugin writes its own files into plugins/SnCompanions/:
| File | Purpose |
|---|---|
config.yml | Every tunable: formation, animation, buffs, fusion, eggs and more |
lang/messages_en.yml | Every user facing message, in English |
lang/messages_es.yml | The same messages, in Spanish |
guis/main.yml | The storage menu: the grid, the equip slot markers and the buttons of the bottom row |
guis/eggs.yml | The egg shop, one file for every egg you declare |
guis/fusion.yml | The fusion menu: the two input slots, the confirm beacon and Fuse All |
guis/bulk_delete.yml | The bulk delete menu, one button per group |
companions/*.yml | One file per companion type, three examples seeded |
eggs.yml | Every companion egg, one top-level key each, one example seeded |
The companions/ folder and the eggs.yml file are seeded
exactly once, on a true fresh install. After that they belong to you. A companion file you delete
stays deleted and is never restored on the next boot, and eggs.yml carries a
# sn:extensible-root header so a key you delete stays deleted too. config.yml, the language
files and the menu layouts are managed instead: new keys are merged in on boot while your
values and comments are preserved.
Once the server starts cleanly, run /companions admin give <player> ember_fox to hand out the
first companion, then open /companions to see it in storage.