Switchy

An extensible preset system for player customizations provided by other mods.
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 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)
• 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

1. Use /switchy list to see your current presets

2. use /switchy rename default [name] to give your starting preset a name

3. /switchy new [name] will create and switch to a new preset

4. /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.
Hovering over toggle buttons will show detailed information on the effects of pressing them.

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 save to a file, choose export, choose which modules to include in the file, and click export!
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 to OPERATOR (e.g. origins)
• OPERATOR: Importable by operators when specified - can be changed to ALLOWED (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 boolean
  • inventories: 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!

---

Tinkerer's: Quilt - Smithing - Origins - Statures - HUD
Loveletters: Tabs - Atlas - Portable Crafting - Drogstyle
Others: Switchy - Crunchy - Starcaller