10 releases, newest first.
1.8.1 is the API baseline; additions-only from here. The public surface in
com.sn.companions.api - eight facade methods, five cancellable events, three notifications and
three views - is now frozen against removals. Nothing public is removed, renamed, or changed in
signature or observable behaviour after this release; an addition bumps the MINOR component of
API_VERSION, which stays 1.0.0 for this baseline. Versions 1.0.0 through 1.8.0 did not follow
that rule and the constant never moved, so a consumer compiled against an older jar should check
its surface against the API page once, and never again.
This release ships no new feature and changes no gameplay. It closes the development pass that built the plugin:
SnDevelopmentGuiService.anyMenuOpen) and corrected every javadoc, config comment and counter that still
described a plugin with more menus, more admin leaves or more registries than this one has.plugin.yml now carries an honest description.config.yml eggs.default is validated on every load. Pointing it at an egg eggs.yml does not
declare now logs one console WARNING naming the id, instead of only surfacing when a player walks
into the shop and is refused.egg_animation migration probe escapes the LIKE wildcards it passes to the JDBC driver, so
egg_animation can no longer be matched by a same-shaped column with a different separator.guis/main.yml and guis/fusion.yml document {icon} as the second name of {texture}.https://github.com/ValentinTarnovsky/Sn-Releases/tree/main/docs/gitbook/sncompanions
| Version | What it did |
|---|---|
| 1.1.0 | Removed companion scrolls and the upgrades-to rarity ladder |
| 1.2.0 | Removed traits and the traits menu |
| 1.3.0 | Removed boosts, the roll infrastructure, the internal currencies and the selector menu |
| 1.4.0 | Replaced companion boxes with companion eggs: eggs.yml, weighted tables, one key per egg |
| 1.5.0 | Eggs cost money: per-bundle price buttons charged in Vault or an EdTools currency, with a full refund when an open cannot be saved |
| 1.6.0 | The in-game egg shop, /companions eggs [egg], one menu file for every egg |
| 1.7.0 | The LINE formation: companions in a straight row behind their owner, at their feet |
| 1.8.0 | The Dragon Egg hatch show, drawn with packets, with a per-player switch saved on the owner row |
| 1.8.1 | This release: orphan sweep, final documentation, API baseline |
Opening a companion egg now plays a hatch show. A Dragon Egg appears about 1.5 blocks in front
of the buyer, at their feet, and shakes - slowly at first, then harder and faster, with step-sound
climbing in pitch on every frame. When shake-ticks runs out it breaks in a burst of its own block
particles with break-sound, and the companion's head rises out of the wreckage carrying its name
for reveal-ticks with reveal-sound. Only then does the summary reach chat.
Nothing is spawned. The egg, the head and the name are drawn with packets, the same way the companions behind an owner already are, so nothing can be walked into, pushed, hit or picked up and no block or entity is ever written into the world. It is shown to exactly the players who may already see that owner's companions - the same range, the same vanish rules, the same two hide preferences - and its sounds go to those viewers rather than to everyone in earshot.
The show decides nothing. The companions are granted and saved before the first frame is drawn, so quitting, crashing or changing world mid-hatch loses the animation and keeps every companion. A quit or a world change cancels the show and takes the egg off every screen; a world change still delivers the chat summary.
One show per player. Buying a second egg while the first is still hatching is refused with the
new messages.egg-animating, before anything is charged. /companions admin openegg is never
refused for this: it lands, and reports in chat if the player is already watching one. A bundle of
N eggs plays ONE show whose reveal sums the lot (+N beside the first companion's name).
The menu closes when the show starts, since the animation happens in the world and the shop
sits on top of it. It stays open when the player has the animation off. Two cases end the show
before it begins on purpose: a player who cannot see their own companions at all (the visibility
toggle, or a world outside worlds.render) gets their summary at once instead of several seconds
of nothing, and holograms.enabled: false reveals the companion with no name plate, because that
switch means the same thing here as it does above a companion.
Every player can switch it off for themselves. Slot 36 of the eggs menu draws anim-on or
anim-off and clicking it flips the preference, says so, and saves it - it survives a relog and a
restart. With it off, eggs give exactly the same companions and the summary goes straight to chat.
animation.enabled in eggs.yml stays the server's own per-egg switch and still wins.
One database column is added automatically. egg_animation on sncompanions_players, on the
first boot of 1.8.0, with every existing player left with the animation ON. It is looked up before
it is added and the duplicate is swallowed underneath, so later boots run one catalogue read and no
statement. SQLite and MySQL both covered. Nothing to run by hand.
New lang keys (both locales, merged into your file on boot): messages.egg-animation-on,
messages.egg-animation-off, messages.egg-animating, menus.egg-reveal, menus.egg-reveal-bulk.
The last two are the floating label above the revealed companion, not chat lines.
This release was built and reviewed without a running server, and three things about the show are derived rather than seen:
ITEM_DISPLAY with context NONE, which renders
a block item at its full 1x1x1 size centred on its origin - hence the egg being positioned half a
block above the owner's feet. If the egg turns out to look wrong on a client, the BLOCK_DISPLAY
alternative and the exact position correction it needs are written out in the javadoc of
PacketEggBlock.depth = +1.5 in front of the owner, from the same rotation the
formation uses (positive is in front, which is why the companions pass a negative one).BLOCK on 1.20.5+,
BLOCK_CRACK on 1.20.4) so the jar keeps working on both, and every sound is per egg in
eggs.yml - the step-sound pitch is deliberately ignored and climbs from 0.8 to 2.0 instead.Tell us if any of it looks off and it is a one-line adjustment.
Paper 1.20.x and 1.21.x. Requires SnLib. Public API unchanged - API_VERSION is still 1.0.0, and
CompanionEggOpenEvent / CompanionEggRewardEvent fire at exactly the same points with the same
fields whether or not the player watches the show.
formation.shape: LINE - what the plugin ships from now on - puts every equipped companion on
one line perpendicular to the owner's facing, formation.line.distance blocks behind them
(1.0), formation.line.spacing blocks apart (0.8), ordered by equip slot from the owner's
RIGHT. A lone companion stands dead centre behind them. The row is always centred on the owner,
so equipping one more slides it half a spacing across instead of growing it out to one side, and
the whole row swings with the camera exactly as the arc did.CIRCLE and OVAL are untouched. Set formation.shape back to either one and radius,
back-radius, arc-degrees and arc-center-offset mean exactly what they always did. An
unknown value still logs one warning and falls back to CIRCLE; an absent one still falls back
to CIRCLE silently.formation.line.spacing (0.8) and formation.line.distance (1.0). A negative
distance runs the line in FRONT of the owner, which is what you want for a screenshot.formation.shape OVAL -> LINE, formation.height-offset
1.9 -> 0.08, animation.bounce.height 0.06 -> 0.0.config.yml is managed: SnLib merges missing KEYS into your file but never overwrites a VALUE you
already have. So the two new line.* keys arrive on the next boot on their own, but the three
changed values above do not reach an existing config.yml. Set them yourself and run
/companions reload:
formation:
shape: LINE
height-offset: 0.08
animation:
bounce:
height: 0.0A fresh install needs none of this.
formation.height-offset is the blocks above the owner's FEET the companion origin sits at. A
player head drawn as a ground item hangs 1/16 of its scale below its origin, so the value that
rests it on the floor is:
height-offset = 0.0625 x animation.head-size0.08 is that rule at the shipped head-size: 1.3. Scale the heads and scale this with them -
head-size: 4.0 gives a companion about one block tall and wants height-offset: 0.25. Raise it
freely to go back to floating companions (the old look was 1.9).
models.height-offset is SUMMED with it and moves only the companions drawn as BetterModel models.
A model's origin is already at its feet, so 0.0 leaves it standing 0.08 above the floor and
-0.08 puts its feet exactly on the ground.
These two numbers are derived, not measured in-game. If the companions look like they float or
sink a little on your server, formation.height-offset is the one value to nudge.
API_VERSION stays 1.0.0. The shape only moves where companions are
DRAWN, which no part of the API contract exposes.CIRCLE/OVAL still share a single formula.The companion eggs shop. Eggs were already a purchase; now there is a place to buy them.
New menu guis/eggs.yml - ONE managed menu for every egg eggs.yml declares. Which egg is
on screen travels with the player, so adding a key to eggs.yml gives it a shop page with no
menu file to write, and deleting one leaves no orphan menu behind.
pool): the companions this egg can give, each with its {chance} -
the row's weight normalized over the whole table, never the raw number you wroteopens): one button per price tier, with its amount and its priceanim-on / anim-off templates ship declared but unbound, for the hatch
animation switch of the next versionBoth regions are sized by the mask alone: widen the p or o run to show more.
New /companions eggs [egg] (sncompanions.eggs, default true). With no argument it
opens eggs.default; the optional id tab-completes over the eggs that exist right now.
New egg button on guis/main.yml, opening eggs.default.
A button you cannot pay for is drawn with the open-button-locked template instead of
open-button. Its click stays enabled on purpose: pressing it runs exactly the same purchase,
which refuses with the message naming the price and the currency. The menu decides nothing about
money - the master switch, the creative rule, the cooldown, the price, the storage decision, the
charge and the refund are all re-taken when the button is pressed.
New messages.egg-unknown, sent when the shop is asked for an egg eggs.yml does not
declare - most often an eggs.default naming a key that was renamed. Both doors refuse to open
rather than showing a blank window.
guis/eggs.yml seeds itself on the first boot. guis/main.yml is managed, so the merge adds the
new eggs-button entry but keeps YOUR layout:, which has no letter for it: put an e where you
want it - the shipped mask uses slot 45, the first cell of the bottom row, as "e < > Fd".
/companions eggs works either way.
No database migration. The public API is unchanged; API_VERSION stays 1.0.0.
Companion eggs now cost money. Until this version every open was free; the price an egg
declared was parsed and shown and nothing was ever charged. EggManager.open gains a charge
flag, so a purchase and an admin gift run the same roll, the same capacity decision, the same
reservation and the same grant chain, and only the money differs.
price.currency: vault charges the server economy through Vault (or whatever
backend SnLib is configured with). price.currency: edtools:<id> charges one of your EdTools
currencies through the EdTools currency API. Egg prices in EdTools money do not depend on
edtools.enabled, which governs the companion boosters and nothing else.vault egg with messages.egg-no-economy. An <id> EdTools does not serve refuses
that egg with messages.egg-no-currency, and the console names the egg the moment eggs.yml
loads so a typo is visible before a player finds it. Opening an egg produces companions, so a
free egg would hand them out for nothing.eggs.allow-creative, the egg's own cooldown-seconds and the price. The cooldown is armed
only after the money really moved, so a refused purchase never starts one.opens: button prices its own bundle. An amount with no button of its
own costs the first button's price in proportion, so nothing invents a discount curve.opens: button prices a bundle rather than one egg.CompanionEggOpenEvent, the storage
reservation, the charge, the grant. The reservation sits ahead of the charge because the server
economy settles a tick later, and it is handed straight back if the charge fails.Eight new lang keys in both locales - egg-creative, egg-cooldown, egg-not-for-sale,
egg-no-economy, egg-no-currency, egg-no-money, egg-charged, egg-refunded - plus a new
menus.eggs block holding the money words. currency-vault ships with a value; add
currency-<edtools-id> for any EdTools currency you want renamed, and an id with no key shows
itself. SnLib merges all of them into your existing files on boot, keeping your values and
comments. No database migration.
No surface change, and API_VERSION stays 1.0.0. No type, method or signature was added,
removed or altered. What changed is only that CompanionEggOpenEvent.isCharged() and
CompanionEggRewardEvent.isCharged() can now return true: they were always false while every
open was free. CompanionEggOpenEvent still fires before the charge, so cancelling it costs the
player nothing.
Companion boxes are gone and companion eggs take their place. An egg is a purchase, not an item: nothing is minted, traded or right-clicked. The weighted table rolls the moment the egg is opened and the companions go straight to the owner's storage.
eggs.yml (seed only, # sn:extensible-root) replaces boxes.yml. One key per egg:
display-name, price.currency (vault or edtools:<id>), an opens list of explicitly priced
bundles, the drops table, the hatch animation, the two feedback keys and cooldown-seconds./companions admin openegg <player> <egg> [amount] (sncompanions.admin.openegg) opens
eggs for an online player without charging them. givebox and giveallbox are gone.config.yml: the boxes band is gone; a new eggs band takes its place (enabled,
default, allow-creative), and blocked-blocks moves under companion-items, where the redeem
click is now its only reader.box_<id> registration, the success chance
stamped on the stack, the fail roll, the shift-click bulk open, the actionbar spinner and the
boxes/ folder migration.box-* lang keys out, 10 egg-* keys in, in both locales.The public API CHANGED, and API_VERSION stays 1.0.0 on purpose. The contract is still
provisional and is being cut down feature by feature, so removals are made outright rather than
through a deprecation cycle; bumping the version would claim a stability it does not have yet.
CompanionBoxOpenEvent, CompanionBoxRewardEvent.CompanionEggOpenEvent (cancellable, fired after the gates and before anything is charged
or granted) and CompanionEggRewardEvent (notification, fired after the companion rows are
persisted, so every companion it names is already queryable through the facade).Compile against the version of the jar you ship with, and re-read the Developer API page when you upgrade.
No migration. Nothing about the schema changed.
Boosts, the roll infrastructure, the three internal currencies and the companion selector are
removed. CompanionModifierSource.NONE is now the single modifier source, so buffs, experience
and the EdTools boosters all value a companion at its base rate.
boost-grades.yml, the roll roulette and its per-player
animation switch, the trait-ticket / dice-normal / dice-special balances, and the
guis/boosts.yml and guis/selector.yml menus. 19 files deleted./companions admin setboost and /companions admin currency are removed along with
their permissions. The admin tree is now 18 leaves, 20 declared help leaves.{boosts} is no
longer bound, and the [companions-forget-selection], [companions-skip-spin] and
[companions-toggle-roll-anim] tags are unregistered.fusion.keep.boost-* is gone from config.yml.%sncompanions_currency_<id>% placeholders no longer resolve. The
other nine, plus buff_ and equipped_, are unchanged.edtools-boosts, edtools:,
messages.edtools-currency-*), the buffs, the companion boxes, and the shared reveal spinner.No migration, and none is needed. sncompanions_players stops reading and writing
ticket_trait, dice_normal, dice_special and roll_animation, and sncompanions_companions
stops reading and writing boost_experience, boost_level and boost_buff. Every one of those
columns is nullable or NOT NULL DEFAULT, so a database created by 1.2.0 or earlier keeps them,
keeps its data, and works untouched. Do not drop them by hand.
The API surface SHRINKS in this release, and API_VERSION stays 1.0.0 on purpose. Removed:
getBoostGrades(), getCurrencyBalance(UUID, String), the BoostGradeView and RollChangeView
records, the CompanionRollEvent and CompanionRolledEvent events, and CompanionView's
experienceBoostId / levelBoostId / buffBoostId components (the record is now 7 components).
The contract is still provisional: SnCompanions is a new plugin with no known consumers and its feature set is still being cut down, so removals are made outright rather than through a deprecation cycle, and the version is not bumped for them. Compile against the version of the jar you ship with.
Drop the new jar in and restart. config.yml, the language files and the menu layouts auto-merge:
your values and comments are kept, and the removed keys simply stop being read. boost-grades.yml
is no longer shipped - the file already on your server is inert and can be deleted whenever you
like. The same is true of guis/boosts.yml and guis/selector.yml.
The traits feature is removed. SnCompanions no longer has traits: the global roll table, the two trait menus and every effect a trait had are gone. Boosts, fusion, the roll infrastructure and companion boxes keep working exactly as before, minus the trait's contribution.
traits.yml, guis/traits.yml, guis/traits_index.yml, the whole traits: config band, fusion.keep.trait, /companions admin settrait and sncompanions.admin.settrait, and every {trait} placeholder in the menus, the companion item lore and the holograms.A database created before 1.2.0 keeps its trait column untouched. The column is nullable and the plugin simply stops reading and writing it, so an upgrade is a jar swap. Do not drop the column by hand.
config.yml, the language files and the menu layouts auto-merge on boot as always, keeping your values and comments. guis/traits.yml and guis/traits_index.yml are not deleted from an existing install: the merge never removes a file. They are dead weight and you can delete them yourself whenever you like.
trait-ticket currency is temporarily orphanedCurrency.TRAIT_TICKET, the ticket_trait balance, messages.currency-trait-ticket, %sncompanions_currency_trait-ticket% and /companions admin currency trait-ticket all still exist, and nothing spends them any more. Balances are preserved. They are retired together with the rest of the currency work in a later version rather than being dropped here.
API_VERSION stays 1.0.0Removed outright, with no deprecation cycle: SnCompanionsAPI.getTraits(), the TraitView record, CompanionView's trait component (11 components to 10) and CompanionRollEvent.TRAIT / TRAIT_TICKET.
getApiVersion() still answers 1.0.0. That is deliberate: the contract is provisional while the plugin's feature set is being cut down, and bumping the version would claim a stability it does not have yet. The API version does not tell you whether surface went away, so compile against the jar you ship with. The javadoc and the GitBook page that previously promised removals never happen were corrected to say this.
Requires SnLib. Built with the release profile, so this jar's hash is registered with the licence backend.
/companions admin givescroll with its sncompanions.admin.givescroll permission.scrolls: band from config.yml and the 20 scroll-* / admin-unknown-scroll keys from every locale. Both messages_en.yml and messages_es.yml still carry the same key set (169 each).upgrades-to rarity ladder (CompanionType.upgradesTo / canUpgrade(), CompanionRegistry.parseUpgradesTo), whose only consumer was the rarity scroll.guis/main.yml loses the storage-drop-target item and both input: true flags, and player-inventory goes back to locked, so the companions menu freezes your inventory like every other menu of the plugin./companions admin setowner.No API change: API_VERSION stays 1.0.0. companions/ remains seed-only, so your own companion files are untouched.
Existing installs keep their scrolls: block and their old lang keys on disk (managed files are never pruned); they are simply no longer read.