diff --git a/source/about/faq.rst b/source/about/faq.rst index c9a0ff0a25a6..b22603d57643 100644 --- a/source/about/faq.rst +++ b/source/about/faq.rst @@ -46,14 +46,13 @@ There have also been community implementations due to the flexibility of the API (1) **LanternServer**, an open source and compatible Minecraft: Java Edition server that implements SpongeAPI. It does not rely on the vanilla codebase at all, allowing for it be more configurable, open, and performant. While still a work in progress, their project is quite promising and may one day be the choice for servers not - looking to run Forge mods. You can find their project - `on GitHub `_. + looking to run Forge mods. You can find more information `on their website `_ + as well as `on GitHub `_. Where do I get Plugins for Sponge? ---------------------------------- -You can find plugins on the `SpongeForums `_ as well as our -almost complete, official plugin repository, called `Ore `_. +You can find plugins on our official plugin repository, called `Ore `_. What happened to Bukkit? ------------------------ @@ -79,7 +78,7 @@ For Server Owners I'm a Server Owner! How Will Switching to Sponge Affect My Server? ------------------------------------------------------------------ -For an existing Forge server, you will need to download Sponge and place it into the mods folder. The server can then +For an existing Forge server, you will need to download SpongeForge and place it into the mods folder. The server can then be started like any other Forge server. Non-Forge servers may elect to use SpongeVanilla instead, an implementation that does not rely on Forge. There are @@ -112,7 +111,7 @@ What can't I do with Sponge? / Limitations of Sponge? ----------------------------------------------------- Sponge can't be used to create new blocks, textures, mobs on the client-side or any other content which would need -client-side modifications. SpongeAPI won't support sending mods or plugins to the client for now due to security +client-side modifications. SpongeAPI won't support sending mods or plugins to the client due to security concerns. However, you can make use of the ForgeAPI for clients and create Sponge plugins for the server-side. It is even possible to use Sponge on the client-side, but for several tasks mods are still required. diff --git a/source/conf.py b/source/conf.py index f60fe0e1bf4f..59d408b251ee 100644 --- a/source/conf.py +++ b/source/conf.py @@ -91,7 +91,7 @@ javadoc_links = { 'https://jd.spongepowered.org/%s/' % release: ['org.spongepowered.api'], - 'http://configurate.aoeu.xyz/apidocs/': ['ninja.leaping.configurate'], + 'https://configurate.aoeu.xyz/apidocs/': ['ninja.leaping.configurate'], 'https://docs.oracle.com/javase/8/docs/api/': ['java'], 'https://google.github.io/guava/releases/17.0/api/docs/': ['com.google.common'] } diff --git a/source/contributing/guidelines.rst b/source/contributing/guidelines.rst index c15d5a4959c6..fd3cd4de9796 100644 --- a/source/contributing/guidelines.rst +++ b/source/contributing/guidelines.rst @@ -35,8 +35,8 @@ General steps `Minor Issues on GitHub `_. 4. If the issue requires a bigger change you may want to submit the issues without the necessary changes first, so we - can confirm the issue and know that you're working on fixing it. You should also create a WIP (work in process) pull - request prefixed with ``[WIP]`` early so we can already start reviewing them. + can confirm the issue and know that you're working on fixing it. You should also create a draft pull + request or comment with ``~wip`` so we can already start reviewing them. #. Fork the project, clone it and make your changes in an extra branch. diff --git a/source/contributing/implementation/datamanipulator.rst b/source/contributing/implementation/datamanipulator.rst index cd7345120978..1e5b22edf4a9 100644 --- a/source/contributing/implementation/datamanipulator.rst +++ b/source/contributing/implementation/datamanipulator.rst @@ -52,7 +52,7 @@ The following snippet shows the imports/paths for some classes in SpongeCommon t import org.spongepowered.common.data.manipulator.mutable.common.AbstractData; import org.spongepowered.common.data.manipulator.mutable.entity.SpongeHealthData; import org.spongepowered.common.data.processor.common.AbstractEntityDataProcessor; - import org.spongepowered.common.data.util.DataConstants; + import org.spongepowered.common.util.Constants; import org.spongepowered.common.data.util.NbtDataUtil; import org.spongepowered.common.registry.type.data.KeyRegistryModule; @@ -94,20 +94,18 @@ The second constructor must import static com.google.common.base.Preconditions.checkArgument; - import org.spongepowered.common.data.util.DataConstants; - public class SpongeHealthData extends AbstractData implements HealthData { private double health; private double maxHealth; public SpongeHealthData() { - this(DataConstants.DEFAULT_HEALTH, DataConstants.DEFAULT_HEALTH); + this(20D, 20D); } public SpongeHealthData(double health, double maxHealth) { super(HealthData.class); - checkArgument(maxHealth > DataConstants.MINIMUM_HEALTH); + checkArgument(maxHealth > 0); this.health = health; this.maxHealth = maxHealth; registerGettersAndSetters(); @@ -136,10 +134,10 @@ The interface we implement specifies some methods to access :javadoc:`Value` obj public MutableBoundedValue health() { return SpongeValueFactory.boundedBuilder(Keys.HEALTH) - .minimum(DataConstants.MINIMUM_HEALTH) - .maximum(this.maximumHealth) - .defaultValue(this.maximumHealth) - .actualValue(this.currentHealth) + .minimum(0) + .maximum(this.maxHealth) + .defaultValue(this.maxHealth) + .actualValue(this.health) .build(); } @@ -164,9 +162,9 @@ contains a corresponding ``DataQuery``, just use those by passing the ``Key`` di .. code-block:: java public DataContainer toContainer() { - return DataContainer.createNew() - .set(Keys.HEALTH, this.currentHealth) - .set(Keys.MAX_HEALTH, this.maximumHealth); + return super.toContainer() + .set(Keys.HEALTH, this.health) + .set(Keys.MAX_HEALTH, this.maxHealth); } registerGettersAndSetters() @@ -184,29 +182,30 @@ by ``AbstractData``, but we must tell it which data it can access and how. There .. code-block:: java - private void setCurrentHealthIfValid(double value) { - if (value >= DataConstants.MINIMUM_HEALTH && value <= (double) Float.MAX_VALUE) { - this.currentHealth = value; + private SpongeHealthData setCurrentHealthIfValid(double value) { + if (value >= 0 && value <= (double) Float.MAX_VALUE) { + this.health = value; } else { throw new IllegalArgumentException("Invalid value for current health"); } + return this; } - private void setMaximumHealthIfValid(double value) { - if (value >= DataConstants.MINIMUM_HEALTH && value <= (double) Float.MAX_VALUE) { - this.maximumHealth = value; + private SpongeHealthData setMaximumHealthIfValid(double value) { + if (value >= 0 && value <= (double) Float.MAX_VALUE) { + this.maxHealth = value; } else { throw new IllegalArgumentException("Invalid value for maximum health"); } - + return this; } private void registerGettersAndSetters() { - registerFieldGetter(Keys.HEALTH, () -> this.currentHealth); + registerFieldGetter(Keys.HEALTH, () -> this.health); registerFieldSetter(Keys.HEALTH, this::setCurrentHealthIfValid); registerKeyValue(Keys.HEALTH, this::health); - registerFieldGetter(Keys.MAX_HEALTH, () -> this.maximumHealth); + registerFieldGetter(Keys.MAX_HEALTH, () -> this.maxHealth); registerFieldSetter(Keys.MAX_HEALTH, this::setMaximumHealthIfValid); registerKeyValue(Keys.MAX_HEALTH, this::maxHealth); } @@ -218,7 +217,7 @@ This applies especially for :javadoc:`DataHolder`\s which won't accept negative .. tip:: The validity criteria for those setters are the same as for the respective ``Value`` object, so you might delegate - the validity check to a call of ``this.health().set()`` and just set ``this.currentHealth = value`` if the first + the validity check to a call of ``this.health().set()`` and just set ``this.health = value`` if the first line has not thrown an exception yet. That's it. The ``DataManipulator`` should be done now. @@ -253,13 +252,15 @@ There add a line to register (and create) your used keys. .. code-block:: java - this.register(Key.builder() + import static org.spongepowered.api.data.DataQuery.of; + + this.register("health", Key.builder() .type(TypeTokens.BOUNDED_DOUBLE_VALUE_TOKEN) .id("health") .name("Health") .query(of("Health")) .build()); - this.register(Key.builder() + this.register("max_health", Key.builder() .type(TypeTokens.BOUNDED_DOUBLE_VALUE_TOKEN) .id("max_health") .name("Max Health") @@ -511,9 +512,9 @@ a ``Value`` and its immutable counterpart and three methods to get, set and remo @Override protected MutableBoundedValue constructValue(Double health) { return SpongeValueFactory.boundedBuilder(Keys.HEALTH) - .minimum(DataConstants.MINIMUM_HEALTH) + .minimum(0D) .maximum(((Float) Float.MAX_VALUE).doubleValue()) - .defaultValue(DataConstants.DEFAULT_HEALTH) + .defaultValue(20D) .actualValue(health) .build(); } @@ -539,7 +540,7 @@ Since it is impossible for an ``EntityLivingBase`` to not have health, this meth @Override protected boolean set(EntityLivingBase container, Double value) { - if (value >= DataConstants.MINIMUM_HEALTH && value <= (double) Float.MAX_VALUE) { + if (value >= 0 && value <= (double) Float.MAX_VALUE) { container.setHealth(value.floatValue()); return true; } diff --git a/source/contributing/implementation/debugging/mixin.rst b/source/contributing/implementation/debugging/mixin.rst index e19dae97e953..8156b94baa5d 100644 --- a/source/contributing/implementation/debugging/mixin.rst +++ b/source/contributing/implementation/debugging/mixin.rst @@ -59,7 +59,7 @@ There are a several ways to view the class files from the mixin process. Having the fernflower jar on your runtime classpath will cause the class files to be decompiled as they are created. -* `JD-Gui `_ is a standalone graphical utility that displays Java source codes of class files. +* `JD-Gui `_ is a standalone graphical utility that displays Java source codes of class files. Phases And Environments ======================= diff --git a/source/contributing/implementation/debugging/more.rst b/source/contributing/implementation/debugging/more.rst index e7afc0b75d31..fad9173999f6 100644 --- a/source/contributing/implementation/debugging/more.rst +++ b/source/contributing/implementation/debugging/more.rst @@ -31,5 +31,5 @@ IntelliJ -------- Learn about `Git Integration `_ and `Project -Structure `_ on JetBrains' +Structure `_ on JetBrains' web site. diff --git a/source/plugin/api-versions.rst b/source/plugin/api-versions.rst index 09d31bab8cf2..d23cc5732a90 100644 --- a/source/plugin/api-versions.rst +++ b/source/plugin/api-versions.rst @@ -7,8 +7,8 @@ This page explains which API versions exist, and to which Minecraft version thei +-------------+--------------+----------------+-------------------------------------------+ | API-Version | Release Date | End of Support | Known Implementations (Minecraft Version) | +=============+==============+================+===========================================+ -| *8.0.0* | TBA | TBA | * *SpongeForge (1.13.x)* | -| | | | * *SpongeVanilla (1.13.x)* | +| *8.0.0* | TBA | TBA | * *SpongeForge* | +| | | | * *SpongeVanilla* | +-------------+--------------+----------------+-------------------------------------------+ | 7.2.0 | TBA | TBA | * SpongeForge (1.12.2) | | | | | * SpongeVanilla (1.12.2) | diff --git a/source/plugin/assets.rst b/source/plugin/assets.rst index bee8de6042ab..ad24f5d534c0 100644 --- a/source/plugin/assets.rst +++ b/source/plugin/assets.rst @@ -25,6 +25,8 @@ Alternatively, you can retrieve assets through the ``AssetManager`` class: import org.spongepowered.api.Sponge; + PluginContainer plugin = ...; + Asset asset = Sponge.getAssetManager().getAsset(plugin, "myfile.txt").get(); .. tip:: diff --git a/source/plugin/buildsystem.rst b/source/plugin/buildsystem.rst index 35d12426aee1..eeb24e638d8b 100644 --- a/source/plugin/buildsystem.rst +++ b/source/plugin/buildsystem.rst @@ -64,8 +64,8 @@ your plugin. Continue at :doc:`plugin-identifier` for choosing an identifier for .. _Gradle: https://gradle.org/ .. _Maven: https://maven.apache.org/ -.. _Groovy: http://www.groovy-lang.org/ -.. _Kotlin: http://kotlinlang.org/ +.. _Groovy: https://www.groovy-lang.org/ +.. _Kotlin: https://kotlinlang.org/ .. _`Gradle User Guide`: https://docs.gradle.org/current/userguide/userguide.html .. _`Gradle Java Quickstart`: https://docs.gradle.org/current/userguide/tutorial_java_projects.html .. _`Project Object Model`: https://maven.apache.org/guides/introduction/introduction-to-the-pom.html diff --git a/source/plugin/commands/arguments.rst b/source/plugin/commands/arguments.rst index 9cb6d0eaf332..ad5921c0d087 100644 --- a/source/plugin/commands/arguments.rst +++ b/source/plugin/commands/arguments.rst @@ -61,6 +61,8 @@ Example: Building a Command with Multiple Arguments import org.spongepowered.api.command.spec.CommandExecutor; import org.spongepowered.api.command.spec.CommandSpec; + PluginContainer plugin = ...; + CommandSpec myCommandSpec = CommandSpec.builder() .description(Text.of("Send a message to a player")) .permission("myplugin.command.message") diff --git a/source/plugin/commands/childcommands.rst b/source/plugin/commands/childcommands.rst index 419cce5591ba..d0ee31e455ba 100644 --- a/source/plugin/commands/childcommands.rst +++ b/source/plugin/commands/childcommands.rst @@ -48,6 +48,8 @@ The first alias supplied is the primary one and will appear in the usage message import org.spongepowered.api.Sponge; + PluginContainer plugin = ...; + CommandSpec mailCommandSpec = CommandSpec.builder() .permission("myplugin.mail") .description(Text.of("Send and receive mails")) diff --git a/source/plugin/commands/commandcallable.rst b/source/plugin/commands/commandcallable.rst index 4ec9c118b378..c5308be7b6ea 100644 --- a/source/plugin/commands/commandcallable.rst +++ b/source/plugin/commands/commandcallable.rst @@ -60,7 +60,7 @@ The first step is to create a class for the command. The class has to implement return usage; } - public List getSuggestions(CommandSource source, String arguments) throws CommandException { + public List getSuggestions(CommandSource source, String arguments, @Nullable Location targetPosition) throws CommandException { return Collections.emptyList(); } } @@ -82,6 +82,7 @@ passing your plugin, an instance of the command, and any needed aliases as param import org.spongepowered.api.command.CommandManager; CommandManager cmdService = Sponge.getCommandManager(); + PluginContainer plugin = ...; cmdService.register(plugin, new MyBroadcastCommand(), "message", "broadcast"); .. note:: diff --git a/source/plugin/commands/creating.rst b/source/plugin/commands/creating.rst index 5051cad9cb76..a0970d22931b 100644 --- a/source/plugin/commands/creating.rst +++ b/source/plugin/commands/creating.rst @@ -28,6 +28,8 @@ Example: Building a Simple Command import org.spongepowered.api.text.Text; import org.spongepowered.api.command.spec.CommandSpec; + PluginContainer plugin = ...; + CommandSpec myCommandSpec = CommandSpec.builder() .description(Text.of("Hello World Command")) .permission("myplugin.command.helloworld") diff --git a/source/plugin/commands/service.rst b/source/plugin/commands/service.rst index fe3bff68bd98..ae085b2c53b6 100644 --- a/source/plugin/commands/service.rst +++ b/source/plugin/commands/service.rst @@ -14,16 +14,17 @@ them to the right command handler. To register your command, use the method :javadoc:`CommandManager#register(Object, CommandCallable, String...)` passing your plugin, an instance of the command, and any needed aliases as parameters. -Usually you want to register your commands when the :javadoc:`GameInitializationEvent` is called. If you are registering -the commands from the main plugin class, use ``this`` as the ``plugin`` parameter. +Usually you want to register your commands when the :javadoc:`GameInitializationEvent` is called. .. code-block:: java import org.spongepowered.api.Sponge; import org.spongepowered.api.command.CommandManager; + PluginContainer plugin = ...; + CommandManager cmdManager = Sponge.getCommandManager(); - cmdManager.register(this, myCommandSpec, "alias1", "alias2", "alias3"); + cmdManager.register(plugin, myCommandSpec, "alias1", "alias2", "alias3"); .. note:: diff --git a/source/plugin/configuration/index.rst b/source/plugin/configuration/index.rst index a6cb39449143..1b837dd4d4df 100644 --- a/source/plugin/configuration/index.rst +++ b/source/plugin/configuration/index.rst @@ -113,7 +113,7 @@ specific directory or to ``true`` to get the shared configuration directory. .. note:: - The use of YAML format (http://yaml.org/spec/1.1/) and JSON format (https://www.json.org/) is also supported, but + The use of YAML format (https://yaml.org/spec/1.1/) and JSON format (https://www.json.org/) is also supported, but the preferred config format for Sponge plugins is HOCON. Conversion from YAML (or JSON) to HOCON can be automated by using a :javadoc:`YAMLConfigurationLoader` (or :javadoc:`GsonConfigurationLoader`) to load the old config and then saving it using a :javadoc:`HoconConfigurationLoader`. diff --git a/source/plugin/configuration/loaders.rst b/source/plugin/configuration/loaders.rst index 722f75abfb95..a5db1c31d1a8 100644 --- a/source/plugin/configuration/loaders.rst +++ b/source/plugin/configuration/loaders.rst @@ -145,14 +145,17 @@ You can use :doc:`the Asset API <../assets>` to do this, as shown in the example .. code-block:: java - Sponge.getAssetManager().getAsset(myplugin, "default.conf").get().copyToFile(path, false, true); + PluginContainer plugin = ...; + Path path = ...; + + Sponge.getAssetManager().getAsset(plugin, "default.conf").get().copyToFile(path, false, true); loader = HoconConfigurationLoader.builder().setPath(path).build(); rootNode = loader.load(); For this example it is important to note that the :javadoc:`AssetManager#getAsset(String)` method works relative to the plugin's asset folder. So, if in the above example the plugin ID is ``myplugin``, the ``default.conf`` file must not lie in the jar file root, but instead in the directory ``assets/myplugin``. This example also uses -:javadoc:`Asset#copyToFile(String, boolean, boolean)` which allows an the file creation to override existing +:javadoc:`Asset#copyToFile(Path, boolean, boolean)` which allows the file creation to override existing files only if specified. .. note:: @@ -174,6 +177,8 @@ copying to a file as this will automatically place values that were absent while .. code-block:: java + PluginContainer plugin = ...; + node.mergeValuesFrom(HoconConfigurationLoader.builder() .setURL(plugin.getAsset("default.conf").get().getUrl()) .build() diff --git a/source/plugin/data/custom/datamanipulators.rst b/source/plugin/data/custom/datamanipulators.rst index 09234be08966..3428c3eaeac1 100644 --- a/source/plugin/data/custom/datamanipulators.rst +++ b/source/plugin/data/custom/datamanipulators.rst @@ -12,6 +12,7 @@ Custom DataManipulators org.spongepowered.api.data.key.KeyFactory org.spongepowered.api.data.manipulator.DataManipulator org.spongepowered.api.data.manipulator.ImmutableDataManipulator + org.spongepowered.api.data.manipulator.immutable.common.AbstractImmutableData org.spongepowered.api.data.manipulator.mutable.common.AbstractBoundedComparableData org.spongepowered.api.data.manipulator.mutable.common.AbstractData org.spongepowered.api.data.manipulator.mutable.common.AbstractSingleData @@ -185,7 +186,7 @@ To register a ``DataManipulator`` Sponge has the :javadoc:`DataRegistration#buil .builder(new CustomDataBuilder()) .manipulatorId("my-custom") .dataName("My Custom") - .buildAndRegister(myPluginContainer); + .build(); } .. warning:: @@ -321,8 +322,8 @@ Registering Values ------------------ Next, you'll want to register these so that the :doc:`Keys <../keys>`-based system can reference them. To do this, -implement either :javadoc:`DataManipulator#registerGettersAndSetters()` or -:javadoc:`ImmutableDataManipulator#registerGetters()` depending on whether the data is mutable or not. +implement either :javadoc:`AbstractData#registerGettersAndSetters()` or +:javadoc:`AbstractImmutableData#registerGetters()` depending on whether the data is mutable or not. For each value you must call: diff --git a/source/plugin/economy/practices.rst b/source/plugin/economy/practices.rst index c7aedab90bd0..1ffdfaeba31e 100644 --- a/source/plugin/economy/practices.rst +++ b/source/plugin/economy/practices.rst @@ -32,18 +32,18 @@ This code illustrates what **not** to do: import org.spongepowered.api.service.economy.EconomyService; import org.spongepowered.api.service.economy.account.Account; - PluginContainer pluginContainer = ...; + PluginContainer plugin = ...; EconomyService service = ...; Account account = ...; BigDecimal requiredAmount = BigDecimal.valueOf(20); - EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, pluginContainer).build(); + EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(); // BAD: Don't perform this check if (account.getBalance(service.getDefaultCurrency()).compareTo(requiredAmount) < 0) { // You don't have enough money! } else { // The account has enough, let's withdraw some cash! - account.withdraw(service.getDefaultCurrency(), requiredAmount, Cause.of(eventContext, pluginContainer)); + account.withdraw(service.getDefaultCurrency(), requiredAmount, Cause.of(eventContext, plugin)); } @@ -54,18 +54,21 @@ return :javadoc:`ResultType#ACCOUNT_NO_FUNDS`, or :javadoc:`ResultType#FAILED` i Here's how you **should** withdraw money: .. code-block:: java - + + import org.spongepowered.api.event.cause.Cause; + import org.spongepowered.api.event.cause.EventContext; + import org.spongepowered.api.event.cause.EventContextKeys; import org.spongepowered.api.service.economy.transaction.ResultType; import org.spongepowered.api.service.economy.transaction.TransactionResult; - PluginContainer pluginContainer = ...; + PluginContainer plugin = ...; EconomyService service = ...; Account account = ...; BigDecimal requiredAmount = BigDecimal.valueOf(20); - EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, pluginContainer).build(); + EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(); TransactionResult result = account.withdraw(service.getDefaultCurrency(), requiredAmount, - Cause.of(eventContext, pluginContainer)); + Cause.of(eventContext, plugin)); if (result.getResult() == ResultType.SUCCESS) { // Success! } else if (result.getResult() == ResultType.FAILED || result.getResult() == ResultType.ACCOUNT_NO_FUNDS) { diff --git a/source/plugin/economy/using.rst b/source/plugin/economy/using.rst index 4b608402e3cf..167b133f6aef 100644 --- a/source/plugin/economy/using.rst +++ b/source/plugin/economy/using.rst @@ -80,5 +80,5 @@ Some :javadoc:`Account` methods require variables such as: These are for more advanced uses, but still must be filled in. Below is a list of acceptable default values: * Currency: :javadoc:`EconomyService#getDefaultCurrency()` -* Cause: ``Cause.source(myPlugin).build()`` +* Cause: ``Cause.of(EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(), plugin)`` * Context: ``new HashSet()`` diff --git a/source/plugin/event/causes.rst b/source/plugin/event/causes.rst index 055aa7cd5627..afa1106b50b3 100644 --- a/source/plugin/event/causes.rst +++ b/source/plugin/event/causes.rst @@ -235,6 +235,7 @@ to the cause would be the root cause. EventContext context = EventContext.builder() .add(EventContextKeys.PLAYER_SIMULATED, playerToSimulate.getProfile()) + .add(EventContextKeys.PLUGIN, plugin) .build(); Cause cause = Cause.builder() diff --git a/source/plugin/event/custom.rst b/source/plugin/event/custom.rst index 0605c012ea51..455391808071 100644 --- a/source/plugin/event/custom.rst +++ b/source/plugin/event/custom.rst @@ -85,10 +85,16 @@ Example: Fire Custom Event .. code-block:: java + import org.spongepowered.api.event.cause.Cause; + import org.spongepowered.api.event.cause.EventContext; + import org.spongepowered.api.event.cause.EventContextKeys; import org.spongepowered.api.Sponge; + PluginContainer plugin = ...; + EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(); + PlayerMutationEvent event = new PlayerMutationEvent(victim, PlayerMutationEvent.Mutation.ROTTED_SOCKS, - Cause.source(flardSource).build()); + Cause.of(eventContext, plugin)); Sponge.getEventManager().post(event); if (!event.isCancelled()) { // Mutation code diff --git a/source/plugin/event/filters.rst b/source/plugin/event/filters.rst index a7e266bd0559..a5b147ffc8ce 100644 --- a/source/plugin/event/filters.rst +++ b/source/plugin/event/filters.rst @@ -19,7 +19,6 @@ Event Filters org.spongepowered.api.data.value.mutable.CompositeValueStore org.spongepowered.api.util.Tristate java.lang.Class - java.lang.String Now that you've spent a bit of time working with events you've probably noticed that there are several preconditions that you very commonly check while writing an event listener. Event filters are a group of annotations that assist you by allowing you @@ -151,20 +150,6 @@ contained no players.** :javadoc:`Cause#root()`. It also performs an additional check that the type of the root object matches the type of your parameter. -**@Named** This parameter source annotation tells the event system to find the object with the name specified by the annotation -parameter (This is equivalent to :javadoc:`Cause#get(String, Class)`). Additionally, the found object must match the -type of the parameter. If no object is found meeting these criteria, then your listener is not called. - -**In this example your listener will only be called if there is a player associated with the name** -``NamedCause.OWNER``\ **. The** ``player`` **parameter will be set to that player.** - -.. code-block:: java - - @Listener - public void onInteract(InteractBlockEvent.Secondary event, @Named(NamedCause.OWNER) Player player) { - // do something - } - **@Getter** This parameter source annotation will fetch a getter on the event with the specified name. If the specified getter returns an ``Optional``, ``@Getter`` will automatically unwrap the ``Optional``. diff --git a/source/plugin/event/listeners.rst b/source/plugin/event/listeners.rst index 50cb3a6293ac..7d5aa4b37dd6 100644 --- a/source/plugin/event/listeners.rst +++ b/source/plugin/event/listeners.rst @@ -124,7 +124,7 @@ event listeners, including those registered with ``@Listener`` annotations. .. code-block:: java - MyPlugin plugin = ...; + PluginContainer plugin = ...; Sponge.getEventManager().unregisterPluginListeners(plugin); .. _about_listener: @@ -189,11 +189,16 @@ Example: Firing LightningEvent .. code-block:: java - import org.spongepowered.api.event.SpongeEventFactory; import org.spongepowered.api.event.action.LightningEvent; import org.spongepowered.api.event.cause.Cause; + import org.spongepowered.api.event.cause.EventContext; + import org.spongepowered.api.event.cause.EventContextKeys; + import org.spongepowered.api.event.SpongeEventFactory; + + PluginContainer plugin = ...; + EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(); - LightningEvent lightningEvent = SpongeEventFactory.createLightningEventPre(Cause.source(plugin).build()); + LightningEvent lightningEvent = SpongeEventFactory.createLightningEventPre(Cause.of(eventContext, plugin)); Sponge.getEventManager().post(lightningEvent); .. warning:: diff --git a/source/plugin/permissions.rst b/source/plugin/permissions.rst index 3398f6fcc71c..070f2c34efbe 100644 --- a/source/plugin/permissions.rst +++ b/source/plugin/permissions.rst @@ -103,7 +103,8 @@ Usage-Example import org.spongepowered.api.service.permission.PermissionService; import org.spongepowered.api.text.Text; - Builder builder = permissionService.newDescriptionBuilder(myplugin); + PluginContainer plugin = ...; + Builder builder = permissionService.newDescriptionBuilder(plugin); builder.id("myplugin.commands.teleport.execute") .description(Text.of("Allows the user to execute the teleport command.")) diff --git a/source/plugin/plugin-identifier.rst b/source/plugin/plugin-identifier.rst index dfa9d796708d..b44e2807d2d7 100644 --- a/source/plugin/plugin-identifier.rst +++ b/source/plugin/plugin-identifier.rst @@ -10,7 +10,7 @@ folders for your plugin. .. note:: The plugin ID must be lowercase and start with an alphabetic character. It may only contain alphanumeric characters, dashes or underscores. The plugin name does **not** have such a limitation and can even contain spaces or - special characters. + special characters. It cannot be longer than 64 characters. Keep in mind your plugin ID will be the main identification of your plugin, used in other plugins as dependencies, for your configuration files, as well as other properties stored for your plugin. That's why it is important you always diff --git a/source/plugin/scheduler.rst b/source/plugin/scheduler.rst index fd32db648468..0c16c2701c73 100644 --- a/source/plugin/scheduler.rst +++ b/source/plugin/scheduler.rst @@ -110,6 +110,8 @@ initial delay of 100 milliseconds could be built and submitted using the followi import java.util.concurrent.TimeUnit; + PluginContainer plugin = ...; + Task task = Task.builder().execute(() -> logger.info("Yay! Schedulers!")) .async().delay(100, TimeUnit.MILLISECONDS).interval(5, TimeUnit.MINUTES) .name("ExamplePlugin - Fetch Stats from Database").submit(plugin); @@ -209,6 +211,8 @@ to be thread-safe. .. code-block:: java import org.spongepowered.api.scheduler.SpongeExecutorService; + + PluginContainer plugin = ...; SpongeExecutorService minecraftExecutor = Sponge.getScheduler().createSyncExecutor(plugin); @@ -237,6 +241,8 @@ CompletableFuture_ is a fluent interface which usually has the following three v .. code-block:: java import java.util.concurrent.CompletableFuture; + + PluginContainer plugin = ...; SpongeExecutorService minecraftExecutor = Sponge.getScheduler().createSyncExecutor(plugin); @@ -274,6 +280,8 @@ synchronously using ``Observable#subscribeOn(Scheduler scheduler)``. import rx.Scheduler; import rx.schedulers.Schedulers; + PluginContainer plugin = ...; + SpongeExecutorService executor = Sponge.getScheduler().createSyncExecutor(plugin); Scheduler minecraftScheduler = Schedulers.from(executor); diff --git a/source/plugin/services.rst b/source/plugin/services.rst index 022648df2302..12584e0b2f2e 100644 --- a/source/plugin/services.rst +++ b/source/plugin/services.rst @@ -94,6 +94,8 @@ the interface) and replace your version. .. code-block:: java + PluginContainer plugin = ...; + Sponge.getServiceManager().setProvider(plugin, WarpService.class, new SimpleWarpService()); Other plugins can now access your service through the service manager: diff --git a/source/preparing/text.rst b/source/preparing/text.rst index bebe75c2d4c0..acdd3558c1ab 100644 --- a/source/preparing/text.rst +++ b/source/preparing/text.rst @@ -2,7 +2,7 @@ Installing a Text Editor ======================== -Articles on SpongeDocs are saved as text files in the `reStructuredText `_ markup +Articles on SpongeDocs are saved as text files in the `reStructuredText `_ markup language. Although your operating system's default text editor is likely sufficient for editing these files, installing a different text editor may prove to be useful. diff --git a/source/server/getting-started/configuration/sponge-conf.rst b/source/server/getting-started/configuration/sponge-conf.rst index b7d242394fee..95a68e530443 100644 --- a/source/server/getting-started/configuration/sponge-conf.rst +++ b/source/server/getting-started/configuration/sponge-conf.rst @@ -415,7 +415,7 @@ gameprofile-lookup-batch-size If you are running multiple servers behind the same IP, it is recommended to raise the 'gameprofile-task-interval' setting in order to compensate for the amount requests being sent. Finally, if set to 0 or less, the default batch size will be used. - For more information visit http://wiki.vg/Mojang_API + For more information visit https://wiki.vg/Mojang_API gameprofile-lookup-task-interval The interval, in seconds, used by the GameProfileQueryTask to process queued GameProfile requests. (Default: 4) Note: This setting should be raised if you experience the following error: @@ -915,7 +915,7 @@ This config was generated using SpongeForge build 3442 (with Forge 2705), Sponge # If you are running multiple servers behind the same IP, it is recommended to raise the 'gameprofile-task-interval' setting # in order to compensate for the amount requests being sent. # Finally, if set to 0 or less, the default batch size will be used. - # For more information visit http://wiki.vg/Mojang_API + # For more information visit https://wiki.vg/Mojang_API gameprofile-lookup-batch-size=1 # The interval, in seconds, used by the GameProfileQueryTask to process queued GameProfile requests. (Default: 4) # Note: This setting should be raised if you experience the following error: diff --git a/source/server/getting-started/implementations/spongeforge.rst b/source/server/getting-started/implementations/spongeforge.rst index eb41f7adff44..1c63186c5f9e 100644 --- a/source/server/getting-started/implementations/spongeforge.rst +++ b/source/server/getting-started/implementations/spongeforge.rst @@ -2,7 +2,7 @@ Installing SpongeForge ====================== -SpongeForge integrates `Minecraft Forge `__ so you can also run Minecraft Forge mods. +SpongeForge integrates `Minecraft Forge `__ so you can also run Minecraft Forge mods. In fact, it's more like Sponge itself is a Forge mod that then loads Sponge plugins, but this is a technical detail. Users who do not want to use Minecraft Forge can consider :doc:`SpongeVanilla `. diff --git a/source/server/spongineer/properties.rst b/source/server/spongineer/properties.rst index 3fab49da7d64..7612a37ed245 100644 --- a/source/server/spongineer/properties.rst +++ b/source/server/spongineer/properties.rst @@ -52,8 +52,8 @@ Properties Available | | ``.sponge.debug.out`` folder, named after the class they are altering. | | (boolean, default: false) | | +------------------------------------+---------------------------------------------------------------------------------+ -| **sponge.print_all_catalog_types** | Prints out all registered ``CatalogType`` s and their ``String`` id's at the | -| | end of startup, which is useful for finding out what id's are registered from | +| **sponge.print_all_catalog_types** | Prints out all Sponge provided ``CatalogType`` s and their ``String`` id's | +| | before preInit, which is useful for finding out what id's are registered from | | (boolean, default: false) | vanilla, mods, and plugins for all created ``CatalogType`` s. | +------------------------------------+---------------------------------------------------------------------------------+ | | Prints out a very verbose log entry for every block captured that is processed, | diff --git a/source/versions/versioning.rst b/source/versions/versioning.rst index b10ca709c250..a75f5f0a298f 100644 --- a/source/versions/versioning.rst +++ b/source/versions/versioning.rst @@ -6,7 +6,7 @@ Versioning .. tip:: Sponge follows a format of the SemVer specification in its projects. You can read about general SemVer usage at - http://semver.org. + https://semver.org/. The SpongeAPI and implementations (SpongeForge/SpongeVanilla) follow two different policies. Understanding our versions is a matter of interpreting the SemVer version string. The SpongeAPI version utilizes the *Major* and *Minor* parts in