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
@Vincent1468
Thanks for finding all the issues!
The code at the beginning where you create the SwiftApi.Client object should have an extra step where it sets up a TFramedTransport using the TSocket object like this:
That should sort you out. I fixed the tutorial page. Thanks for finding this!
@phybros
Thanks for telling me that, but now I get this Error. Sorry for the many questions :S
@Vincent1468
Oops, the code on the tutorial page had 2 very important lines missing.
Once you create the client object, you have to open the connection and then close it when you're done:
@phybros
Indeed, thanks I had to rebuild it. but I have one other problem(hopefully the last one), when I debug the application, the reference gets removed. Here are two screenshots from it, before the debug and after. Before and After I've tried creating a new project with the same code and references but the problem is still there.
Edit: after googling I found the solution to this issue, many thanks for your help! Edit(aigan):The thrift is giving errors when im trying to connect, here is a Screenshot
@Vincent1468
For starters, you can delete the Class1.cs file that was automatically added to the SwiftApi project - you don't need it.
Secondly, you probably need to Build the project. Click on Build > Rebuild Solution.
Thirdly, you need to make sure that you Import the namespaces. Add these lines to the top of your Form1 code:
Hope that helps
@phybros
That's helping a lot, thanks. I dragged the files generated by the Thrift to the SwiftApi C# Class Library, then I set all the references. Now I have this: Click for image When I start to code and use SwiftApi, the only thing that comes up is Class1. I think that I did something wrong at the SwiftApi project, but I did everything that's on the page. Do you know how to fix this? :)
@Vincent1468
No, you need to add the generated code as a separate project.
Read this page I just created for more info :)
http://dev.bukkit.org/server-mods/swiftapi/pages/examples/c-net-vb-net/
@phybros
Sorry, im not understanding this. I added the .cs files to the project like this: But I don't understand how to add those files as a reference like you said, could you give some more information about that?
@Vincent1468
No. Once you've created your VB project, you can just do File > Add > Existing Project and find your generated C# project and then add a Project Reference to the C# project in your VB project
@phybros
Thanks, I didn't found the two .thrift files but now I found them on github :) Do you know if I have to convert the C# files to VB files?
@Vincent1468
Visual Basic is definitely available. The app MineCenter is written in VB (http://minecenter.org). You have the right idea though - you generate the C# library and then add that to your project Solution in Visual Studio.
You have to have both Errors.thrift AND SwiftApi.thrift in your C:\ for it to work correctly, that's probably what your problem is.
Is Visual basic also available? it's very simmilair to C#.
Also ive tried to download the C# library and got this: C:\>thrift -r
gen csharp SwiftApi.thrift [FAILURE:C:/SwiftApi.thrift:1] Could not open input file: "C:/SwiftApi.thrift"@Relicum
Nice, sounds awesome! If there's a feature you think is missing, just leave a comment here and I'll see what I can do to add it!
@phybros
Have a million idea's definently an admin front end to control my servers and the others under bungee cord. Also hope possible to control certain parts of custom mini games, I need to look into it a bit more and see the load it takes up. Interested what objects can be controlled though it which will decide what I can use it for.
@Relicum
What are you using SwiftApi for if you don't mind my asking?
Oh yes thanks very much
Version 1.1 is uploaded, built for 1.4.7-R0.1 just waiting on approval
@Linrox
Version 1.0 is up, built against 1.4.6-R0.3
@phybros Thanks Thats awesome. Happy new year to you as mell
@Linrox
Just waiting on approval, the new version should be up shortly...
Happy New Year!