Bukkit

Advanced Usage

Effective as of CommandSigns v1.8.0

Allowing use of OP commands

If the command '/i diamond 1' is on a CommandSign, you may find that only operators and those with enough permission will be able to use the command. But if you want anyone to be able to use the command, you need to do one of the three following things.

There are 'meta-characters' that can go just after the forward slash '/' in your command. These meta-characters are '*', '^' and '#'. They're used like this.

1. /*acommand
2. /^anothercommand
3. /#yetanothercommand

This is what they do:

• '*' means that the user will have access to the '*' permission node (everything) whilst running the sign.
• '^' means that the user will be granted OP whilst running the sign.
• '#' means that the command will be run from the console, without any player data being sent along with it.

So as for the '/i' command, it would make sense to run it as an OP because by default, OPs can use it. '/*' will also work, whereas '/#' will not as the command does need player information to work.

1. /^i diamond 1

Sorted.

Variables

Variables are bits of text in your CommandSign that can change according to various conditions. An example is the name of the player that clicked the sign, or their location.

Variables are accessed like this:

/commandsigns line1 /dosomethingwith <variablename>

The variable can be one of the following:

• <x> - Player's x coordinate
• <y> - Player's y coordinate
• <z> - Player's z coordinate
• <world> - Player's current world
• <name> - Player's user name
• <display> - Player's display name
• <money> - Player's current money balance
• <formatted> - Player's current money balance formatted. (Ex. "10.00 dollars")

Complete List of Variables

Here's a fun one for you:

/commandsigns line1 /nuke <name>

Restrictions and Permissions

It's all well and good if you just want to make a list of commands to run, but what if you only want some users to be able to use it, or have a delay between using it. This is a job for restrictions.

A restriction goes like this:

1. {condition}
2. /commands
3. -

The {condition} part consists of a symbol, followed by text describing the condition. Here are the valid conditions you can use:

• `@groupname` - Restrict access to only that group.
• `&permission` - Require the specified permission node. This means you can make up your own permission nodes too!
• `$amount` - Make the CommandSign cost a certain amount to the player.
• `timeinseconds` - Restrict usage to once every ? seconds.
• `>>' - Restrict sign usage to right-clicking only.
• `%percent` - Restrict sign to work only a certain percentage of the time.

Complete List of Conditions

So now we can make a real example. Lets say only people in the group 'vip' can use the command `/get bacon`:

1. @vip
2. /get bacon
3. -

Nesting restrictions

But it doesn't stop there! You can also 'nest' restrictions inside each other. This means that the same '/get bacon' command above can only be used by VIPs and only once every 10 seconds for example.

1. @vip
2. ~10
3. /get bacon
4. --

Notice how I put two '-'s at the end of the restrictions? You don't have to do that, you could have just had the second one on line 4, but to save space, you can put several on the same line. They must be before any commands or conditions though. More on that in the Syntax section below.

Update

As of v1.8.3, you can now define multiple permission nodes and groups in the same condition; just separate them with a comma!

1. @vip,mod,admin
2. ~10
3. /get bacon
4. --

This also works for:

1. &permission.node,another.permission
2. ~10
3. /get bacon
4. --

Read commas as 'OR'.

Negating / using 'not' in conditions

What if you want everyone not in the VIP group to run a different command instead? Lets say they should run `/get coal`. That's easy too. There is another meta-character known to you and me as '!'. This is the 'not' operator. It can be used like this:

1. !@vip
2. /get coal
3. -
4. @vip
5. ~10
6. /get bacon
7. --

On its own line, the '!' character acts as an else, inverting the restrictions on the sign. The above code could also be accomplished like this, using else:

1. @vip
2. ~10
3. /get bacon
4. -
5. !
6. /get coal
7. -

Optional conditions

Now we're starting to get something that looks cool. One final thing: if we run this, we'll get the error 'You are not in the required group to run this command' no matter who you are. You can fix this by using one last meta-character: '?'. This makes the condition an optional check. It shouldn't report to the user that they didn't match the condition.

1. ?!@vip
2. /get coal
3. -
4. ?@vip
5. ~10
6. /get bacon
7. --

Alternatively, with else:

1. ?@vip
2. ?~10
3. /get bacon
4. -
5. !
6. /get coal
7. -

There we go. Now as a result of this, non-VIPs will be given coal, VIPs will be given bacon (but only once every 10 seconds), and nobody will get any errors along the way.

Additional commands

There is one other command that you can use alongside your normal ones. That is the delay command. It's simple to use, just type this:

1. \Waiting 5 seconds...
2. %5
3. \Finished!

That makes the current CommandSigns pause for 5 seconds. Don't worry, this doesn't lag your server at all!

Silent Commands

The '?' Operator also works on console commands, (1.7+) and on player commands. (1.8+) To run a player command silently, simply prefix the line with '?', for example:

1. ?/i diamondsword 1

Syntax

There are a few rules and shorthand ways of writing CommandSigns. You should already know from earlier that the '/commandsigns' command can also be accessed from '/cmdsigns' and '/cs', and you can use '5' instead of 'line5' (v1.8+), but there are also some tricks to make conditions and restrictions easier to remember.

The meta-characters '-', '?' and '!' can appear in any order provided they are before a condition or a command. Yes, that means you can put a '-' on the same line as another group condition and you can use multiple '-'s on the same line. That means the previous code could look like this:

1. !?@vip
2. /get coal
3. ?-@vip
4. ~10
5. /get bacon
6. --

And that will still be completely valid.

Remember that the '-' character will end the last condition that was opened.

Using CommandSigns with CommandHelper

If you need more advanced processing in signs, CommandHelper is a good plugin to work with. CommandSign commands will use CommandHelper aliases over registered commands if they're available, (1.8+) so it's a very good way to get extra programming functionality. To restrict an alias to just a sign, you can add an op requirement to the alias and run it as '/^alias'.

Batch Processing

By typing /cmds batch, (1.8+) you can enter batch processing mode. In this mode, read, enable, and remove operations can be done multiple times in a row with the same state. This is good if you need to remove a lot of signs, or make several signs with the same text. Here's an example of how one might use it:

1. Put some text in the clipboard with /cmds line1 \test
2. Enter batch enable mode with /cmds batch
3. Click multiple signs. They'll all be given the same contents.