ArcadeBoard

欢迎来到ArcadeBoarde插件百科

插件名
ArcadeBoard

作者
Maximvdw

兼容版本
1.8-1.14

原文
[1]

API

ArcadeBoard API

提醒: 这个版本的API仍在构建中，以下为文档

介绍

ArcadeBoard API的运行方式和其他的游戏API相似。如果你曾经创建过游戏你很可能在这个API中找到对应的设计模式。

游戏位于'games'文件夹内并分在独立的JAR文件内。插件会在开服时加载这些游戏。

当然图像是有限的，然而这个API提供了大量的工具来帮助你拓展图像。这个API最主要的游戏类型名为'Tile based games'。如果你不熟悉这个观念，我推荐你阅读这个: https://en.wikipedia.org/wiki/Tile-based_video_game

总而言之: 你创建的游戏利用了低分辨率光栅。 然而你在光栅里所绘制的每个像素都可以通过资源包来实现高清化。 资源包拓展了API的功能，资源包的详细解释请往下看。

Github: https://github.com/Maximvdw/ArcadeBoard-API

了解主要观念

你需要了解API的三大方面.

1.游戏玩家

加入游戏的玩家称为'GamePlayer'。联机游戏可以让多名玩家同时进行游戏

2.画布

画布为玩家游玩的区域。每名玩家拥有各自的画布，但是你可以设置全局画布来让所有玩家看到同一件事。（等于计分版）

你可以在画布里绘制每一个框架。画布不会在每次更新时重置，你必须重置一部分或是不更新画布(在没有更改的情况下).

3.游戏

游戏为你创建新游戏使拓展的class. 游戏拥有的每一帧都会fired game loop . 默认帧数为20, 但是你可以增加到 30FPS.

在game loop中你可以为所欲为地改变画布。 你可以在画布上随意移动一个对象。 作为开发者你必须计算变更后会发送什么。如果你想要每秒都进行变更，但你只有25FPS，你只需要每25帧触发一次。

了解术语

这些术语你必须在创建游戏时铭记于心。

帧数延迟

在Minecraft低于1.13的版本中拥有帧数延迟。也就是说当你更改一些东西，在3帧内不会显示出来。通常这不是个大问题，25帧只有120毫秒 - 然而你需要在使用inputs时记住一些东西。

屏幕维度

屏幕维度取决于很多东西. 你可以使用最多15行+1个标题。宽度则为变量: 每一个像素可拥有不同的颜色的情况下，在1.8-1.12的服务器宽度为72。 然而在不是所有的像素拥有不同的颜色的情况下使用黑白游戏或资源包可以增加宽度。 1.13以上版本的服务器的宽度就没有限制。 音乐和音效

API可以让你播放音乐和音效。 音效设置和Spigot/Bukkit的相似，你可以选择一个音效并设置音量和音高。你还可以指定资源包中不同的ogg音效文件.

音乐则有所不同，你可以播放NBS文件。

资源包

API提供了导入PNG文件的能力。你可以创建sprites和tiles.

你也可以使用自定义字体、音效和音乐。

了解API的拓展性

API易于拓展。这个API包括了绘制屏幕所需的类和工具、创建音乐，还有更多的可能。同时API也提供了一些基础的2D游戏矢量计算、绘制objects或 sprites 的功能- 你甚至可以使用自创的游戏引擎.

画布

介绍

你可以在画布上自由进行绘制. 取决于游戏设置，每名玩家可以拥有独立的画布或是共享同一个画布。

在插件的API里，你可以找到Canvas这一抽象的class和拓展的CharacterCanvas。这用于未来版本可使用的如地图、全息文字或其他界面构成的画布。但现在你只能使用计分版作为画布。 In the API, you will find that the Canvas class is abstract and extended by CharacterCanvas. This is done to allow for future canvasses such as maps, holograms or other interfaces you can display your game on. For now, only character based canvases for scoreboards are supported.

分辨率

像素分辨率在游戏建造者中已被设置. 每个游戏中的'默认'画布拥有分辨率.你必须在每个像素内使用全宽度并在UTF-8编码条件下使用.每个字符都可以拥有颜色.

X 和 Y 从屏幕的左上角开始扩展。也就是说你往右走则Y值会增加，往下走X值会减少. It is indexed as an array where 0,0 is the start position and the maximum value is (width-1),(height-1).

标题

你可以使用 setTitle setter来设置标题。 The title will be formatted internally with colors and updated alongside the pixel updates.

标题的最大长度为32个字符。

绘制

画布部分已经有一些绘制的方式了。API存在多个包含参数的默认值超载方法（如像素字符）。 The canvas already has several methods included for drawing. Multiple overloaded methods exist with default values for arguments (such as pixel character).

绘制像素

可以让你在指定的X、Y位置绘制一个像素。

画线

可以让你在两点间画一条线

绘制矩形

可以根据你给予的高度和宽度让你从指定的X、Y位置开始绘制一个矩形边界。

填充矩形

可以根据你给予的高度和宽度让你从指定的X、Y位置开始绘制一个矩形。

writeString

Draws a string with regular ASCII characters at a given X,Y position. In order to compensate for the non-monospace font in minecraft all the pixels left to the X,Y position will be cleared.

The string you provide has to be color formatted if you use color characters.

游戏

游戏需求

• 游戏制作者必须在计分板上测试测试游戏
• 游戏应该引导玩家如何入门 (教程)
• 游戏需要有一个可以暂停或停止游戏的菜单 (在 ArcadeBoard API 内可使用helper methods)

拓展游戏class

第一步就是拓展游戏的class。 This will force you to implement a constructor and implement the "game loop" and game events (start/stop).
Each game requires a type parameter to define the Canvas you are drawing on. While the API is Scoreboard centered, it can be scaled for future expansion.

注释扩展class

The next step is to provide some information for your game. This is done by annotations that are read by the plugin when the game is loaded into memory.
The required information:

• GameName (be.maximvdw.arcadeboard.api.annotations.GameName) A name for your game following the requirements of [aA-zZ] (only letters)
• GameAuthor (be.maximvdw.arcadeboard.api.annotations.GameAuthor)
• GameVersion (be.maximvdw.arcadeboard.api.annotations.GameVersion)
• GameDescription (be.maximvdw.arcadeboard.api.annotations.GameDescription)可选信息:
  

• GameDisplayName (be.maximvdw.arcadeboard.api.annoations.GameDisplayName) A fancier name than the GameName (can contain numbers and spaces, ..)
• GameControls (be.maximvdw.arcadeboard.api.annotations.GameControls) Description of your controls
• GameScreenshots (be.maximvdw.arcadeboard.api.annotations.GameScreenshots) A string array of links to screenshots of your game
• GamePermalink (be.maximvdw.arcadeboard.api.annotations.GamePermalink) A link to an information page of your game
• GameVideos (be.maximvdw.arcadeboard.api.annotations.GameVideos) A string array of links to videos of your game
• GameConstraint (be.maximvdw.arcadeboard.api.annotations.GameConstraint) A constraint given to your game. The game will not start when this constraint is not met. Examples would be a server version, ArcadeBoard version (when you use new features), ...
• GameConstraints (be.maximvdw.arcadeboard.api.annotations.GameConstraints) A list of multiple constraints

更改游戏设置

游戏拥有一些默认的设置，但在大多数情况下你会选择更改这些默认选项。设置选项的范围包含了最少玩家数、目标的fps和资源包要求等。 The game has some default settings. However you will most likely want to change these. Settings range from things like the minimum amount of players to things like aimed FPS and resource pack requirements.

游戏事件

一个class extending a Game will have to implement all the game events. External plugins can just use the Bukkit events to catch these events.

开始游戏

• 当玩家想要开始单人游戏时，游戏会被构建并在之后触发GameStartEvent (onGameStart method) 事件。
• 当玩家想要开始多人游戏时, 游戏会被构建但玩家会被置入游戏大厅. When the game starts (by reaching a minimum amount of players or when all players are ready) theGameStartEvent (onGameStart method) is fired。

停止游戏

• A game is stopped when there aren't enough players. The GameEndEvent (onGameEnd method) is fired.
• A game is stopped when the "stop()" method is called. The GameEndEvent (onGameEnd method) is fired.

玩家离开

• GamePlayerLeaveEvent (onPlayerLeave method) 会在游戏离开游戏时触发。 这个事件在 GameEndEvent 之前就会被触发，以防玩家in case the player causes to trigger the minimum amount of players

游戏循环（Game Loop）

当你完成游戏设置后，是时候在游戏循环内进行编程了。查阅本wiki以获取更多有关如何在画布上绘制一名玩家的信息。

游戏教程

以下教程基于公开的API进行构建，测试是在最新版的minecraft和预发布版本的插件中进行的。API的用法可能会千变万化，但是万变不离其宗。 The following tutorials are build upon the public API, the testing is done on a pre-released version of the plugin using the latest minecraft version. API usage is subjected to change, however will remain mostly the same !

游戏玩家

介绍

一名'游戏玩家' 指的是使用ArcadeBoard的玩家。 It is an encapsulation of a normal player, but with more features. It is used internally as a way to keep track of players that are playing a game, but can be used as developers to get specific information about other games (or your game) and store them in the database the player has configured.

永久游戏存储·Persistent Game storage

The GamePlayer API offers a way for games to store data in a "key" "value" method. This means that you can give a key of your choice to store data. For example: "killed puppies"=3.

On top of that, there is a statistic API that allows you to specifically store statistics. Internally this uses the same key/value storage method. This allows external developers to get specific information from your game without having to understand what it actual stores.

storeGameData

This stores a key/value pair of a player for your game.

It takes 4 arguments: The Game (GameInformation is a downcasted instance of your Game instance), the player you are saving the data to, and the key/value pair.

getGameData

This gets a stored key/value pair of a player by its key.

storeStatistic

This stores a statistic of a given type. Available types are "BEST_SCORE", "VICTORIES", "DEFEATS".

When using this you immediately provide your game with placeholders for MVdWPlaceholderAPI.

The placeholders would be:

{arcadeboard_<YOURGAMENAME>_statistic_<STATISTIC TYPE>}

So if your game is called "DonkeyKong" and you store the BEST_SCORE, then the placeholder would be:

{arcadeboard_donkeykong_statistic_best_score}

资源包控制

The plugin and API try to make it as easy for a developer to add resource packs for their game as possible. You do not have to worry about knowing if a player has a resource pack or not, the API comes with a set of helpful methods.

Please read the API documentations about resource packs first!

getEnabledResourcePacks

Returns a list of enabled resource packs

hasResourcePackEnabled

Checks if the user has a resource pack enabled.

setResourcePack

Sets the resource pack of a user. The user still has time to accept/reject this. Use the "hasResourcePackEnabled" method to check if the user installed it successfully.

音乐/音效 控制

You can play resource pack songs or note block songs (NBS files) through the API.

Please read the API documentations about resource packs and music first!

输入事件

原wiki暂无

菜单

介绍

菜单 API以一种抽象的方式向玩家显示菜单。这个API包括了拥有独立属性的菜单物品。

包含以下重要组成部分: 菜单·Menu: This is a menu object that contains the 'components' of the menu, such as the buttons, or other items 菜单物品·MenuItem: This is an item that you add to a menu. It can be something like a button, label, checkbox ,... MenuInstance: When a menu is shown to a player it gives you a menu instance. This is a menu unique to a player containing the selected item , ... 一个菜单class on itself doesn't look like anything. Only when extended you can implement how it is drawn and updated. That is why there is a DefaultMenu available that implements a basic menu example.

技术细节

原wiki暂无

资源包

介绍

默认你可以使用任意的 ASCII 或 UTF 字符来在画布上绘制像素。然而这些字符受限或大小不对会致其难以使用。

Resource packs are very well integrated in the plugin, allowing you to draw sprites without having to deal with the creation of resource packs. The plugin will handle the creation, you just need to remember the name you gave to individual sprites.

Based on your resource pack settings you provide the pack can be forced to the user (forced as in: If you don't want it, you can't play).

资源图标

A resource icon is an icon (image) that will replace an unused UTF-8 character. You do not have to worry about which character is replaced, or remember the character.

资源图像

A resource image is a combined collection of individual resource icons. It provides one big image that is split in 16x16 chunks to create one image.

资源音乐

A resource song is an OGG song that can be used in the game. It can be used for in-game music or effects.

资源字体

A resource font is an additional font that uses ResourceIcon's to display the characters. Multiple games can multiple fonts.

用法

添加一个图标

Adding an icon takes two arguments. The first being a name you give to your icon and the second being a file, input stream or BufferedImage.

resourcePack.addIcon("PACMAN_IDLE",new File(....));

Note: You can automatically generate rotated versions of your icon by specifying "allowRotation"

添加一个图像

Adding an image takes two arguments. The first being a name you give to your image and the second being a file, input stream or BufferedImage.

resourcePack.addImage("MyPicture",new File(....));

提示: You can automatically generate rotated versions of your icon by specifying "allowRotation"

使用一个图标

Using an icon is as simple as getting it by the name you created it with.

resourcePack.getIconByName("PACMAN_IDLE");

The above code returns a "ResourceIcon" that has a toString() method you can use.

You can also use this instance of ResourceIcon directly when drawing to a canvas.

提示: When you've added the icon with "allowRotation" you can use toString(rotation)

rotation is a number between 0 and 3

使用一个图像

Using an image is as simple as getting it by the name you created it with.

resourcePack.getImageByName("MyPicture");

The above code returns a "ResourceImage" that you can use to draw to a canvas.

'Note: When you've added the icon with "allowRotation" you can use toString(rotation)'

'rotation is a number between 0 and 3'