Docmand - 文档与命令
下载 v0.6.04
允许创建自定义命令,将文件或 URL 的内容发送给玩家。
支持自定义加入消息(MOTD)和传送提示。
内置标签系统,可将内容中的标签转换为 Java 代码,从而实现高度定制化。
你可以决定插件的具体行为(在插件功能允许的范围内)。
可视为功能极其丰富的 MCDocs 替代品。
支持权限系统和多世界。
支持参数传递,可将参数解析并传递给命令、别名及其他部分的各个组件。
更新说明
从 0.5x 版本更新至 v. 0.6.xx 前的重要提示:
请删除或重命名你的 events.yml 文件,系统将自动生成一个新的示例文件以适配新代码。
旧版 events 文件与新系统不兼容。请重新配置你的事件。
对于由此带来的不便深表歉意,但此次更新对事件系统进行了重大变更。我将在下一次更新中提供更完善的升级方案。
建议同时删除 default.yml 解析器配置文件,它将自动重新生成并包含一些新的解析器。此外,尽量避免向 default.yml 解析器文件中添加自定义解析器,而是将它们创建在单独的文件中。
安装
下载并将其放入 plugins 文件夹。重载服务器。
cbDocmand 将自动生成默认配置文件和一些示例文件。
配置
| cacheTime | 所有文件和 URL 都会被加载到内存中并存储。此缓存时间指定在获取更新文本之前保留这些数据的时间长度(单位:秒) |
|
| linesPerPage | 创建分页时每页显示的行数。当显示的行数达到 linesPerPage + 1 时,将触发分页 |
|
| logLevel | (当前未使用)要显示的日志级别。0 = 无,1 = 少量信息,2 = 更多信息,3 = 所有调试信息 |
|
| paginationHeader | 分页标题的渲染格式。可使用 3 个变量:%x 表示当前页码,%y 表示总页数,%commands 将渲染为使用 pageCommands 定义的 3 个分页导航命令 |
|
| pageCommands | 定义用于浏览页面的命令。 |
用法
根据需要,在 files 文件夹中添加任意数量的文件。
根据需要,在 events.yml 文件中添加任意数量的事件。
你可以随意编辑并添加任意数量的解析器。建议不要修改默认解析器,因为随着新版本发布它会随之更新,但你可以添加新文件。所有位于 parsers 文件夹中的 .yml 文件都会被加载,因此你可以自由添加支持你常用插件的解析器,并在 论坛 上分享它们。
发送给玩家的消息会使用标准的 Minecraft 颜色进行着色,当使用 &x(其中 x 为十六进制 0-f)编写时。
如果消息超过 9 行(或在配置中指定的行数),发送给玩家的消息将自动转换为分页。
可以通过输入 next、previous 或 page 命令来查看页面,具体命令由 pageCommand 配置定义。
例如,执行 /rules 命令会向用户发送 16 行内容。内容会自动分为两页,并显示一个介绍分页的头部信息
第 1 页,共 2 页(输入 /next、/prev 或 /page <x> 选择页面)
用户可以随后发送 /next 或 /page 2 命令来查看第二页。
你可以使用以下命令重新加载所有配置文件:
/docmand reload - 需要权限 docmand.reload
Docmand 权限
| docmand.reload | 允许重新加载所有 Docmand 配置、事件、文件和解析器。 |
|
| docmand.all | 拥有此权限的用户将跳过所有事件(Events)的权限检查。 |
概念
使用 cbDocmand 需要了解三个概念:事件(Events)、解析器(Parsers)和文件(Files)。
事件(Events)
共有三种类型的事件:
Commands:当玩家输入指令时触发。
Joins:在玩家加入服务器时触发。
Teleports:当玩家通过指令、插件或下界传送门传送到指定世界时触发。
事件的定义是通过编写包含一个或多个事件描述的元素来实现的(顺序不限)。
你可以为同一个触发器指定多个事件,例如可以添加 1 个以上的加入(join)事件,或者根据权限和世界向命令添加更多事件等。
所有满足条件的事件都会被触发,因此如果某个事件未指定世界或权限,它将与已指定世界或权限的事件同时触发。
支持的事件描述包括:World(世界)、Permission(权限)和 Actions(动作)。
World(世界)事件描述:
你可以指定一个或多个该事件将触发的世界,
可以通过多个描述来指定,也可以以数组形式指定。
例如:
World: World
World: World_nether
或者
World: [World, World_nether]
Permission(权限)事件描述:
你可以指定一个或多个权限,事件触发时需要具备这些权限
如果有多个,则必须为玩家设置所有列出的权限才能触发
可以使用多个描述或数组来指定
可以设置为任意权限,因此你可以复用其他插件使用的权限,或者创建自己的权限等。
例如:
Permission: someplugin.somepermision
Permission: someotherplugin.someotherpermission
或
Permission: [someplugin.somepermision. someotherplugin.someotherpermission]
Actions 事件描述:
你可以指定多个触发动作。
动作基于键值对,其中键是动作类型,值是动作的内容。
动作在 Actions 事件描述中指定。
动作会按照指定的顺序触发。所有向用户渲染文本的动作
都会被合并在一起,形成一段文本,该文本随后会自动分页(分页处理)。
剩余的所有 Command 动作则会按出现顺序依次触发。
例如:
Actions:
- Text: 'Some text here'
- Command: /somecommand
支持的 4 种动作为:
Url:定义将内容发送给玩家的 URL
File:定义放置在插件 files 文件夹中的文件,将内容发送给玩家
Command:定义要触发的命令(注意:这会触发聊天行为,因此如果命令未加斜杠 /,玩家会将消息发送到服务器)
Text:发送给玩家的内容,与 file/url 相同,但无需外部文件
所有动作都可以包含解析脚本,写法为 %someparse%
解析脚本支持参数,例如 %someparse("World",4)%
对于加入和传送,事件描述以 Joins/Teleports 类别下的多个事件形式编写。
而 Commands 事件则需要分配一个命令。
这是通过写入命令名称来实现的,并在该命令下指定(一个或多个)事件描述。
命令支持参数(自变量)
例如:
help
help worldedit
help tp
在此示例中,如果用户输入 "help me",它将默认回退到 help 命令,插件会寻找最精确的匹配项。
但如果用户输入 "help tp",则只会触发为此命令指定的事件,而不会默认回退到 help 命令。
命令还支持参数解析。因此在命令之后指定的参数将作为 $n(其中 n 是参数编号)发送到内容中编写的任何解析器。
例如,如果用户输入:
/help worldedit hello rules.txt
插件将触发 help worldedit 命令,并将 hello 解析为参数 $1,将 rules 解析为参数 $2。
例如(针对 help worldedit 命令)
Actions:
- File: worldedit.txt
- Text: 'You wrote $1'
- Text: '%includeFile($2)%'
这将获取 worldedit.txt 的内容,然后输出 "You wrote hello",接着包含文件 "rules"。
示例
Joins:
- World: Test
Permission: docmand.test1
Actions:
- Text: 'Youhavepermissiontest1'
- World: [Test, Test_nether]
Permission: docmand.test2
Actions:
- Text: 'Youhavepermissiontest2'
- Actions:
- File: motd.txt
Commands:
someurl:
- Actions:
- Url:
serverrules:
- Actions:
- Command: /rules
news:
- Actions:
- File: news.txt
motd:
- Actions:
- File: motd.txt
rules:
- Actions:
- File: rules.txt
test:
- Actions:
- Text: 'Somethingtest'
test hello:
- Actions:
- Text: 'Somethingothertesthello'
test say:
- Actions:
- Text: 'Yousaid:$1'
me:
- Actions:
- Command: '/say&d%player_name%is$1'
stuff:
- Text: 'Some$1andfirstlinefrom$2:%lineFromCommand("$2",1)%'
permworldtest:
- World: World
权限: docmand.permworldtest1
操作:
- 文本: '你拥有 permworldtest1 权限'
- 文本: 'Andareinworld%world_name%'
- 权限: docmand.permworldtest2
世界: [World,World_nether]
操作:
- 文本: '你正在世界%world_name%中'
- 文本: '并且具有 permworldtest2 权限'
- 操作:
- 文本: '你拥有 test1 或 test2 权限'
权限: [docmand.test1,docmand.test2]
- 世界:
- World
- World_nether
操作:
- 文本: 'Helloworld'
帮助:
- 权限: minecraft.tp
操作:
- 文本: '&b/helptp'
- 权限: minecraft.give
操作:
- 文本: '&b/helpgive'
- 权限: minecraft.settime
操作:
- 文本: '&b/helpsettime'
help tp:
- 权限: minecraft.tp
操作:
- 文本: 'Youwrite/tp<player1><player2>'
帮助 give:
- 权限: minecraft.give
操作:
- 文本: '你编写/give<itemid><itemnum>它将给你你这些物品'
帮助 settime:
- 权限: minecraft.settime
操作:
- 文本: '你输入 /settime <xxx>,其中 xxx 是时间(以刻为单位)'
传送点:
- 世界: World
权限: docmand.test1
操作:
- 文本: 'WelcometoWorld'
- 世界: World_nether
权限: docmand.test2
操作:
- 文本: 'WelcometoHell!'
解析器
解析器由一个解析关键字和一些基本的 Java 代码组成(仅支持基本代码,且仅支持单行代码)
内置函数可以直接调用,同时您也可以访问 Player 对象和 Server 对象。
因此,若要创建一个返回玩家当前所在世界名称的解析器,您可以这样写:
player_world: Player.getWorld().getName()
这随后可以从任何 Text、Url 来源或 File 来源进行解析,例如:
Welcome to %player_world%
也支持参数。
lineFromCommand: readLineFromCommand($1,$2)
注意 $1 和 $2,它们是参数占位符。
您可以通过指定带有括号的参数来使用带参数的解析命令进行解析。
Latest news: %readLineFromCommand("news",1)
这将把 "news" 作为第一个参数,1 作为第二个参数进行解析。
此命令将读取指定为 /news 的命令的输出行,并仅返回第一行。
支持数组/列表:
Server.getPlayers[0].getName()
Server.getPlaysers.get(0).getName()
Server.getPlayers[$1].getName()
解析器也支持 void 方法,因此您可以执行以下操作:
添加事件
命令:
hurt:
Text: You were damaged 5 hearts %damage_player(5)%
添加解析器
damage_player: Player.damage($1)
现在您就拥有一个会显示消息 "You were damaged 5 hearts" 然后触发伤害效果的命令了。
内置函数(更多功能即将推出)
| Java | 参数 | 描述 |
|
| readLineFromCommand($1,$2) | 命令, 行数 | 包含从命令渲染的前 x 行数 |
|
| readLinesFromCommand($1,$2,$3) | 指令,起始行,结束行 | 包含从某指令渲染出的文本中,从起始行到结束行的所有行 |
|
| getOnlinePlayerNames() | | 返回在线玩家名称的逗号分隔列表 |
|
| getPlayersInPlayerWorld() | | 获取当前玩家所在世界中的在线玩家 |
|
| includeFile($1) | 文件名 | 从 files 文件夹中包含一个文件 |
|
| includeCommand($1) | 指令名称 | 包含某个指令的内容 |
示例
server_name: Server.getServerName()
player_name: Player.getName()
players_in_world: getPlayersInPlayerWorld()
online_players: getOnlinePlayerNames()
online_players_count: Server.getOnlinePlayers().length
lineFromCommand: readLineFromCommand($1,$2)
player_world: Player.getWorld().getName()
linesFromCommand: readLinesFromCommand($1,$2,$3)
include: includeFile($1)
includeCommand: includeCommand($1)
文件
通过 File 命令类型引用的文件,必须位于 cbDocmand/Files 文件夹中。
示例
Hi %player_name% and welcome to %server_name%
There are &d%online_players_count% &fplayers online
&aOnline: &c%online_players%
%include("include.txt")%
&a全部新闻:&b/news
&a规则:&b/rules(或 /serverrules)
未来/想法/当前问题
- 增加更多内置函数
- 提供更多代码支持(如数学运算等)
- 增加更多可在解析器中访问的基础类(目前仅支持 Player 和 Server)。
- 清理代码,并将代码提交至仓库。
- 增加更多默认解析器。
- 是否支持 Spout?
不再属于未来,已实现/修复
- 权限支持
- 修复自动分页
- 使用权限节点支持群组
- 支持嵌套解析器(评估一个解析器,并将其传递给另一个解析器进行解析)
- 事件中的多个操作
- 分页命令
结语
希望你喜欢它。欢迎评论、提出想法或报告错误。也欢迎提供解析命令(已准备好供其他插件使用的 parse command 文件),我们将非常感激。
玩得开心!
Docmand - Documents and Commands
Download v0.6.04
Allows creation of custom commands that will send the content of files or urls to the player.
It allows for custom message on Join (MOTD) and Teleports.
Complete with tag system that can transform tags in content to java code and thus enabling a very large portion of customization.
You decide what the plugin should do (In the frame of the functionality the plugin allows you too)
Consider it a very feature rich MCDocs replacement.
Permission and Multiworld support.
Argument support, parse arguments around to the various aspects of commands, alias' and other.
Update notice
Important before updating to v. 0.6.xx from 0.5x:
Please delete/rename your events.yml file, it will auto generate a new example file following the new code.
The old events file is NOT compatible with the new system. Recreate your events again.
I'm sorry for the inconvenience, but this update is a major change to the events system. I will try in the next update to supply a better upgrade system.
Also advised to delete the default.yml parser, it will regenerate with some new parsers, and generally avoid adding your own parsers to the default.yml parser file, instead create your parsers in seperate file(s).
Installation
Download and put in plugins folder. Reload server.
cbDocmand will auto generate default config file, and some example files.
Config
| cacheTime | All files/url are loaded in to memory and stored, this cache time tells how long to store this before getting an updated text, in seconds |
|
| linesPerPage | How many lines is shown per page when creating pagination, shows up to linesPerPage + 1 before it will create pages |
|
| logLevel | (currently not in use) What level of log to show. 0 = nothing, 1 = litle information, 2 = more information, 3 = all debug information |
|
| paginationHeader | What the pagination header should render as, 3 variables can be used, %x and %y is current page and total pages respectively, and %commands will render as the 3 pagination commands defined with pageCommands |
|
| pageCommands | Defines the commands that can used to traverse the pages. |
Usage
Edit and add as many Files in the files folder as you wish.
Edit and add as many Events in the events.yml file as you wish.
Edit and add as many Parsers as you wish, advised to not edit the default parser since this will be updated with new versions, but you can add new files. All .yml files in the parsers folder will be loaded, so feel free to add new parsers to support your favorite plugin, and share them in the Forum.
Messages sent to the player will be colorized using the standard minecraft colors when written with &x where x is between hex 0-f.
Messages sent to the player are automatically converted to pages, if more than 9 (or what is specified in config) lines is present.
Pages can be viewed by typing the next, previous or page command as defined in the pageCommand config.
E.g. a command /rules will be sending 16 lines to the user. The content is automatically split into two pages and a header presenting the pagination will be sent
Page 1 of 2 (/next, /prev or /page <x> to select page)
The user can then send the command /next or /page 2 to view the second page
You can reload all configs with the command:
/docmand reload - Requires the permission docmand.reload
Docmand Permissions
| docmand.reload | Ability to reload all docmand configs, events, files and parsers. |
|
| docmand.all | A user with this permissions will skip permission check for all events. |
Concepts
There are 3 concepts you will need to know about to use cbDocmand: Events, Parsers and Files
Events
There are 3 types of Events
Commands which triggers when a player enters the command
Joins which triggers on a join event
Teleports which triggers when a player either teleports via command or plugin or netherportals to the specified world
Events are specied by writing an element that contain one or more event descriptions (In no particular order).
You can specify several events to one trigger, e.g you can more than 1 join event, or more events to a command, based on permission and world. etc.
All events that is fullfilled will be triggered, so if an event specified no world or no permission it will be triggered alongside those that have a world or permission specied.
Event desciptions supported are: World, Permission and Actions.
World event description:
You can specify one or more worlds the event will trigger for,
they can be specified using multiple descriptions, or as an array.
E.g:
World: World
World: World_nether
OR
World: [World,World_nether]
Permission event description:
You can specify one or more permissions the event will require in order to trigger
If multiple, then all all permissions written needs to be set for the player in order to trigger
can be specified using multiple descriptions or as an array
Can be set to any permission, so you can reuse permissions used for other plugins, or create your own, etc.
E.g:
Permission: someplugin.somepermision
Permission: someotherplugin.someotherpermission
OR
Permission: [someplugin.somepermision. someotherplugin.someotherpermission]
Actions event description:
You can specify multiple actions to trigger.
Actions are key/value based, so key is Action type, and value is content for the Action
Actions are specied in a Actions event description.
Actions are triggered in the order they are specified. All actions that renders some text to displayed to the user
will be merged together, to form one piece of text, this text is then automatically cut into pages (pagination).
all remaining Command actions will triggered afterwards in the order they appear.
E.g:
Actions:
- Text: 'Some text here'
- Command: /somecommand
The 4 Action types supported are:
Url: defines a url where content will be send to the player
File: defines a file placed in the files folder of the plugin where content will be send to the player
Command: defines the command to trigger (NB: Triggers a chat, so if command is specified without / the player will chat the message to the server)
Text: content to be send to the player, the same as file/url but without the need for an external file
All Actions can contain parse scripts, which is written as %someparse%
parse scripts supports arguments such as %someparse("World",4)%
For joins and teleports the event descriptions are written as multiple events in the Joins/Teleports category
Commands events however needs to have a command assigned.
This is done by writting the command name, and under the command you specify the (1 or multiple) event descriptions
Commands support arguments (parameters)
E.g:
help
help worldedit
help tp
In this example, if a user write "help me" it will default back to help, the plugin looks for the best exact match.
But if a user writes "help tp" it will trigger ONLY the events specied for this command, and will not default back to help command
Commands also support argument parsing. So arguments specified after the oommand will be send to any parsers written in the content as $n (Where n is the argument number)
E.g, if the user writes:.
/help worldedit hello rules.txt
The plugin will trigger the help worldedit command, and parse hello as argument $1 and rules as argument $2.
E.g (for help worldedit command)
Actions:
- File: worldedit.txt
- Text: 'You wrote $1'
- Text: '%includeFile($2)%'
This will get the contents of worldedit.txt, and after that it will write "You wrote hello" and then include the file "rules"
Example
Joins:
- World: Test
Permission: docmand.test1
Actions:
- Text: 'Youhavepermissiontest1'
- World: [Test, Test_nether]
Permission: docmand.test2
Actions:
- Text: 'Youhavepermissiontest2'
- Actions:
- File: motd.txt
Commands:
someurl:
- Actions:
- Url:
serverrules:
- Actions:
- Command: /rules
news:
- Actions:
- File: news.txt
motd:
- Actions:
- File: motd.txt
rules:
- Actions:
- File: rules.txt
test:
- Actions:
- Text: 'Somethingtest'
test hello:
- Actions:
- Text: 'Somethingothertesthello'
test say:
- Actions:
- Text: 'Yousaid:$1'
me:
- Actions:
- Command: '/say&d%player_name%is$1'
stuff:
- Text: 'Some$1andfirstlinefrom$2:%lineFromCommand("$2",1)%'
permworldtest:
- World: World
Permission: docmand.permworldtest1
Actions:
- Text: 'Youhavepermworldtest1permissions'
- Text: 'Andareinworld%world_name%'
- Permission: docmand.permworldtest2
World: [World,World_nether]
Actions:
- Text: 'Youareinworld%world_name%'
- Text: 'Andhavepermworldtest2permissions'
- Actions:
- Text: 'Youhavepermissionstest1ortest2'
Permission: [docmand.test1,docmand.test2]
- World:
- World
- World_nether
Actions:
- Text: 'Helloworld'
help:
- Permission: minecraft.tp
Actions:
- Text: '&b/helptp'
- Permission: minecraft.give
Actions:
- Text: '&b/helpgive'
- Permission: minecraft.settime
Actions:
- Text: '&b/helpsettime'
help tp:
- Permission: minecraft.tp
Actions:
- Text: 'Youwrite/tp<player1><player2>'
help give:
- Permission: minecraft.give
Actions:
- Text: 'Youwrite/give<itemid><itemnum>itwillyougiveyoutheitems'
help settime:
- Permission: minecraft.settime
Actions:
- Text: 'Youwrite/settime<xxx>wherexxxisthetimeinticks'
Teleports:
- World: World
Permission: docmand.test1
Actions:
- Text: 'WelcometoWorld'
- World: World_nether
Permission: docmand.test2
Actions:
- Text: 'WelcometoHell!'
Parsers
Parsers are made up of a parse keyword, and some basic java code (Only basic code, and only 1 line of code is supported)
The built in fuctions are called directly, but you also have access to the Player object, and the Server object.
So to create a parser that will return the world name of the world the player is currently in, you would do something likes this:
player_world: Player.getWorld().getName()
This can then be parsed from any Text, Url source, or File source, e.g:
Welcome to %player_world%
Arguments are also supported.
lineFromCommand: readLineFromCommand($1,$2)
Notice the $1 and $2 they are argument placeholders.
They can parsed by specifying the parse command with arguments surrounded by parenthesis around them.
Latest news: %readLineFromCommand("news",1)
Will parse "news" as the first argument, and 1 as the second argument.
This command will read the lines from the command specified as /news, and return only the first line.
Arrays/Lists are supported:
Server.getPlayers[0].getName()
Server.getPlaysers.get(0).getName()
Server.getPlayers[$1].getName()
Parsers also support void methods, so you could do the following:
Add a event
Commands:
hurt:
Text: You were damaged 5 hearts %damage_player(5)%
Add a parser
damage_player: Player.damage($1)
And now you have a command that writes the message "You were damaged 5 hearts" and then triggers the damage.
Built in functions (More will come)
| Java | Arguments | Description |
|
| readLineFromCommand($1,$2) | Command, line number | Includes the first x number of lines rendered from a command |
|
| readLinesFromCommand($1,$2,$3) | Command, start, end | Includes lines from start line to end line of lines rendered from a command |
|
| getOnlinePlayerNames() | | Returns a comma seperate list of online players |
|
| getPlayersInPlayerWorld() | | Gets the online players in the world the player is currently in |
|
| includeFile($1) | Filename | Includes a file from the files folder |
|
| includeCommand($1) | command name | includes the content from a command |
Example
server_name: Server.getServerName()
player_name: Player.getName()
players_in_world: getPlayersInPlayerWorld()
online_players: getOnlinePlayerNames()
online_players_count: Server.getOnlinePlayers().length
lineFromCommand: readLineFromCommand($1,$2)
player_world: Player.getWorld().getName()
linesFromCommand: readLinesFromCommand($1,$2,$3)
include: includeFile($1)
includeCommand: includeCommand($1)
Files
Files refered to with the File command type, must reside in the cbDocmand/Files folder.
Example
Hi %player_name% and welcome to %server_name%
There are &d%online_players_count% &fplayers online
&aOnline: &c%online_players%
%include("include.txt")%
&aAll News: &b/news
&aRules: &b/rules (or /serverrules)
Future/Ideas/Current issues
- More built in functions
- More code support (Math, etc)
- Add more supported Base classes that can be accessed in the parser (currently only Player and Server).
- Clean code, and throw code in repository.
- Add more default parsers.
- Spout support?
No longer future, has been implemented/fixed
- Permissions support
- Fixed auto pagination
- Group support using permission nodes
- Support for nested parsers (evaluating one parser, and parsing it to another parser)
- Multiple actions on events
- Pagination commands
End notes
I hope you like it. Comment, ideas, bugs, parse commands(parse command files prepared to be used for other plugins) are very welcome and appreciated.
Enjoy!
评论 0
登录后参与评分
还没有评论,来抢沙发吧