|
| |
2.1.1 -
General Script Layout
Scripts are simple text files that are read as blocks. A block is ended with a semicolon. A block
may encompass multiple commands or items followed by semicolons, by encasing them in curly
brackets - { }. A command block is either a single command, where curly braces are not needed, or
multiple commands enclosed in them.
| Block example |
# a simple one line block
on pcmd_hi cmd /say_stat hi;
# a block containing multiple lines
on pcmd_hi {
perc .2;
cmd /say_stat hi;
};
# a block containing multiple lines and multiple commands
on pcmd_hi {
perc .2;
cmd {/say_stat hi;/say_stat there;};
};
# an alternate version of the above block
on pcmd_hi {
perc .2;
cmd {
/say_stat hi;
/say_stat there;
};
};
# list blocks (as opposed to an event blocks)
list test {
one 1;
two 2;
};
list test three 3;
# The above example would create a list of three items, each
# list item with a value of the corresponding number.
|
2.1.2 -
Variables
Variables in scripts are a combination of a target and a variable name, they are indicated by a leading
dollar sign ($). There are a few different formats that you can specify this in. You may specify the
target as a full name or a single letter
abbreviation. If you specify the full name, you need a comma between the target and variable.
Valid targets are as follows:
- c or serv or server - Specifies a server variable, like $ctime (current server time)
- p - Specifies the primary player in whatever event is being run.
- s - Specifies the secondary player in whatever event is being run.
- g or game - Specifies a game variable.
- 1, 2, etc. - Specifies a team variable.
- a - Specifies an argument variable. This could be an argument passed to a command from a player.
- # - Special number target. This can be used to specify a number passed to an event or to do plurals based on the last number
displayed.
- list name - Specifies a list item
Variables may need to be wrapped in parenthesis if they contain special characters or if they need to be placed
right next to another letter. You could do $pk.e for a primary player's enemy killcount, or $(pk.e).
| Variable examples |
# Just show off a few different ways of expressing variables in player commands
# called test, test2, etc.
# $pn - primary player name - The primary player here is the one who ran the command !test
# $pk.e - primary player kills [of] enemies.
# We have to put parenthesis around it since we put a comma right after the variable.
on pcmd_test cmd /say_stat * Hello, $(pn), you have $pk.e enemy kills this game.;
# $pteam - primary player team name
# $(game,k.e) - game enemy kills, this is a running total of everyone's enemy kills.
on pcmd_test2 cmd
/say_stat * $pn you are on team $(p,team). There have been $(game,k.e) kills total this game.;
# $cplayers - server players, number of players currently in the server
# $#s - Displays an 's' if the last number displayed (in this case, $cplayers) was not equal to 1
on pcmd_test3 cmd
/say_stat * There are currently $cplayers player$#s on the server;
# create a list and then call from it
list testlist testitem sense;
on pcmd_test4 cmd
/say_stat * Without the testlist, this would not make $(testlist,testitem).;
|
More to come...
2.1.3 -
Flow Control
The following keywords influence flow control inside command blocks.
They are used to control when and where the commands are run. Flow
Control keywords may be used anywhere in place of a command. They
typically precede command blocks. They may also be stacked:
| Flow stacking example |
# Will make a test command for players and console users that will say
# the line to the server chat. "(1)" will always be true.
on pcmd_test cmd {
if (1) sleep (2) {/say_stat * 1 was true two seconds ago.;};
};
|
if
- if (Expression) {Command Block;}; [else {Command Block;};]
repeat
- repeat (number of times[,sleep time]) {Command Block;};
for
- for (Condition,sleep time) {Command Block};
forlist
- forlist (List name,sleep time[,offset]) {Command Block;};
foreach
- foreach (Expression) {Command Block;};
doas
- doas (UserID[, Secondary UserID]) {Command Block};
2.1.4 -
Command Syntax
Commands are specified with a leading '/' and the command name in scripts. Any options
to be passed to the command are included in parentheses immediately following the command. Other
arguments for the command follow that.
Custom commands may be created by creading an event prefixed by cmd_ (for script commands), ucmd_
(user commands), pcmd_ (player commands), or acmd_ (admin commands). Scripts may access any of
the commands, players in-game may access pcmd and acmd, and users on the console can access either
ucmd or all, depending on their security level. If they have editing permissions on the server,
they may execute any command from their console.
In-Game, commands are accessed by saying the command, prefixed by an exclamation point (!) in public
chat.
| Command Syntax Examples |
# Adds a player command to say hello to them
on pcmd_hi cmd /say_stat * Why, hello there $(pn)!;
# Admins have the ability to alter gravity with this command (Half-Life)
# This first checks the number of arguments given to the command, then
# does the appropriate action. Note the sv_gravity without a leading
# slash (/), this will send it directly to the server console.
on acmd_gravity cmd {
if ($(ac)==1) /say_resp * Usage: !gravity <number>;
else sv_gravity $(a1);
};
# This will add a console user command to allow them to print to
# the HUD for every player in the server
on ucmd_sayh cmd {
if ($(ac)==1) /say_resp * Usage: /sayh $lt;test>;
else /say_hud (chan=0,pos=bottom,color=red) $(a1-);
};
# And finally, a simple abbreviation command for say_hud for scripts
on cmd_sh cmd /say_hud $escape($(a1-));
|
2.1.5 -
Options
Options contain a list of variable assignments seperated by commas. These variables
may be ones for built-in commands or be custom for script commands. They can be
in the format of variable=value or may be a single word that is in the
SYS_OPTIONS list describing the variable and value to assign.
| Option examples |
# This will create a player command that, when run, will print
# the HUD text for 5 seconds, in red.
on pcmd_suck cmd /say_hud (color=red, len=5) You suck!;
# This following example does the exact same thing.
list SYS_OPTIONS blood color=red, len=5;
on pcmd_suck cmd /say_hud (blood) You suck!;
# Options may also be referenced by their custom commands by
# using the 'a' target for the variable
list SYS_OPTIONS blood color=red, len=5;
on pcmd_suck cmd /mysay (adj=suck);
on cmd_mysay cmd /say_hud (blood) You $(aadj)!;
|
|
|
|
