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
@ray73864
Sweet. Let me know if there are any more issues.
@phybros
yep, that fixed it.
@ray73864
Change the line where it says
$transport = new TFramedTransport($socket);
to
$transport = new TBufferedTransport($socket);
When version 0.5 is released, you will need to use TFramedTransport
So i've done all that, i've got the example set up on my bukkit server, but when i click on 'get server version' it responds with the following:
I have changed the username, password and salt in the example page and in the swift config.yml file.
the php page is at: http://www.mcaddictgallery.info/thrift_test.php
@ray73864
Yeah, if you use the link from the Apache Thrift website (http://thrift.apache.org/download) The file that it points to is indeed corrupt (or the way it is transferred is all screwed). But if you download it from the Apache Archive website, it's all good.
Let me know how it goes!
@phybros
Ahh, thanks for that. Strange that you recommend the .tar.gz file, a friend of mine downloaded it onto his computer the other day and the only thing it had in it was a binary.
I tried downloading it twice, and both times WinRAR said the archive was corrupt.
@ray73864
You're right, the PHP example page was a lacking a little detail. Check it again for a working example with some more info. Basically, do the following:
You can also check out the example project I made just for you at https://github.com/phybros/swiftapi-example-php
Could you please elaborate a bit more on the php example?
I generated my php stuff for it, have a 'gen-php' folder with Errors and SwiftApi folders in that.
However, when i look at the 'SwiftApi.php' file, it includes 'Thrift.php', are there things i am missing? Steps i haven't taken?
@breezeyboy
Thanks for checking it out. It is still very beta, but I'm working on it! Could always use some testers.
sounds nice, ill look into coding with it