Nucleus released this version on Sep 5, 2020

2.6 MB

This is an update of RC5 - one bug was fixed

This is a release candidate of Nucleus 2.0.0 for Sponge API version 7.3


Please report any issues to Github Issues (https://github.com/NucleusPowered/Nucleus/issues) CLEARLY stating the version of Nucleus you are using.

This was built from Nucleus commit: 2e9883a8

Release Notes

If you’re having trouble, visit our Discord channel: https://discord.gg/A9QHG5H

Nucleus 2.0

Nucleus 2 is a major rewrite of much of the base code. It is designed to make future work to the system simpler, easier to understand, and hopefully, easier for people to contribute to.

As it stands, Nucleus 2 is semi-stable, but please do not use it on production servers without testing first. I would appreciate any testing I can get. I am only one person!

Here is a rundown of some of what is new, changed, removed, fixed and crucially, known to be broken.

PSA: Before you use Nucleus 2…

Nucleus 2 does not change how your data is stored, but the entire storage system has been completely rewritten. There may be issues with the storage system that I have been unable to test that might cause unexpected data loss. If this happens, please tell me via Github Issues.

No migration is necessary for the following:

  • main.conf
  • info.txt and other info files
  • User data
  • World data
  • Kits, warps, and other general data

Nucleus 2 also uses a new format for the commands.conf file and no migrator has been provided.

Also, a note on the version. The Nucleus version will no longer contain the Sponge API version that it is built for, instead preferring new major versions to denote the change. This will still be denoted in the file name.

Nucleus 2 is for Sponge API 7.3 or any later version of Sponge API 7.x.

For Server Owners and Players

If you need help to decide which version of Nucleus to use, please visit our guide on how to choose.

For the things YOU need to do as a server owner, please visit our instructions on how to upgrade.

ADDED: Permission Levels/Powers for moderation tasks

Many of you have been asking “permission levels” because you don’t trust lower level staff to not abuse their powers and use them against higher level staff. They already existed for social spy, but now they exist for muting, jailing, kicking and banning. This feature allows you to give a numeric level to each player - by default, if your level is higher than the person you’re trying to act upon, your action will go through. By default, those with the same power for an action will not be able to affect each other.

Because this is an advanced feature, you must turn it on for the respective modules. The options in the mute, jail, kick, admin (for /sudo) and ban modules are:

  • use-permission-level: set to true to use permission levels
  • can-affect-same-level: set to true to let two players with the same permission level affect each other, false if not.

To specify a permission level, you have to give a specific permission option to the player in question. In LuckPerms, options are referred to as “meta”. The options you need to assign are specified in the config file (at least for now, will be on docs later), but for convenience, they are:

  • nucleus.ban.level
  • nucleus.jail.level
  • nucleus.kick.level
  • nucleus.mute.level
  • nucleus.sudo.level
  • nucleus.socialspy.level (this already existed)

No prizes for guessing which one is which! In LuckPerms, you would then specify the level an option using the command:

/lp user <user> meta set <option> <level>

For a ban level of 4 on dualspiral:

/lp user dualspiral meta set nucleus.ban.level 4

If a level is invalid or does not exist, having the permission to run the command you are running is considered a level of 1, not having the permission is considered a level of 0.

This has only been lightly tested. Please report any feedback on the system to me during your testing.

ADDED: Ability to specify arbitrary command names for Nucleus commands (EXPERIMENTAL)

Nucleus commands can now be given arbitrary command names in commands.conf under the “root level aliases” section, and Nucleus will attempt to register the command under that alias.

This feature is still subject to some testing, but I realised it was easy to add with the new codebase.

ADDED: Per User translation of Nucleus system messages

Nucleus will support sending translated messages to players based on either:

  • The locale set via /nucleussetlanguage on a per-player basis; or
  • The client’s locale.

This will be available as we (hopefully) receive more translations.

You will be able to turn this off, of course, if you want all clients to see the same language.

(If you want to help with the translation effort, see https://v2-beta.nucleuspowered.org/docs/translation/)

ADDED: Permission context when running a Nucleus command

When a player is running a Nucleus command, they will obtain a permission context for the duration of that call. This context is nucleus_command, and will have a context value corresponding to the command in question - this can be seen by looking at the help page for the command in question.

ADDED: Compatibility Warning system

Nucleus comes packaged with information about known plugins and mods that conflict with its functions. These warnings may appear on startup, and on demand by running /nucleus compat.

ADDED: Kit data can now be reloaded from persistence on demand

I don’t recommend that you ever do this manually, but you can now update the kits data from persistence and reload it using /kit reload.

ADDED: /basictitle, /basicsubtitle and /basicactionbar commands

These commands allow you to send title, subtitle and actionbar messages to all or specific players. They work the same way as /planbroadcast. The flags for these commands are:

  • -p [player]: The name of the player or a selector that defines who to send the message to. If omitted, sends to all on the server.
  • -i [seconds]: The amount of time taken by the fade in effect, in seconds (does not affect action bar messages).
  • -o [seconds]: The amount of time taken by the fade out effect, in seconds.
  • -t [seconds]: The amount of time taken the message remains on the screen, in seconds.

ADDED: Notification module

This module houses the broadcast commands, as well as the new /basictitle, /basicsubtitle and /basicactionbar commands. Relaxant config from the admin module will be auto-migrated.

ADDED: Support for automatic USER permissions on the default group

Particularly useful for OP based servers, if you want all players to have access to all permissions in the nucleus USER role, you can now set core.give-default-group-user-permissions to true and all users will be granted all permissions in the USER role. This is equivalent to granting the nucleus.user permission, but can also be used on servers with no permissions plugin installed.

MODIFIED: Chat tokens no longer accept pl style tokens

Chat tokens work similar to before, but are no longer plugin namespaced (so, {{pl:[]}} will no longer work). {{o:[]}} style tokens, those that select options from your permissions plugin, will still work.

MODIFIED: The /tp alias for /teleport defaults to disabled

Many mods, such as JourneyMap, were using the /tp command to perform teleports

Other commands may get the same treatment if the Nucleus team figures that it would be in the best interest of the community.

MODIFIED: The /mute and /unmute, /jail and /unjail commands are no longer toggles

This also has the side effect of making these actions all require their own permission.

MODIFIED: Warps now always require the permission nucleus.warps.<name> to redeem

Until recently, this was a configuration toggle. This is no longer the case. To emulate the previous behaviour, simply grant the nucleus.warps permission.

MODIFIED: Permission Group Chat Templates

The original way Nucleus attempted to determine which group template to use when displaying chat formatting was unpredictable and was very slow as it had to collect a lot of data from a permissions plugin. This has now been removed.

Nucleus has supported a nucleus.chat.group permission option (meta in LuckPerms) for some time. This option is now the only way to determine the group template a permission group or user will use - falling back to the default if this does not match.

MODIFIED: Permission Group /list groups

For similar reasons to chat groups no longer relying on parent groups, /list no longer does either. Groups are now defined by the nucleus.list.group option/meta. The group alias config has also been removed, as you can just provide them the same nucleus.list.group option value.

As a bonus, /list groups now use text colour codes in the group names.

MODIFIED: /kit add has been merged into /kit create

The action performed by /kit add in v1 was to create a kit based on your inventory. This is now /kit create -c instead.

Both /kit create and /kit create -c now require the edit kit permission to actually add items to kits.

REMOVED: Debug Mode

Nucleus will just spit out errors to the console now, as they should never happen (or if they do, you should know about them).

REMOVED: The Warnings module has been removed

It wasn’t used much and, honestly, it was actually pushing the boundaries as to what Nucleus really should be doing. There are no migration paths available as it stands, however plugin developers can use the Nucleus API to extract any warnings against a player if they wish to enable such migration.

REMOVED: The Server Shop module has been removed

It wasn’t used much, and it had many issues with it that were not simple to fix. There are no migration paths available.

REWRITTEN: Teleportation Routines

Player teleportation should now be more reliable as the base teleport code has been deleted and completely rebuilt.

REWRITTEN: Message channel support removed for higher compatibility with other plugins

Nucleus will no longer use message channels, instead using an in-house solution to support formatting with other mods, (and for reporting formatting to other plugins). However, when possible, the message channels will still be applied to the event so plugins can see that Nucleus is doing something with them.

BUG FIXES: Miscellaneous fixes

While many bugs might have been introduced, other bugs have been fixed. Notable issues that have been fixed will be noted here.

For Plugin Developers that use the API

REMOVED: The Nucleus static object

I’m going to start with something that isn’t in the API - Nucleus.getNucleus(). I’ve had the occasional complaint that updates to Nucleus have broken some plugins that depend on it. It always turns out to be developers not asking for API additions (which I try to guarantee) but just decide to use Nucleus.getNucleus() everywhere. Don’t do it - I do not class that as part of the API and it was a horrible object that allowed me to be lazy. v2 is about stopping me being lazy.

You shouldn’t do it anyway, but you will not be able to do it at all in v2, because the Nucleus object has been deleted. Please use the API. If there is something missing from the API that you wish to use, please open a Github issue.

MODIFIED: The location of nearly everything

To try to make things a little more sane, all APIs are now classified by their module or overreaching theme first, rather than whether they are a service, event etc. This should make it simpler to see what APIs are available for each module.

MODIFIED: TeleportResults is now TeleportResult, an enum. Other CatalogTypes are now Suppliers

TeleportResult is now an enum. Other CatalogTypes are now represented by Suppliers to remove reliance on hacky reflection techniques.

MODIFIED: The Kit API has been updated

A failed redemption will no longer throw a KitRedeemException. Instead, a KitRedeemResult will be returned and that will tell you if about the success (or failure).

You can also now get the status of a cooldown for a Kit/User combination.

REMOVED: NucleusMessageTokenService has been removed in favour of the SpongeAPI 7.3 placeholder solution

The message token service has been completely removed, Nucleus now supports the SpongeAPI 7.3 central placeholder system.

Nucleus Gluon v1 will no longer work for supporting placeholder API tokens.

REMOVED: Nucleus MessageChannels

These will be restored in a marker capacity only

In order to enable Nucleus formatting in chat events and to avoid future conflicts with other plugin message channels, Nucleus will now apply its formatting during the MessageChannelEvent.Chat event, and will no longer use MessageChannels for formatting. Nucleus will dynamically create message channels during the LATE priority.

As a result, no API for message channels is available in the API.

REMOVED: NucleusModuleService

The NucleusModuleService has been removed. Plugins wishing to disable modules should listen to the NucleusModuleEvent.AboutToConstruct event instead.

MODIFIED: All kinds of stuff

Please take a look through the API yourself for now. It’s all subject to change, but I have tried to add sensible documents. I will flesh out this section once we approach Beta.

For Developers considering contributing to Nucleus

Nucleus’ biggest changes have happened in this area. v2 no longer uses the static Nucleus object, but instead uses Guice and DI to create a series of cross cutting concerns to provide Nucleus wide actions. Commands, listeners and tasks should all have INucleusServiceCollection injected into themselves for access to these systems.

MODIFIED: Nucleus now uses Gradle 5.6.4

We have jumped from Gradle 4.10 to 5.6.4, as this is the last version that the SpongeGradle plugin has been tested with.

MODIFIED: Nucleus Implementation has been moved to the nucleus-core subproject

This gives a cleaner separation of the project, and allows for other sub projects to be added more easily. The root project now handles project wide actions only.

MODIFIED: Nucleus now uses the Kotlin DSL

The build scripts have been rewritten in Kotlin to improve type safety and being some more order to the scripts.

For more information, have a look around our documentation site at https://v2-beta.nucleuspowered.org/docs.

General Notes