-
Notifications
You must be signed in to change notification settings - Fork 0
API
For developers looking to use the API, Maven is most supported however Gradle should work as well.
Maven:
<dependencies>
<!-- ... -->
<dependency>
<groupId>co.dotarch.paper</groupId>
<artifactId>x</artifactId>
<version><!-- Latest version number --></version>
<scope>provided</scope>
</dependency>
<!-- ... -->
</dependencies>Gradle:
compileOnly 'co.dotarch.paper:x:<!-- Latest version number -->' // The full Spigot server with no shadowing. Requires mavenLocal.Note: I haven't tried using this with Gradle, if this is wrong/broken please PR the correct usage. Sorry - I don't really use gradle XD
Before continuing, take a look at ExamplePlugin for an idea of how to set up a DotX-enabled plugin properly.
VConfig is a way for plugin developers to support hot-swapping config options on the fly. If you design a feature with VConfig in mind, it will be much easier and cleaner to use. If you design it without VConfig in mind, it may still be possible to utilize VConfig with some refactoring.
VConfig starts in DotPlugin.java:
public void onEnable() {
...
// Load vConfigs
for(String filename : getConfigFilenames())
{
// Pulls the filename and ensures it has been saved before loading
var vConfigFile = new File(getDataFolder(), filename);
if (!vConfigFile.exists()) {
vConfigFile.getParentFile().mkdirs();
saveResource(filename, false);
}
// Retreive the file
var vConfigUnderlying = new YamlConfiguration();
try {
vConfigUnderlying.load(vConfigFile);
} catch (IOException | InvalidConfigurationException e) {
e.printStackTrace();
}
// Set up the VirtualizedConfiguration
virtualConfigs.put(filename, new VirtualizedConfiguration(
vConfigUnderlying,
filename,
this
));
}
...
}In essence, every configuration file in your plugin that has an entry in YourPlugin::getConfigFilenames()
will have a VirtualizedConfiguration object saved that you can access at any time via YourPlugin::getVConfig().
Every key in any given config file that has been loaded into a VirtualizedConfiguration will have an associated VirtualConfigEntry.
The magic of VConfig happens when you hold onto the references for those entries in the classes you're working on.
package com.example.dotX.whatever;
public class VConfigExample()
{
private ExamplePlugin plugin;
private final VirtualConfigurationEntry arbitrary;
// No magic strings please! I don't like string theory!
String ARBITRARY_NUMBER_PATH = ".arbitrary-number";
public MathVConfigExample(ExamplePlugin plugin, String section)
{
this.plugin = plugin;
// Get the correct virtual configuration for this class,
// as defined in ExamplePlugin::getConfigFilenameForClass
var vConfig = DotChat.instance().getVConfig(
DotChat.instance().getConfigFilenameForClass(this.getClass())
);
// Get the entry for the value we're looking for.
arbitrary = vConfig.getEntry(section + ARBITRARY_NUMBER_PATH);
}
public double multiplyWithArbitrary(double number)
{
// This now dynamically uses the correct value based on the VConfig.
var arbitrary = this.arbitrary.getDouble();
return arbitrary * number;
}
}With this example class, you are able to initialize a new MathVConfigExample in ExamplePlugin::onEnable() and pass the config section it will base on.
From there, it will automatically load the correct value every time you call multiplyWithArbitrary.
VConfig is ready to go as soon as super.onEnable() is called within your onEnable().
outline (todo)
When designing with VConfig, be cautious which items are handled via a regular VConfig option. For example, removing and renaming configuration sections will break things unless you listen to the VirtualConfigurationEvent for the section being removed or renamed. Adding sections should be handled similarly.
DotPlayer is a wrapper around the Spigot player. DotPlayers have utility methods for assigning and managing data associated with the player.
To get a DotPlayer for a given player player, use <any DotPlugin>.api().players().get(player);.
DotPlayers have properties that are backed by the database.
- To check if a player has a property:
dotPlayer.hasProperty(key) - To get the value of a property:
dotPlayer.getProperty(key, defaultValue) - To write the value of a property:
dotPlayer.writeProperty(key, defaultValue, save: true)- If you are looking to write more than one property, pass false at the end of writeProperty to cancel saving. Omit the false from the last property written to save them all to database.
- To delete a property:
dotPlayer.deleteProperty(key, save: true)- Similarly with writeProperty, pass false instead of omitting the boolean to allow more efficient deletion of large numbers of properties.
DotPlayers also have a separate set of properties, called Transient Properties. These properties are always cleared whenever the player relogs or the server restarts.
-
To check if a player has a transient property:
dotPlayer.hasTransient(key) -
To get the value of a transient property:
dotPlayer.getTransient(key, defaultValue) -
To write the value of a transient property:
dotPlayer.writeTransient(key, defaultValue) -
To delete a transient property:
dotPlayer.deleteProperty(key) -
DotObjects
- Key-based retrieval
- Type-based retrieval
- Setting properties
- Deleting properties
- Deleting objects
-
DotBlock
- todo?
DotX has multiple event types to help you with managing DotX features.
DotSignalEvents are fired whenever something noteworthy occurs in any DotX-enabled plugin. Noteworthiness is determined by the developer of the plugin(s).
DotSignalEvents contain information on what plugin they originated from, and a keystore similar to a DotObject containing the properties of the signal.
Signals are generally used to communicate things to featurepacks or other plugins that do not necessarily depend on the plugin listening to the signal. For example, most featurepacks work based on a DotSignalEvents system where one is fired and the result of the featurepack's operation(s) is saved in a key on the signal that can be retrieved after the event is fired.
This event fires whenever a given DotObject has been loaded from the database into the cache.
This event fires whenever a given DotPlayer is loaded, which always happens whenever a player logs onto the server.
Whenever a VirtualConfiguration is updated in any way, a VConfigurationEvent is fired with metadata about what has changed. Use these to listen to advanced events within configuration files that your plugin needs to be aware of, like whenever sections are created or destroyed.