forked from mfnalex/Spigot-UpdateChecker
-
Notifications
You must be signed in to change notification settings - Fork 0
/
SpigotMC Description.txt
181 lines (143 loc) · 9.08 KB
/
SpigotMC Description.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
[B]Hi everyone :)[/B]
Today I wanna show you how to get an awesome and fancy Update Checker for your plugins [B]in basically one line of code[/B] (really!), but it's also extremely powerful and customizable!
[SIZE=2]I once posted something similar as a resource in this forum, but the old resource is basically useless compared to this, so I made another thread.[/SIZE]
[B]Updates:[/B]
[LIST]
[*][B]1.2.1:[/B] Fixed checkNow(), checkNow(CommandSender...) and stop() not returning the instance
[*][B]1.2.0:[/B] Detects whether the currently used version is newer than the version found by the UpdateChecker
[*][B]1.1.0:[/B] Added Consumers (onSucces, onFail) for custom behaviour without Event Listeners - Thanks [USER=228867]@Nemo_64[/USER]
[/LIST]
[SIZE=6][B]Overview[/B][/SIZE]
[B]GitHub[/B]: [URL]https://github.com/JEFF-Media-GbR/Spigot-UpdateChecker[/URL]
The SpigotUpdateChecker is a very easy to use library for you to add a perfectly working update checker to your plugins. [B]Scroll all the way to the bottom for maven information, JavaDocs and a complete Example Plugin![/B]
[CENTER][IMG]https://api.jeff-media.de/img/updatechecker2.png[/IMG][/CENTER]
[SIZE=6][B]Features[/B][/SIZE]
You can issue manual and repeated update checks and send the result as ingame message to specific players and/or have them printed to the console.
All checks are done asynchronously. When the check is done, a custom event is called. The update checker itself listens to it and can automatically notify Operators on Join or players with a specific permission.
Of course, you can also just listen to the UpdateCheckEvent yourself to do whatever you like once a new version is detected.
It is also possible to define two download links if your plugin is available as both, a free and paid version, and you can add links to your donation page and changelog.
You can either provide all those links, including to the API endpoint where the latest version is checked yourself, or just provide the SpigotMC Resource ID of your plugin for the Update Checker to get those links automatically.
[SIZE=6][B]Example[/B][/SIZE]
To get a working UpdateChecker, this is already enough:
[CODE=Java]public class MyPlugin extends JavaPlugin {
// To get the Resource ID, look at the number at the end of the URL of your plugin's SpigotMC page
private static final int SPIGOT_RESOURCE_ID = 59773;
@Override
public void onEnable() {
UpdateChecker.init(this, SPIGOT_RESOURCE_ID)
.checkEveryXHours(24) // Check every 24 hours
.checkNow(); // And check right now
}
}[/CODE]
The code above will print a message to the console once a new version is available and also send a message to every OP joining the server. If no new version is found, no message will be sent. The whole UpdateChecker initialization would easily fit in one line, anything more is not needed.
But, of course, there are many more options you can use. For example:
[CODE=Java]public class MyPlugin extends JavaPlugin {
private static final int SPIGOT_RESOURCE_ID = 59773;
@Override
public void onEnable() {
UpdateChecker.init(this, "https://api.jeff-media.de/chestsort/latest-version.txt") // A link to a URL that contains the latest version as String
.setDownloadLink("https://www.chestsort.de") // You can either use a custom URL or the Spigot Resource ID
.setDonationLink("https://paypal.me/mfnalex")
.setChangelogLink(SPIGOT_RESOURCE_ID) // Same as for the Download link: URL or Spigot Resource ID
.setNotifyOpsOnJoin(true) // Notify OPs on Join when a new version is found (default)
.setNotifyByPermissionOnJoin("myplugin.updatechecker") // Also notify people on join with this permission
.setUserAgent(new UserAgentBuilder().addPluginNameAndVersion())
.checkEveryXHours(0.5) // Check every 30 minutes
.checkNow(); // And check right now
}
}[/CODE]
[SIZE=6][B]Differentiating between free and paid versions[/B][/SIZE]
Now imagine you have two versions of your plugin. One free version and a paid version with extra features, like my AngelChest Free and AngelChest Plus plugin. If both plugins share the same codebase and only decide on runtime whether to unlock the premium features, you can easily get something like this working:
Users of the free version will get links to both versions, so they can see the advantages of your paid version, while we don't want to send the free version link to users who already bought the paid version. The Update Checker uses SpigotMC's Premium Resource Placeholders to detect whether a server is using the paid version, but you can also override this detection using [I]UpdateChecker#setUsingPaidVersion(boolean)[/I].
To achieve this, you can just do this:
[CODE=Java]public class MyPlugin extends JavaPlugin {
private static final int ANGELCHEST_FREE = 60383;
private static final int ANGELCHEST_PLUS = 88214;
@Override
public void onEnable() {
UpdateChecker.init(this, "https://api.jeff-media.de/angelchest/latest-version.txt")
.setFreeDownloadLink(ANGELCHEST_FREE)
.setPaidDownloadLink(ANGELCHEST_PLUS)
.setNameFreeVersion("Free") // Optional. It's the suffix for the download links
.setNamePaidVersion("Plus") // when both links are shown.
.checkNow();
}
}[/CODE]
Users of the free version will now see both links:
[CENTER][IMG]https://api.jeff-media.de/img/updatechecker1.png[/IMG][/CENTER]
Users of the paid version will however only get the paid version's download link, just like in the screenshots at the top.
[SIZE=6][B]Using Consumers[/B][/SIZE]
You can use Consumers to change the behaviour of the Update Checker without registering an Event Listener. Thanks [USER=228867]@Nemo_64[/USER] for the Pull request! Example:
[CODE=Java]public class MyPlugin extends JavaPlugin {
@Override
public void onEnable() {
UpdateChecker.init(this, "https://api.jeff-media.de/angelchest/latest-version.txt")
.setDownloadLink("https://www.chestsort.de")
.onSuccess((commandSenders, latestVersion) -> {
for(CommandSender sender : commandSenders) {
sender.sendMessage("This code will run after the update check was successfull.");
}
})
.onFail((commandSenders, exception) -> {
for(CommandSender sender : commandSenders) {
sender.sendMessage("This code will run after the update check failed.");
}
})
.setNotifyRequesters(false) // Do not show the default messages, instead only run our custom consumers
.checkNow();
}
}[/CODE]
[SIZE=6][B]Maven[/B][/SIZE]
The UpdateChecker is available in my public repository:
[CODE=HTML]<repositories>
<repository>
<id>jeff-media-gbr</id>
<url>https://repo.jeff-media.de/maven2/</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>de.jeff_media</groupId>
<artifactId>SpigotUpdateChecker</artifactId>
<version>1.2.0</version> <!-- Check on GitHub for the latest version -->
<scope>compile</scope>
</dependency>
</dependencies>[/CODE]
Please note that you will also have to shade and relocate the UpdateChecker into your .jar file:
[CODE=HTML]<build>
...
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.1</version>
<configuration>
<relocations>
<!-- Using the maven-shade-plugin to shade and relocate the UpdateChecker -->
<!-- Replace "your.package" with your plugin's package name -->
<relocation>
<pattern>de.jeff_media.updatechecker</pattern>
<shadedPattern>your.package.updatechecker</shadedPattern>
</relocation>
</relocations>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>[/CODE]
[B]Failing to relocate the package will make the UpdateChecker throw an exception, so CHANGE IT![/B]
[SIZE=6][B]JavaDocs and Example plugin[/B][/SIZE]
JavaDocs are available here: [URL]https://repo.jeff-media.de/javadocs/SpigotUpdateChecker/[/URL]
Example plugin: [URL]https://github.com/JEFF-Media-GbR/Spigot-UpdateChecker-Example[/URL]
GitHub: [URL]https://github.com/JEFF-Media-GbR/Spigot-UpdateChecker[/URL]
[SIZE=6][B]Thanks for reading![/B][/SIZE]
That's all! You can check the JavaDocs and the linked example plugins to learn about this thing. I hope someone finds it useful, I spent at least 5 hours making this today so hopefully I am not the only one who would find it useful :)
Have a nice day everyone!