cbDocmand
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: 'You have permission test1' - World: [Test, Test_nether] Permission: docmand.test2 Actions: - Text: 'You have permission test2' - Actions: - File: motd.txt Commands: someurl: - Actions: - Url: http://example.com/mc.php?name=%player_name% serverrules: - Actions: - Command: /rules news: - Actions: - File: news.txt motd: - Actions: - File: motd.txt rules: - Actions: - File: rules.txt test: - Actions: - Text: 'Something test' test hello: - Actions: - Text: 'Something other test hello' test say: - Actions: - Text: 'You said: $1' me: - Actions: - Command: '/say &d%player_name% is $1' stuff: - Text: 'Some $1 and first line from $2: %lineFromCommand("$2",1)%' permworldtest: - World: World Permission: docmand.permworldtest1 Actions: - Text: 'You have permworldtest1 permissions' - Text: 'And are in world %world_name%' - Permission: docmand.permworldtest2 World: [World,World_nether] Actions: - Text: 'You are in world %world_name%' - Text: 'And have permworldtest2 permissions' - Actions: - Text: 'You have permissions test1 or test2' Permission: [docmand.test1,docmand.test2] - World: - World - World_nether Actions: - Text: 'Hello world' help: - Permission: minecraft.tp Actions: - Text: '&b/help tp' - Permission: minecraft.give Actions: - Text: '&b/help give' - Permission: minecraft.settime Actions: - Text: '&b/help settime' help tp: - Permission: minecraft.tp Actions: - Text: 'You write /tp <player1> <player2>' help give: - Permission: minecraft.give Actions: - Text: 'You write /give <itemid> <itemnum> it will you give you the items' help settime: - Permission: minecraft.settime Actions: - Text: 'You write /settime <xxx> where xxx is the time in ticks' Teleports: - World: World Permission: docmand.test1 Actions: - Text: 'Welcome to World' - World: World_nether Permission: docmand.test2 Actions: - Text: 'Welcome to Hell!'
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!
@Wolf480pl
:ยด(
@HostiileIntent
Forget about it, it's dead plugin. He haven't updated it since October 2011
Please update. Broken on 1.2.3/1.2.4. :(
Please Update to 1.2.3
@cyberdudedk
I'm guessing mChat isn't liking this very much D: http://pastebin.com/Xk5H3TPC
Edit : Unless this is wrong ? mChatNick: Server.getPluginManager().getPlugin("mChat").API.getRawPrefix("%player_name%")
@cyberdudedk
Ah, perfect ! Thanks ! :D
@cyberdudedk
Wow, didn't expect such a massive reply, haha !
Basically, what I'm trying to achieve, is make thicker texts : http://puu.sh/89gI
The text that is displayed when typing /register is the one I had already set up with MCDocs, and it used to span out using the full width, and not going back to a new line. Is this kind of feature not possible to add to the existing cbDocmand ?
I'll give the Server.getPluginManager a try, hadn't thougt of that !
I'll keep you posted if it works, I'm not too good at Java (More of a PHP guy.. :P ) ! :D
@Pr4w
A bit more details about mChat.
mChat has a "public" api.
http://dev.bukkit.org/server-mods/mchat/pages/current-mchat-api/
You should be able to use these function by calling:
Server.getPluginManager().getPlugin("mChat").API.xxxxxxx(yyy,zzz)
etc.
Edit:
And yet another look, it doesn't look like mChat supports returning playername coloured. And most of the functions for prefix and group and stuff requires the Player object, to be parsed, which currently isn't supported. I'm sorry, but it will at some point, when I get some proper free time on my hands.
@Pr4w
Thank you ;) The plugin is created with extendability in mind :)
About the text. I cut of the text at a specific length (I can't remember exactly what length), instead of breaking a text somewhere, it finds the first space before this line break, so as to create better readable text. Each character has varying length, so I cut the text based on how many wide characters can be on the screen, such as "w" or "m" or whatever. "i" and "l" and other characters is thinner, and thus texts with many thin characters will seem to cut of earlier than is necessary. Without doing major work to calculate each width of the characters, to get the correct width of the text, this is best I can do.
Notice I implemented my own line breaker because I didn't like the fact that the normal chat breaks the word.
I have not had much time lately for development. But what you are asking is essentially what this plugin is trying to achieve with Parsers. I will create more functions, and parser examples when I get time for it. It isn't fully developed yet.
You can create a parser that will call e.g
Server.getPluginManager().getPlugin("mChat").getColoredName()
This will of course require that mChat has a public function that is named getColoredName or something like that.
However, that function would probably require a instance of the Player object. If the plugin have a function like this, that requires the Playername as a string as parameter, you would theoretically be able to create a parser like this:
coloredName: Server.getPluginManager().getPlugin("mChat").getColoredName("%player_name%")
Explanation:
%player_name% will be replaced by the included parser, so it would amount to execute (in your example) something like this:
Server.getPluginManager().getPlugin("mChat").getColoredName("Pr4w")
As I said this is theoretically, this is what Docmand is supposed to be able to handle, however I have not personally tested this sort of functionality yet, also it does require that the plugin have such methods implemented.
Later it will be possible to parse the Player object and other various stuff to other plugins using this method, instead of just Strings.
If more advanced stuff is required (such as looping or other) it will be possible later to add small class files that can be called from the parser.
This of course requires a bit programming knowledge since it uses the same syntax as Java and requires knowledge about the plugin. The idea is that other knowledgable users create these parser, and share them with the community on the forum.
Hey !
Loving the plugin, I have a few issues though ! :D
- Text isn't as long as a message could be, so it goes back to a new line instead of being stretched to the end of the screen
- Is there a way to have a parser set for another plugin ? eg have someone's colored nickname using a parser for mChat for example ?
Thanks ! :D
Thanks so much for this. I am completely replacing McDocs with this plugin, it's functions, design, and ease of use is awesome. So far it works without skipping a beat on 1240/PEX.
@cocoson
You can do it two ways, one way is as you describe is to write the 16 different commands.
The other way is e.g
$1 will be replace by the argument supplied.
Currently the system can not detect the difference between the command pc not using arguments, and a command using the arguments as described over this. But if you can create a file without any name, or instead use the filename like this %include("pc/pc_$1.txt")% then you can name the default file (no arguments) as "pc_.txt" and voxelsniper file as "pc_voxelsniper.txt". If however a user tries to enter a argument for a file that doesn't exists, then you might get undesired results. Also notice there might be security problems using this approach as the path is not sanitized. So a specially written argument might allow the user to get the content of a file in another folder they were not supposed to. The next couple of version will also be focused on security among other things.
yo i don't see how i'm able to do what i asked you before with out having like 16 different commands the only way i see to do it is like this
and so on
@cyberdudedk
I answering whether you can make a event in what happens following: Someone get a rank up (he was promoted) and in the result of that he himselfs open a document. Like if someone joins and him is shown the motd, but with the event that someone get a rank up and him is shown another document.
@Phant0mX Thank you, that is very interesting idea. I will definitely be thinking about this. I would love to do some Spout work, and this would be a very good idea. It will depend on whether I can keep the setup simple. It is very important for me, that for users only wanting very basic functionality it should be very easy to setup, and then enabling more advanced setup for more advanced functionality. If I can make this play together in a nice way (Integrating it closely with current concepts) then yeah, I'll definitely be considering this idea :)
@nerd007
I am not sure I understand your question. Can you please try refraining it, and then I will answer as best as I can. You are asking about OP support? Or Permission support?
at first thanks for this plugin.(i was to stupid to find MCDocs) your plugin is very helpful. Question: Can you( or i) make the event when a player is a rank up?
Any plans for Spout integration at all in the future?
For example you could set messages to make popup windows instead of displaying them in chat, pull in images from the web to display in those messages, set a keyboard key to popup a message, etc.
Would be really useful for me, dunno about anyone else.
sure will i use the plugin but have have disabled on my server for now but i will keep looking back here every now and then.
<<reply 368093>>
Currently I don't support arguments for custom commands.
However you could with something like this, in the events file:
Commands:
pcvoxelsniper:
File: pc/VoxelSniper.txt
pctimeshift:
File: pc/TimeShift.txt
pc:
File: pccommands.txt
then put the first two files into a folder cbDocmand/files/pc and the pccommands file into cbDocmand/files folder.
You would then have three commands /pcvoxelsniper and /pctimeshift and /pc
I will add argument support later, and also add more functionality.
So currently it doesn't fully support what you want to do. But you can get close.
Stay tuned for more updates (Hopefully within the weekend)
i see yours is set up pretty much like mcdocs so maybe you can help me with yours here since they don't want to help me with the mcdocs yours might be able to do it.
lets say i have a folder inside cbDocmand called "pc" short for "plugins commands" and in side that folder i have lots of txt named something like Voxel Sniper.txt TimeShift.txt WorldEdit.txt
and when i type in like /pc it bring up a list of folders then type in like /pc Voxel Sniper to get all the commands inside the txt something like this plguin http://forums.bukkit.org/threads/ad...our-own-tutorials-for-your-players-953.13347/ would be great if can i dont like using outdated plugins and your would help out alot
seems like your plugin could do it and i hope it can so far i'm liking it.