Compatibility
Minecraft: Java Edition
Platforms
Supported environments
90% of ad revenue goes to creators
Support creators and Modrinth ad-free with Modrinth+Links
Details
Works in singleplayer and on server-side.
Provides a client companion GUI when oωo is installed.
Requires Connector and FFAPI on (neo)forge.
What is Switchy?
Switchy lets you use commands to make presets that are stored with your player data.
Switchy will load modules that tell presets what to store, which can be toggled per-player.
When you switch presets, that data is saved to the old preset, then loaded from the new one.
Modules
Most modules provide inter-compatibility with other mods - be sure to follow the links.
You can hotswap these features out-of-the box by installing their relevant mods:
- Player Nicknames with Styled Nicknames (Note: Switchy force-allows nickname self-assignment)
- Player Pronouns/Bio through
<hover>
or Drogstyle's/bio
- Player Pronouns/Bio through
- Player Skin with Fabric Tailor or model with Figura (via API)
- Player Origin with Origins (includes all layers, e.g. Statures)
- Power state / command powers - e.g. Origin inventories and
/power grant
powers (via MerchantPug)
- Power state / command powers - e.g. Origin inventories and
- Player sizes and scales with Pehkui
- Detailed player profiles for conventions with Lanyard
More functionality can be added with these Addons:
- Switchy Inventories - separate inventories, ender chests, and trinkets (all disabled by default)
- Switchy Teleport - separate player position and spawn points (all disabled by default)
- Switchy Proxy - match message patterns (proxies) to switch nicknames per-chat-message.
- SwitchyKit - import presets with names, proxies, colors, pronouns, and tags - directly from Pluralkit or Tupperbox.
- Switchy Resource Packs - separate enabled resource packs per preset.
These mods have Switchy support built-in (or built in to switchy):
- RPGStats - All stat levels and XP can be kept per-preset
- Hexcasting - Internalized pigment can be kept per-preset (via leo60228)
Showcase
Older showcase that shows fully setting up presets using commands:
Quick Start Guide
Remember, switching does nothing on its own! Make sure you install a mod from above.
Via Server Commands
-
Use
/switchy list
to see your current presets -
use
/switchy rename default [name]
to give your starting preset a name -
/switchy new [name]
will create and switch to a new preset -
/switchy set [name]
or/switch [name]
will switch between existing presets
Toggling Modules
When a module is Enabled, it makes things "switch" (load and save) per-preset.
/switchy module enable/disable [name]
will toggle this for your presets.
/switchy module help
will tell you about a module, and what enabling it does.
Via Client UI
With Switchy also installed on the client, click ;
to open the UI.
The Quick-Switcher allows you to preview and switch presets by clicking on them.
Clicking the manage button shows the manage presets screen, allowing creating, renaming, and deleting presets.
Clicking the modules button shows the manage modules screen, allowing enabling and disabling modules.
Clicking the data button shows the manage data screen, where you can import and export your presets to a file for use on other servers/worlds.
To load from a file, choose import, choose which modules to import from the file, and click import!
Files are saved to .minecraft/config/switchy/
, and are safe to copy between instances.
Client Data Commands
Data operations can also be performed using client-side commands:
/switchy_client export
will export all of your presets and modules to a file.
/switchy_client import [filename] [exclude]
will import all allowed modules, except those in [exclude]
/switchy_client import [filename] [exclude] [operator]
will import all allowed modules, except those in [exclude]
,
adding those in [operator]
if you're a server operator.
You can use ~
to specify no modules.
How do I change a preset nickname? or skin?
Switch to the preset you'd like to change things for, then just do it as normal!
/nick
for nicknames, k
for fabric tailor skins, etc.
When you switch away, they'll be saved - and when you switch back, they'll be restored.
Configuration
Module Editing Permission
Switchy doesn't and will not support permissions on its basic commands, and has no way to enable or disable modules server-wide.
However, you can minorly configure which players can import module data in /config/switchy/config.toml
.
Modules will be listed with one of four import settings:
ALLOWED
: Importable by any player - can be changed toOPERATOR
(e.g. origins)OPERATOR
: Importable by operators when specified - can be changed toALLOWED
(e.g. inventories)ALWAYS_ALLOWED
: Importable by any player - can't be changed (e.g. nicknames/skins)NEVER
: Can't be imported due to technical limitations - can't be changed
Pehkui Scale Types
The pehkui module will switch scale types by the IDs defined in /config/switchy/pehkui.toml
.
By default, it switches height, width, model height, and model width.
This is set by the server - so you can add anything you want to give players switch access to, and remove anything that should be only temporary and switchy might accidentally let players keep.
As an example, Origins Minus uses pehkui:base
to give temporary buffs to players with the Sanguine origin - so this shouldn't be added to the config when it's installed!
Apoli /Power
Types
The apoli module will by default only restore data for powers that the preset already has (e.g. from switching in an origin).
This can be expanded to include powers granted using /power grant
(i.e. powers with the apoli:command
source) in /config/switchy/apoli.toml
- with whitelist and blacklist modes.
This allows, for example, adding an extra power to one preset to give it a 'hybrid origin'.
Developers
Example
repositories {
maven { url 'https://maven.proxyfox.dev/' } // Switchy
maven { url 'https://repo.sleeping.town/' } // Keleido
maven { url "https://maven.nucleoid.xyz/" } // Server Trans
maven { url 'https://maven.wispforest.io' } // owo lib
}
dependencies {
modCompileOnly "folk.sisby:switchy-core:2.8.2"
}
Submodules
All modules use a unified version number. Depend on each required submodule manually.
switchy-core
- Server-side preset/module API and commands.
[core addon] switchy-client
- Client API, preset import/export. Required to define client-sendable modules.
[client addon] switchy-cardinal
- CCA Module API. Dependency unneeded for JSON modules.
[client addon] switchy-ui
- Depends on owo for screens. Module previewing API.
[client addon] switchy-compat
- Module definitions for built-in compatibility like Styled Nicknames.
[compat + ui addon] switchy-compat-ui
- Preview module definitions for built-in compatibility.
[compat + cardinal addon] switchy-cardinal-ui
- CCA Preview Modules. Dependency unneeded for JSON modules.
API
Switchy includes a rich API for both client and server addons for performing all of its basic functions.
Try SwitchyPresets
(via SwitchyPlayer.getPresets()
) covers most mod functions, then SwitchyApi
provides them with text feedback, SwitchyClientApi
provides them on the client, and SwitchyEvents
and SwitchyClientEvents
offer hooks for addons, registering modules, and adding new commands.
Figura Lua API
Listen to switches by subscribing to "switchy.SWITCH"
and "switchy.WORLD_SWITCH"
events["switchy.SWITCH"]:register(function(newpreset, oldpreset, enabledmodules)
-- blah blah
end)
The function body can then match specific preset names to swap in specific models.
Modules
Adding new Modules allows more data to be switched per-preset. They only need to:
- Load and Save their data using NBT.
- Save their data from the player
- Load their data to the player
Just implement SwitchyModule
and register it with SwitchyModuleRegistry
using SwitchyEvents.Init
-
See Switchy Inventories for an example. (Remember to add the switchy
entrypoint in your metafile)
Module Configuration & Commands
Alongside server-level module configuration, which is easily set up within the module itself, modules can also register for player-level configuration when registering their SwitchyModuleInfo
.
withConfigCommands()
allows for arbitrary commands to be registered under /switchy module config [moduleid]
. This is used by Switchy Proxy both to change the player-level latch
option, as well as directly edit module data for proxies.
withModuleConfig()
lets you register a serializable class to construct for every player. You can then easily access it from presets.getModuleConfig(moduleId, YourConfig.class)
in your addon and config commands.
Client Integration
Modules can integrate with the client if they implement SwitchyModuleTransferable
and have a matching SwitchyClientModule
registered with SwitchyClientModuleRegistry
.
The SwitchySerializeable
portion of the server module can be split out and reused for both sides if the held data is usable on the client as-is.
Client modules don't do anything on their own, so implement SwitchyUIModule
if you'd like to add previewing on the switch screen.
See inventories or compat-ui for varying examples.
Data-Driven CCA Modules
If your mod uses the Cardinal Components API to store its
player/entity data, you can instead register a module using CardinalSerializerModule.from()
, or register()
if your component doesn't need extra sync logic besides writeToNbt/readFromNbt
(or just use data).
Any data matching data/*/switchy_cardinal/*.json
will be
loaded like so:
- File namespace and name - module namespace and path.
default
: boolean, module is enabled for players by default.editable
: See import configuration above.ifModsLoaded
: mod IDs to check before trying to register the module.components
: the cardinal components to swap.
Modules can also be previewed in the UI using the serialized NBT data.
Any data matching assets/*/switchy_cardinal/*.json
will be
loaded like so:
- File namespace and name - module namespace and path.
icon
: object. either parsed as a stack or use"path"
with an NBT path to a stack.condition
: optional. NBT path to a booleaninventories
: optional. Array of NBT paths for inventories.components
: optional. Array of NBT paths to pretty print into the tooltip key.
The tooltip will be loaded from switchy.modules.[namespace].[path].preview.tooltip
.
Further Info
This mod is primarily motivated by improving accessibility for plural systems.
❓ Check out Plural Respect.
Afterword
All mods are built on the work of many others.
This mod is included in Tinkerer's Quilt - our modpack about ease of play and self-expression.
We're open to better ways to implement our mods. If you see something odd and have an idea, let us know!
Loveletters: Tabs - Atlas - Portable Crafting - Drogstyle
Others: Switchy - Crunchy - Starcaller