相依注入

Sponge 使用相依注入(Dependency Injection)來為插件提供 API 的實例。相依注入允許插件指定幾個將在建構後被注入的 API 型態

注入型態的臨時清單

ConfigDir(在 Path 或 File 加上 annotation)
Used to inject the plugin’s configuration directory: ./config/ OR ./config/<Plugin#id>/ depending on ConfigDir#sharedRoot()
ConfigurationLoader<CommentedConfigurationNode>
Must be annotated with @DefaultConfig. Used to inject a pre-generated ConfigurationLoader for the File of the same annotation.
DefaultConfig(在 Path、ConfigurationLoader 或 File 加上 annotation)
Used to inject the plugin’s specific configuration file: <Plugin#id>.conf
EventManager
Manages the registration of event handlers and the dispatching of events.
File
Must be annotated with either @DefaultConfig or @ConfigDir. Depending on the annotation given this will contain a file reference to the plugins default config file or the directory used for storing configuration files. However, Path (see below) should be preferred.
Game
The Game object is the core accessor of SpongeAPI.
GameRegistry
Provides an easy way to retrieve types from a Game.
GuiceObjectMapperFactory
A tool provided by Configurate to allow easier mapping of objects to configuration nodes. See Serializing Objects for usage.
Injector
com.google.inject.Injector is available from Guice, it is the injector that was used to inject your plugin’s dependencies. You can use it to create a child injector with your own module in order to inject your own classes with either the Sponge provided dependencies listed on this page, or configure your own classes
Logger
Used to identify the plugin from which logged messages are sent.
Path
Must be annotated with either @DefaultConfig or @ConfigDir. Depending on the annotation given this will contain a path reference to the plugins default config file or the directory used for storing configuration files.
PluginContainer
A Plugin class wrapper, used to retrieve information from the annotation for easier use.
PluginManager
Manages the plugins loaded by the implementation. Can retrieve another plugin’s PluginContainer.

注入範例

There are a few references which are difficult to get - or, in some cases, impossible - without injection. While these may not be absolutely vital to every plugin, they’re quite frequently used.

備註

Remember that it’s almost always best practice to inject your objects within the main class, as it’s instantiated with the Guice injector when the plugin is loaded.

Logger

小訣竅

View 記錄與除錯 for a complete guide, specifically for the Logger.

Game

The Game object is the opening for many of the internal functions of SpongeAPI, from the EventManager to the Server and even the Sync/Async Scheduler.

While it is entirely possible to retrieve the Game object through Sponge.getGame(), it is commonly obtained through an injection.

範例 - Field

import com.google.inject.Inject;
import org.spongepowered.api.Game;

@Inject
private Game game;

範例 - Method

private Game game;

@Inject
private void setGame(Game game) {
    this.game = game;
}

範例 - Constructor

For the purpose of this tutorial, 「Apple」 is the class name.
private Game game;

@Inject
public Apple(Game game) {
    this.game = game;
}

設定資料夾

The recommended way to obtain your config file is through Guice, along with the ConfigDir annotation.

小訣竅

If you set sharedRoot to true, your ConfigDir will be the same directory which - potentially - houses the configuration for other plugins. In most cases where grabbing the ConfigDir is required, this should be false.

範例 - Field

import org.spongepowered.api.config.ConfigDir;

import java.nio.file.Path;

@Inject
@ConfigDir(sharedRoot = false)
private Path configDir;

範例 - Method

private Path configDir;

@Inject
private void setConfigDir(@ConfigDir(sharedRoot = false) Path configDir) {
    this.configDir = configDir;
}

範例 - Constructor

For the purposes of this tutorial, 「Orange」 is the class name.
private Path configDir;

@Inject
public Orange(@ConfigDir(sharedRoot = false) Path configDir) {
    this.configDir = configDir;
}

預設設定

The way that @DefaultConfig works is very similar to @ConfigDir. The biggest difference is that @DefaultConfig refers to a specific file, whereas @ConfigDir refers to a directory.

小訣竅

View 設定插件 for a complete guide, specifically for @DefaultConfig.