SwiftApi
What is SwiftApi?
SwiftApi is an Apache Thrift based API for CraftBukkit Minecraft servers. This API allows simple calls to Bukkit methods over the internet using your favorite programming language. This plugin acts as the server component, allowing you to write client programs/websites/apps that can talk to your CraftBukkit server in almost any programming language!
SwiftApi 2.0
SwiftApi-2.0-alpha is now available for download together with SwiftApiVault-1.0-alpha. Check out the wiki for more information.
What can you do with it?
Basically, SwiftApi allows you write awesome code and apps that can talk to and control your Minecraft server.
An example of such an app is MineCenter. Check it out at http://minecenter.org
Configuration Options
Edit the plugins/SwiftApi/config.yml file to your liking.
The most important options are:
# Authentication Information (CHANGE THESE) username: admin password: password salt: saltines
Leaving these at default would make it easy for an attacker to use this API on your server.
Creating a Client App
Once you have downloaded the Apache Thrift compiler, you can create a client app in a few lines of code.
Check out the example PHP project here: https://github.com/phybros/swiftapi-example-php
Try the C#.NET/VB.NET tutorial here: http://dev.bukkit.org/server-mods/swiftapi/pages/examples/c-net-vb-net/
Generate the Client Library
You can generate the client library (example is in C#) by typing
thrift -r --gen csharp SwiftApi.thrift
The -r option tells the compiler to generate code for all files (including ones that are referenced in SwiftApi.thrift with the include directive. The gen csharp option tells the compiler to generate C# code. This command will leave you with a gen-csharp directory with all the code you need to connect to a server running the SwiftApi plugin.
Include the Code in your App
If you're using C#, you can just drag all the source files right into your client app to use them, or alternatively you could create a new project with the generated files to keep your code and the generated code seperate.
Examples
Visit the Examples page for examples of how to use the code.
Here's an example in C#:
//open a connection to a server running SwiftApi TSocket socket = new TSocket("your.bukkitserver.org", 21111); socket.Open(); //create a new SwiftApi client object TBinaryProtocol protocol = new TBinaryProtocol(new TFramedTransport(socket)); SwiftApi.Client client = new SwiftApi.Client(protocol); //get the server version and output it Console.WriteLine("Server Version: " + client.getServerVersion(authString)); //close the connection socket.Close();
Because the code is based on Apache thrift, you have access to many of the complex types in the CraftBukkit API, such as the Player object.
This example is in C#, but the thrift compiler is able to create libraries for almost ANY programming language.
Visit the Examples page for examples in some other languages
Available Programming Languages
As of version 0.9.0 of Apache Thrift, the following languages are available:
- Actionscript 3 (AS3)
- C (using GLib)
- C
- C#
- Cocoa (Objective-C on Mac OS and iOS)
- Delphi
- Erlang
- Go
- Haskell
- Java
- Javascript
- OCaml
- Perl
- PHP
- Python (including Twisted async support)
- Ruby
- Smalltalk
Code
Think you can improve SwiftApi? Fork the repo on Bitbucket and submit a pull request!
Repo URL: https://bitbucket.org/phybros/swiftapi
Notes
This plugin sends anonymous usage statistics to http://mcstats.org/
To opt out, set opt-out to true in plugins/PluginMetrics/config.yml
@deradic
All good ideas. Do you know java? Want to help? :)
One issue that I'm aware of is that the size of the SwiftApi jar is quite large. Partly due to shading the thrift library into it, and partly due to the fact that the thrift-generated code is very long and verbose.
Basically, any time you add a new thrift method, it adds about 100k to the jar size (ish). The upcoming 0.9.2 release of thrift might address some of that, but we'll see.
So anyway, if we add all the vault methods as well, it might get VERY large unless we can come up with a smart and generic way to pass method calls onto other plugins. Something along the lines of:
So you'd call it like:
This way, SwiftApi only gets one extra method, but grants access to a whole world of other plugins.
But I'm not familiar enough with the Vault or Essentials API to make an informed decision about that.
Thoughts anyone?
Seems Essentials is also providing an API with awesome functionality to have remote.
<<reply 2272604="">>
And if im not mistaken, you can also git clone the entire vaultapi and integrate it directly into your project, which will remove the need to install it seperately etc etc
I'd say implementing this would without doubt make this the de-facto remote managing plugin for bukkit servers (if not already! lol :D)
Because the API implements sending server commands and getting the output, practicly everything is already possible with some regex matching of output. However, there's some thing that would greatly improve the overall plugin and should be relatively easy to implement (as far as i understood by checking up on some code)
Vault is the second most installed plugin on Bukkit servers. As far as i can see, Vault provides an excelent API to manage some specific tasks that would be interesting to see in the SwiftAPI. If im correct, the VaultAPI interfaces with many other addons as can be seen here.
Integrating all the VaultAPI commands and making Vault optional will introduce a very big range of extra services that would be interesting for web-services i am developing (think web-shop that will set permissions, vault items, item sets, etc) while still giving access to the core SwiftApi services if Vault is not installed.
VaultAPI provides chat, economy, item/iteminfo and permissions functionality. If you look at the VaultAPI javadocs you can see all the nice goodies it provides. Having this implemented would be SOO awesome. And because the VaultAPI handles most of the internal stuff, i think it sould be fairly easy to implement.
In any case, i hope that this is all correct and you feel this functionality belongs in the API. It would greatly increase the SwiftAPI use cases for my project, and im sure for many others aswell.
@deradic
Great to hear! Any new features you'd like to see?
<<reply 2264220="">>
Awesome work. Tested my apps + server; everything works and i haven't had to modify a single thing.
Thanks!
Hooray everyone - finally figured it out. New 1.7 version just needs to be approved by bukkit mods and we'll have a Bukkit 1.7.x compatible version of SwiftApi!
@deradic
Really great work - the PHP wrapper looks really fluent and has a great level of abstraction. Once I get SwiftApi's console working with 1.7 I will push an update out
<<reply 2243348="">>
<<reply 2252304="">>
And the web-console.
Laravel Bukkit Console - GitHub
Laravel Bukkit Console - Packagist
The console is really just an example, nothing fancy. Is very easy to implement outside of Laravel aswell.
<<reply 2243348="">>
Here's the initial release. Have included doc's on git hub page.
GitHub Repo
Packagist
I have also written a web-based console using JS/PHP for my cms. I'm gonna put that up as laravel package aswell when im done converting. I will post the links here when it's up.
@Unreal852
PM'd to you
Can someone send me the Client Library because thrift don't start :(
@deradic
Awesome stuff! Glad to hear that this project is proving useful to some people.
Yeah go for it (packagist) - let me know what the package name ends up being and I can include it in the readme on the repo, and/or in the project description here.
I am currently working on a cms-like application for minecraft servers with some serious admin tools. After a lot of searching and trying several options, my conclusion is that your plugin is the best solution for my needs. It's fricking awesome and easy to use/implement. I've currently ported the PHP example to a Laravel package, took me 15 minutes. Everything works just perfect (using the 1.6.4 version) and i can build all the admin features i wanted.
It's great to hear you have plans to continue this. Thank you for putting effort into maintaining this. Very much appreciated.
Would it be alright if i put the package on packagist?
i still look everyday if you updated it. Are you still working on an update? :)
Hey, good job, i like this plugin. Almost all works fine. I'm programming currently a Bukkit-Server-Launcher using vb.net. I'm really happy to see that you upgrade it :)
@Frankyi9
Nice, do you have a link to your project?
Plan to upgrade SwiftApi to latest RB very soon - stay tuned
I love this plugin. :) I'm using it to integrate web-based solutions like a ticket system with ingame messages (sending mail to player). I would be happy if you still develop this nice plugin! :)
@RyanCouch
Depends - is anyone actively using it? My statistics tell me it's installed on 79 servers
Are you still working on this?