Skip to content

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 ​

java
FeatherBoardPlugin featherBoard =
    (FeatherBoardPlugin) getServer().getPluginManager().getPlugin("FeatherBoard");
GameManager games = featherBoard.getGameManager();

The GameManager exposes:

MethodDescription
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.

java
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 ​

HookWhen
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:

OptionDefaultDescription
TPS20Target updates per second. -1 disables the game loop.
GLOBAL_CANVAStrueShare one canvas between players.
SCREEN_WIDTH / SCREEN_HEIGHTcanvas-dependentCanvas size.
MINIMUM_PLAYERS / MAXIMUM_PLAYERS1Lobby limits.
ENABLEDtrueWhether the game is available.
VISIBLEtrueWhether the game appears in menus.
RESOURCE_PACKnoneA resource pack required by the game.
BACKGROUNDOPT_OUTBackground rendering choice.

Players and input ​

TypeUse
GamePlayerA player inside a game, with game-specific state.
GamePlayerStatePer-player state and input listeners.
KeyDownEvent, KeyUpEventKeyboard input.
MouseClickEvent, MouseMoveEventMouse input.
Canvas / CharacterCanvasDrawing 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:

text
/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:

text
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.GameManager
  • org.featherboard.api.game.Game
  • org.featherboard.api.game.GameInformation
  • org.featherboard.api.graphics.Canvas

Browse them at git.mvdw-software.com/plugins/featherboard-api.

Released under a proprietary license. FeatherBoard is not affiliated with Mojang or Microsoft.