Data API
Sponge 提供了一套统一的数据 API 旨在提供一致的方式访问和修改数据。“数据”,在这里指的是所有始终保持客户端和服务端的同步的数据,可以在服务端被更改,然后同步到所有已连接的客户端内。这些数据包括但远远不限于,一块木牌上的文字、一匹马的外貌、和任何有生命的实体的生命值。
尽管其他的 API 通过继承和接口的方式去访问和修改数据(比如一个 LivingEntity
提供对于当前生命值和最大生命值的 Getter 和 Setter 来访问和修改),然而在 Sponge 中,每一个实体、方块等,都不能直接地看出其拥有什么数据。和直接了当地获取数据相比,这可能并不那么直观,但是其强大的可扩展性却是非常重要的。由于增加了 Key,访问特定的数据还是那么简单。
小訣竅
如果这套数据 API 中有和你预期不一致的行为(例如在本应返回有意义数据的地方返回了空 Optional
),或你需要的数据这套 API 中没有,请前往实现追踪器查询,亦可前往 esper.net 的 #spongedev
频道、Sponge 论坛或 Sponge Discord 服务器的 #dev
频道询问有关开发者。
概念
如果你第一次接触数据 API 的文档,可能已经被多如牛毛的接口(Interface)和包(Package)吓得喘不过气了。不过如果只是想要使用数据 API,你并不需要完全理解它们,因为大部分的接口只是用于操纵特定的数据。
DataHolder
一个数据访问器其实仅仅是——用于读写数据的一个东西。它提供了一些方法用于检索和设置数据。接口本身和其存储的数据类型一点关系都没有。因为只有实现才关系到存储的数据类型,所以访问一个其根本没有存在的数据,或者设置一个其根本无法使用的数据,在 DataHolder 身上是完全有可能的。在这些情况下,返回值便会提供对于数据不可读(通过 Optional.empty()
)或者不可写(通过 DataTransactionResult )的信息。
屬性(Property)
A property too is data, but not synchronized between server and clients. Therefore, it can only be changed by modifications present on both client and server. Since Sponge is not intended to require a client-side counterpart, properties are not modifiable. Examples of properties are the applicable potion effects on tools (represented as Keys#APPLICABLE_POTION_EFFECTS or the damage absorption of an equipable armor item (represented as Keys#ABSORPTION).
資料操作者(DataManipulator)
A data manipulator represents points of cohesive data that describes a certain component of its holder. For
example HealthData, which contains both current and maximum health. If a data holder has HealthData
, it
has health that can somehow be depleted and replenished and can die if that health is depleted. This allows for the
re-use of such components over the API and prevents duplication of accessor methods. For example, sheep, stained glass
blocks and leather armor all can share the DyeableData holding the color they are dyed in.
鍵(Key)
A Key
is a unique identifier for a single point of data and can be used to directly read or set that point of
data without worrying about data manipulators. It was designed to provide a way of accessing data
similar to direct getter/setter methods. All keys used within Sponge are listed as constants in the
Keys utility class.
值(Value)
在数据 API 中,一个数据键(Key)对应的数据值是一个被包装起来的对象。在本文档中,将会使用“数据值”一词,以防止和实际值混淆。一个数据值封装了一个实际值(如果有的话),一个默认值(在实际值未定义时使用),和对应的数据键。