FAQ

General

What Minecraft version is supported?

Paper 26.2 (Java 21+; tested on Paper 26.2, Java 25). Spigot and Folia are not supported.

What plugins are required?

SoapsCommon is required. WorldEdit is needed to build rooms. MythicMobs is optional. Vault, SoapsAdmin, and SoapsQuest are optional for locked-floor currencies.

Where is data stored?

plugins/SoapsFloor/. Rooms in rooms/, schematics in schematics/, player stats in data/.

Rooms and building

Schematics are not showing in the browser.

Add .schem files to plugins/SoapsFloor/schematics/. Run /sf reload. Check console for WorldEdit errors.

I cannot finish my room.

You need a starter box (pos1 and pos2), entry/exit points, and at least one floor. Run /sf wand status to check the current step.

Can I rename a room?

Yes: /sf wand rename <old> <new>. Room cannot be in use or under edit.

Floor drops misaligned.

Use the Starter Gap and Floor Gap adjusters in the editor with previews enabled. Defaults are in default-room-settings.

How do locked floors work?

See Locked Floors. Free floors run first. The host buys locked floors in the lobby. Unbought locked floors are skipped.

Gameplay

Players cannot join an active run.

allow-join-in-progress defaults to false. Set it under default-room-settings, or per room in Room Settings (nether star) / room YAML.

Room says full but only 2 players are inside.

Check max-players in global config and per-room settings from the wand editor.

Mobs are not spawning.

Confirm mob type is valid. For MythicMobs, use the exact internal ID. Check floor has spawn locations and spawn-delay-ticks is not stuck with a server lag spike.

Players keep their items on death.

In the wand Room Settings menu, turn on Keep inventory and/or Keep experience for that room. New rooms copy the defaults from default-room-settings in config.yml.

GUI and commands

/sf menu says GUI is disabled.

Set gui.enabled: true in config.yml and reload.

Settings button missing from main hub.

The Settings item requires soapsfloor.admin.gui in gui.yml. Player feedback toggle is also available via /sf settings toggle feedback if you grant soapsfloor.player.settings.

Console cannot run player commands.

Only /sf reload and /sf help work from console. All gameplay and editor commands need a player.

Permissions

Builders cannot use the wand.

Grant soapsfloor.admin.wand or specific children like soapsfloor.admin.wand.create.

Admins cannot break blocks in rooms.

Grant soapsfloor.bypass.protection.

I cannot break a join sign.

Grant soapsfloor.admin.sign.break. Creating join signs uses soapsfloor.admin.sign.

Performance

Large schematic preview crashes clients.

Lower editor-mode.schematic-preview-max-blocks (default 5000). Keep schematic-preview-glow: false.

Falling hazard causes lag.

Lower density and particles-per-point in the room Falling Hazard → Advanced menu (or in the room YAML).

Hazard stays off after a floor.

It pauses during drop/paste and should resume at the same world Y. If a paste failed previously, update to 1.0.7+ (paste failure resumes the hazard). Confirm falling-hazard.enabled: true on the room YAML.

Hazard feels stuck high above after several floors.

It stays in world space on purpose. When far above the current floor it speeds up to catch up, then returns to normal near that floor. Lower fall-interval if you want baseline pressure tighter.

How do I pick a custom particle?

In the Falling Hazard menu, shift-click Particle and type a Bukkit name (e.g. FLAME), or use the clickable suggestions. Type cancel to abort.

Weakness list looks outdated after updating.

weaknesses.yml is not overwritten on update. Merge from the jar defaults or docs, then /sf reload.

Rewards

Reward table not giving items.

Confirm table name with /sf setreward <room> <table>. Check rewards.yml syntax (weight / guaranteed, rolls, optional unique-rolls). Commands run as console: ensure economy/item plugins match your command format. Placeholders include {total_kills}. Weakness × party scaling add fractional extra rolls, not a hard ceil.

Weakness vote never appears.

Check weaknesses.yml → enabled: true. At least one weakness entry must have enabled: true.

Updates

Will my schematics be overwritten on update?

No. Bundled schematics only extract if the file does not already exist.

How do I reload after editing configs?

/sf reload reloads config, messages, gui, weaknesses, rewards, and schematic cache.