Game API
ArcadeBoard games draw on the scoreboard. They are packaged as separate jars in plugins/FeatherBoard/games/ and loaded by FeatherBoard's game module. This page is an overview of the public entry points; the source is the reference for the full lifecycle.
Advanced topic
The game API is larger and less stable than the scoreboard API. Pin the FeatherBoard version you build against, and test a game on a staging server before deploying it.
Getting the game manager
FeatherBoardPlugin featherBoard =
(FeatherBoardPlugin) getServer().getPluginManager().getPlugin("FeatherBoard");
GameManager games = featherBoard.getGameManager();The GameManager exposes:
| Method | Description |
|---|---|
getAvailableGames() | Games discovered from installed jars. |
getRunningGames() | Games that are currently running. |
getOnlinePlayers() | Players currently in a game. |
getGameByName(String name) | Look up game information. |
getGamePlayer(OfflinePlayer player) | The game profile for a player. |
isPlaying(GamePlayer player) | Whether the player is in a game. |
playGame(GamePlayer player, GameInformation game) | Start a game for a player. |
switchGame(...) | Move a player between games. |
getGameLobbies() | Open lobbies. |
createGameLobby(Game game, GamePlayer player) | Create a lobby. |
getTopStatistics(game, type, interval, amount) | Leaderboard data. |
Writing a game
A game extends Game<T extends Canvas> and implements loop(). The type parameter selects the canvas implementation, for example CharacterCanvas for a text scoreboard.
import org.featherboard.api.FeatherBoardPlugin;
import org.featherboard.api.annotations.*;
import org.featherboard.api.game.Game;
import org.featherboard.api.game.GameOption;
import org.featherboard.api.graphics.CharacterCanvas;
@GameName("mygame")
@GameDisplayName("My Game")
@GameDescription("A minimal ArcadeBoard game")
@GameAuthor("Your Name")
@GameVersion("1.0.0")
@GameControls("WASD to move")
public final class MyGame extends Game<CharacterCanvas> {
public MyGame(FeatherBoardPlugin plugin) {
super(plugin);
setOption(GameOption.TPS, 10);
setOption(GameOption.SCREEN_WIDTH, 30);
setOption(GameOption.SCREEN_HEIGHT, 12);
setOption(GameOption.MINIMUM_PLAYERS, 1);
setOption(GameOption.MAXIMUM_PLAYERS, 4);
}
@Override
public void loop() {
// Called on the game thread, at the configured TPS.
// Update game state here; drawing happens through the canvas.
}
}The annotations populate GameInformation (name, display name, description, author, version and controls). They are read reflectively when the game is loaded.
Lifecycle hooks
| Hook | When |
|---|---|
onGameStart(GameStartEvent event) | Before the game loop starts. |
onGameEnd(GameEndEvent event) | When the game stops. |
onPlayerJoin(GamePlayerJoinEvent event) | A player is added. |
onPlayerLeave(GamePlayerLeaveEvent event) | A player leaves or quits. |
Events are cancellable where the event class allows it. A game with an uncaught error is stopped automatically to avoid log spam.
Options
GameOption controls the game runtime:
| Option | Default | Description |
|---|---|---|
TPS | 20 | Target updates per second. -1 disables the game loop. |
GLOBAL_CANVAS | true | Share one canvas between players. |
SCREEN_WIDTH / SCREEN_HEIGHT | canvas-dependent | Canvas size. |
MINIMUM_PLAYERS / MAXIMUM_PLAYERS | 1 | Lobby limits. |
ENABLED | true | Whether the game is available. |
VISIBLE | true | Whether the game appears in menus. |
RESOURCE_PACK | none | A resource pack required by the game. |
BACKGROUND | OPT_OUT | Background rendering choice. |
Players and input
| Type | Use |
|---|---|
GamePlayer | A player inside a game, with game-specific state. |
GamePlayerState | Per-player state and input listeners. |
KeyDownEvent, KeyUpEvent | Keyboard input. |
MouseClickEvent, MouseMoveEvent | Mouse input. |
Canvas / CharacterCanvas | Drawing surface. |
Register input with addKeyListener, addMouseListener, or the individual addKeyDownListener / addMouseClickListener methods. Game loops run on an asynchronous thread; schedule Bukkit API calls back to the main thread.
Installing games
Games are jars in plugins/FeatherBoard/games/. The game commands can load and manage them:
/fb game list
/fb game manage info <game>
/fb game manage add <game>
/fb game load <file>
/fb game reload <game>When a game is loaded, its annotated information and lobby become available through the GameManager. Players start a game with /fb game play <game>.
Game permissions
GameInformation.hasPermission(Player) checks the game-specific nodes:
FeatherBoard.games.play.*
FeatherBoard.games.play.<gamename>The command tree separately uses featherboard.games.play, featherboard.games.manage, featherboard.games.settings and featherboard.developer. Grant the nodes that match how your players access games.
Source
The interfaces live in the API repository:
org.featherboard.api.GameManagerorg.featherboard.api.game.Gameorg.featherboard.api.game.GameInformationorg.featherboard.api.graphics.Canvas
Browse them at git.mvdw-software.com/plugins/featherboard-api.
