Difference between revisions of "Scripting"

From 4Dimensions
Jump to: navigation, search
Line 167: Line 167:
 
*[[#subskill|subskill]]
 
*[[#subskill|subskill]]
 
==T==
 
==T==
 +
*[[#target|target]]
 
*[[#thirst|thirst]]
 
*[[#thirst|thirst]]
 
*[[#time|time]]
 
*[[#time|time]]
Line 605: Line 606:
 
==colour==
 
==colour==
  
−
See the [[Scripting:Crafting#colour|crafting]] section.
+
See the [[#Scripting:Crafting#colour|crafting]] section.
  
  
Line 703: Line 704:
 
==dyecount==
 
==dyecount==
  
−
See the section on [[Scripting:Crafting#dyecount|crafting]].
+
See the section on [[#Scripting:Crafting#dyecount|crafting]].
  
  
Line 798: Line 799:
 
==in_material_group==
 
==in_material_group==
  
−
See the [[Scripting:Crafting#in_material_group|crafting]] section.
+
See the [[#Scripting:Crafting#in_material_group|crafting]] section.
  
  
Line 965: Line 966:
 
==material==
 
==material==
  
−
See the [[Scripting:Crafting#material|crafting]] section.
+
See the [[#Scripting:Crafting#material|crafting]] section.
  
  
Line 984: Line 985:
 
==max_quality_value==
 
==max_quality_value==
  
−
See the [[Scripting:Crafting#max_quality_value|crafting]] section.
+
See the [[#Scripting:Crafting#max_quality_value|crafting]] section.
  
  
Line 1,045: Line 1,046:
 
==num_of_repairs==
 
==num_of_repairs==
  
−
See the [[Scripting:Crafting#num_of_repairs|crafting]] section.
+
See the [[#Scripting:Crafting#num_of_repairs|crafting]] section.
  
  
Line 1,057: Line 1,058:
 
==origin==
 
==origin==
  
−
See the [[Scripting:Crafting#origin|crafting]] section.
+
See the [[#Scripting:Crafting#origin|crafting]] section.
  
  
Line 1,128: Line 1,129:
 
==quality_value==
 
==quality_value==
  
−
See the [[Scripting:Crafting#quality_value|crafting]] section.
+
See the [[#Scripting:Crafting#quality_value|crafting]] section.
  
  
Line 1,171: Line 1,172:
 
==repair==
 
==repair==
  
−
See the [[Scripting:Crafting#repair|crafting]] section.
+
See the [[#Scripting:Crafting#repair|crafting]] section.
  
  
Line 1,250: Line 1,251:
 
==save_affects==
 
==save_affects==
  
−
See the [[Scripting:Crafting#save_affects|crafting]] section.
+
See the [[#Scripting:Crafting#save_affects|crafting]] section.
  
  
Line 1,262: Line 1,263:
 
==set_colour_name==
 
==set_colour_name==
  
−
See the [[Scripting:Crafting#set_colour_name|crafting]] section.
+
See the [[#Scripting:Crafting#set_colour_name|crafting]] section.
  
  
 
==set_material_name==
 
==set_material_name==
  
−
See the [[Scripting:Crafting#set_material_name|crafting]] section.
+
See the [[#Scripting:Crafting#set_material_name|crafting]] section.
  
  
 
==set_quality_name==
 
==set_quality_name==
  
−
See the [[Scripting:Crafting#set_quality_name|crafting]] section.
+
See the [[#Scripting:Crafting#set_quality_name|crafting]] section.
  
  
Line 1,284: Line 1,285:
 
==stage_value==
 
==stage_value==
  
−
See the [[Scripting:Crafting#stage_value|crafting]] section.
+
See the [[#Scripting:Crafting#stage_value|crafting]] section.
  
  
Line 1,317: Line 1,318:
  
 
Returns the ''weaver'' skill of ''player''.
 
Returns the ''weaver'' skill of ''player''.
 +
 +
 +
==target==
 +
 +
Syntax: target <uid of actor> <var> inv|eq|room|char <argument>
 +
 +
Creates a local variable that holds the target of what an argument refers to, seen through the eyes of ''actor''.
 +
 +
    target %actor% obj inv %arg%
 +
    target %actor% obj eq %arg%
 +
    target %actor% obj room %arg%
 +
   
 +
Matches ''arg'' with an object in inventory, equipment and room, respectively. If there's no match, %obj% will be empty.
 +
 +
    target %actor% ch char %arg%
 +
 +
Matches ''arg'' with a character in the room.
  
  
Line 1,405: Line 1,423:
 
Sends a message to every player in zone 30 in rooms 3001-3010.
 
Sends a message to every player in zone 30 in rooms 3001-3010.
 
It translates to mzrecho for mob triggers, to ozrecho for obj triggers and to wzrecho for room triggers.
 
It translates to mzrecho for mob triggers, to ozrecho for obj triggers and to wzrecho for room triggers.
 +
 +
 +
Scripting Debugger
 +
 +
The script debugger can be used to figure out what's happening in a trigger. This is easier than putting in echos and having to remove them afterwards.
 +
 +
The main command is ''dbg'', followed by a number of subcommands. The syntax for each debugging command is given. It uses the | symbol to denote ''or'': you need to choose between what comes before and after. Arguments between [] are optional in some cases. An argument between <> means what's in between should be replaced by something else. All subcommands may be abbreviated down to the first letter.
 +
 +
All debugging messages start with a yellow [DBG]. More than one imm can debug the same trigger, and each imm will see what the other is doing.
 +
 +
It's not possible to directly debug a load trigger since it doesn't exist at first. One way around this is to temporarily change the type of the trigger and debug it.
 +
 +
Debugging a death trigger is special in that when it hits a breakpoint, the mob dies and the trigger is destroyed. This is how it should be, otherwise a wait would postpone a mob's death. In this case you can also change the trigger type to debug it.
 +
 +
 +
==Start Debugging==
 +
 +
The syntax is
 +
 +
    dbg mob|obj|room [<name>] <trigger vnum>
 +
 +
To start debugging trigger 123 on a cow which is in the room:
 +
 +
    dbg mob cow 123
 +
 +
Debugging trigger 234 on the room:
 +
 +
    dbg room 234
 +
 +
Debugging trigger 177 on a worn or carried object, or when it's in the room:
 +
 +
    dbg obj waybread 177
 +
 +
 +
==Display Info==
 +
 +
The syntax is
 +
 +
    dbg info [<number>] [breakpoints|variables]
 +
 +
To get the debugging list:
 +
 +
    dbg info
 +
 +
It shows all triggers being debugged, if they're running, the breakpoints, and local and global variables.
 +
If there's more than one trigger you only get the trigger names. In that case doing
 +
 +
    dbg info <number>
 +
 +
shows the detailed info for that trigger.
 +
 +
If you're only interested in the breakpoints you can do
 +
 +
    dbg info [<number>] breakpoints
 +
 +
and to only see the variables:
 +
 +
    dbg info [<number>] variables
 +
 +
 +
==Trigger List==
 +
 +
The syntax is
 +
 +
    dbg list [<number>]
 +
 +
It shows the trigger with line numbers, so you know where to set a breakpoint.
 +
 +
 +
==Setting Breakpoints and Variables==
 +
 +
The syntax for setting a breakpoint is
 +
 +
    dbg set [<number>] breakpoint <line number>
 +
 +
When a trigger reaches a breakpoint it stops running. This is because a breakpoint is a long wait inserted before the line where it needs to break. This gives you time to see the current state and go from there.
 +
 +
    dbg set 2 breakpoint 34
 +
 +
sets a breakpoint at line 34 in debugged trigger 2. Giving the same command removes the breakpoint.
 +
 +
The syntax for setting a variable is
 +
 +
    dbg set [<number>] variable <var> <args>
 +
 +
It can only change existing variables:
 +
 +
    dbg set variable var A new value
 +
 +
sets global or local variable ''var'' to ''A new value''.
 +
 +
In this way variables don't have to be changed in the trigger itself when testing.
 +
 +
 +
==Printing expressions==
 +
 +
The syntax is
 +
 +
    dbg print <expression>
 +
 +
This prints the result of any scripting expression between the %% symbols.
 +
If you want to know the value of the local variable %x% you can look it up in dbg info, or do
 +
 +
    dbg print %x%
 +
 +
It can also be used to see the result of an expression not related to the trigger:
 +
 +
    dbg print %now%
 +
    dbg print %time.moon%
 +
 +
 +
==Flow Control==
 +
 +
The syntax for continuing a trigger is
 +
 +
    dbg continue [<number>]
 +
 +
When a trigger is at a breakpoint, this resumes a trigger. Because a breakpoint is a wait, continue can also be used to skip long waits in the trigger.
 +
 +
The syntax for stepping through a trigger is
 +
 +
    dbg next [<number>]
 +
 +
Next executes only the current line and breaks in the next. It's a quick way of going through a trigger line by line without having to set and remove breakpoints.
 +
 +
 +
==Stop Debugging==
 +
 +
The syntax is
 +
 +
    dbg delete [<number>]
 +
 +
The trigger is resumed if it was at a breakpoint and you were the only one debugging the trigger. Delete also happens when you logout.
 +
 +
 +
Crafting
 +
 +
__NOTOC__
 +
A player can craft an object by using ingredients, tools and subskills. The crafts are currently Metalworker, Leatherworker, Stoneworker, Textileworker, Woodworker, Brewing, Scribing and Cooking. The command ''professions'' shows the subskills available in the profession groups.
 +
 +
The object will be a unique item, different from the prototype, that will change with use. The differences are mostly stored in the object values 7 through 14:
 +
 +
    [[#7. Colour|7. Colour]]
 +
    [[#8. Quality|8. Quality]]
 +
    [[#9. Material|9. Material]]
 +
    [[#10. Dyecount|10. Dyecount]]
 +
    [[#11. Origin|11. Origin]]
 +
    [[#12. Stage|12. Stage]]
 +
    [[#13. Repairs|13. Repairs]]
 +
    [[#14. Maximum Quality|14. Maximum Quality]]
 +
 +
Crafting is explained by treating each object value and describing the scripting commands that work on these values.
 +
 +
 +
==7. Colour==
 +
 +
The colours are listed in the crafting section of oedit. The idea is that every colour has its own properties, which are up to the builder.
 +
 +
 +
==colour==
 +
 +
    %obj.colour%
 +
 +
Returns the colour name.
 +
 +
    nop %obj.colour(red)%
 +
 +
Sets the colour of ''obj'' to 3 (red).
 +
 +
 +
==set_colour_name==
 +
 +
    nop %obj.set_colour_name%
 +
 +
Adds or replaces a colour in the shortdesc of ''obj''.
 +
 +
    %echo% %obj.shortdesc%
 +
    nop %obj.set_colour_name%
 +
    %echo% %obj.shortdesc%
 +
 +
Possible results:
 +
 +
a sword<br/>a black sword
 +
 +
a green car<br/>a blue car
 +
 +
some grains<br/>some orange grains
 +
 +
 +
==8. Quality==
 +
==14. Maximum Quality==
 +
 +
Quality and maximum quality are percentages reflecting how good an object is and how good it can be when it's repaired. When an object is created, the maximum quality should be set first, before setting the quality, because quality is forced to be less or equal to the maximum quality.
 +
 +
 +
==max_quality_value==
 +
 +
    %object.max_quality_value%
 +
 +
Returns the max quality value of ''object''.
 +
 +
    nop %obj.max_quality_value(80)%
 +
 +
Sets the max quality value of ''object'' to 80. If the quality is larger than the maximum, it's set to the maximum. The stats are updated as well.
 +
 +
 +
==quality_value==
 +
 +
    %object.quality_value%
 +
 +
Returns the quality value of ''object''.
 +
 +
    nop %obj.quality_value(80)%
 +
 +
Sets the quality value of ''object'' to 80. If the quality is larger than 80, it's set to 80. The stats are updated as well.
 +
 +
 +
==set_quality_name==
 +
 +
    nop %object.set_quality_name%
 +
 +
Sets or replaces the quality name of ''object'' in the shortdesc, depending on the quality value.
 +
 +
 +
==save_affects==
 +
 +
    nop %object.save_affects%
 +
 +
Sets the original stats of ''object'' to the current stats. This should be called if the object has stats and when it's at the maximum quality. Negative stats (e.g. -3 wis or +5 AC) are permanent, the others can be lost if the object loses quality, and gained when it's repaired. If the stats are +1 wis, -1 AC, -3 str then the object has 2 positive stats. One stat is lost when the quality drops below 2/3 and the remaining stat is gone once the quality reaches 1/3 of the maximum. A repair to the maximum quality recovers all lost stats.
 +
 +
 +
==9. Material==
 +
 +
Every object is made out of a certain material, which belong to a material group. The material groups are: base-material, metal, stone, organic, textile, wood, and other. The materials are listed in the crafting section of oedit.
 +
 +
 +
==material==
 +
 +
    %object.material%
 +
 +
Returns the name of the material ''object'' is made of.
 +
 +
    nop %object.material(plastic)
 +
 +
Sets the material of ''object'' to plastic.
 +
 +
 +
==in_material_group==
 +
 +
    %object.in_material_group(organic)%
 +
 +
Returns 1 if ''object'' is made of a material from the group ''organic''.
 +
 +
 +
==10. Dyecount==
 +
 +
Dyeing gives an object colour. To add a bit of risk to dyeing, the dyecount is saved so you can check if an object should turn black forever for example.
 +
 +
 +
==dyecount==
 +
 +
    %object.dyecount%
 +
 +
Returns the number of times ''object'' has been dyed.
 +
 +
    nop %object.dyecount(3)%
 +
 +
Sets the dyecount of ''object'' to 3.
 +
 +
 +
==11. Origin==
 +
 +
The origin of an object may determine the quality of the end product, or what you can do with it. The origins are listed in the crafting section of oedit. Currently, there are origins for trees and animals. When a tree is lumberjacked, the log gets the origin of the tree. Similarly, the skin from a corpse automatically gets the origin of the animal.
 +
 +
 +
==origin==
 +
 +
    %object.origin%
 +
 +
Returns the origin name of ''object''.
 +
 +
 +
==12. Stage==
 +
 +
To make sure the end product is always made in the same order, the work can be divided into stages. At each step the activity can be matched with the stage.
 +
 +
 +
==stage_value==
 +
 +
    %object.stage_value%
 +
 +
Returns the stage value of ''object''.
 +
 +
    %object.stage_value(2)%
 +
 +
Sets the stage value of ''object'' to 2.
 +
 +
 +
==13. Repairs==
 +
 +
An object can be repaired, which raises the quality and returns some or all of the original stats. When the maximum quality becomes zero, the object reverts to being a normal object and can no longer be repaired.
 +
 +
 +
==num_of_repairs==
 +
 +
    %object.num_of_repairs%
 +
 +
Returns the number of times ''object'' has been repaired.
 +
 +
 +
==repair==
 +
 +
    %object.repair(70)%
 +
 +
Sets the max quality of ''object'' to 70, or to the original max quality if it's smaller than 70. The quality is set to the maximum quality. The number of repairs is increased by one and the affects are updated.
 +
 +
 +
==save_affects==
 +
 +
    nop %object.save_affects%
 +
 +
Sets the original stats of ''object'' to the current stats. This should be called if the object has stats and when it's at the maximum quality. Negative stats (e.g. -3 wis or +5 AC) are permanent, the others can be lost if the object loses quality, and gained when it's repaired. If the stats are +2 wis, -2 AC, -1 str then the object has four positive stats. One stat is lost if the object quality drops below 80%. A second stat is lost if it drops below 60%, and all stats are gone if the quality is below 20%. A repair may recover all lost stats.

Revision as of 08:51, 7 May 2017

There's a good scripting reference at TBA, but there are differences with 4D's scripting commands. These pages aim to give an overview of these commands. One notable difference is crafting, for which several new commands and fields have been added.

To give an example of the terms used in these pages, consider this line: 

   nop %actor.exp(1000)%

Here nop is the command, actor is the variable, exp is the field and 1000 is the subfield.

A character is a mob or player. The examples usually use actor when it concerns a character.

In scripts, a uid is the character '}' followed by a number. The number is the id of a character, object or room. A uid is used to manipulate what it points to, from any script.

To make it easier to debug scripts, a scripting debugger is available. It can set breakpoints, view or change variables, step through a trigger, and show the result of any scripting expression.

The commands, fields and variables are grouped alphabetically:

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z


A

B

C

D

E

F

G

H

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

X

Y

Z


The aff_ fields are used to get or change the stats of an object.

aff_ac

   %object.aff_ac%

Returns the AC an object gives. 

   nop %object.aff_ac(-5)%

Sets the AC of an object to -5.


aff_age

   %object.aff_age%

Returns the age an object gives. 

   nop %object.aff_age(125)%

Sets the age of an object to 125.


aff_breath_def

   %object.aff_breath_def%

Returns the breath defense an object gives. 

   nop %object.aff_breath_def(50)%

Sets the breath defense of an object to 50.


aff_cha

   %object.aff_cha%

Returns the charisma an object gives. 

   nop %object.aff_cha(2)%

Sets the charisma of an object to 2.


aff_con

   %object.aff_con%

Returns the constitution an object gives. 

   nop %object.aff_con(-3)%

Sets the constitution of an object to -3.


aff_coolness

   %object.aff_coolness%

Returns the coolness an object gives. 

   nop %object.aff_coolness(5)%

Sets the coolness of an object to 5.


aff_damroll

   %object.aff_damroll%

Returns the damroll an object gives. 

   nop %object.aff_damroll(3)%

Sets the damroll of an object to 3.


aff_dex

   %object.aff_dex%

Returns the dexterity an object gives. 

   nop %object.aff_dex(1)%

Sets the dexterity of an object to 1.


aff_hitroll

   %object.aff_hitroll%

Returns the hitroll an object gives. 

   nop %object.aff_hitroll(2)%

Sets the hitroll of an object to 2.


aff_int

   %object.aff_int%

Returns the intelligence an object gives. 

   nop %object.aff_int(3)%

Sets the intelligence of an object to 3.


aff_maxhit

   %object.aff_maxhit%

Returns the maximum hitpoints an object gives. 

   nop %object.aff_maxhit(700)%

Sets the maximum hitpoints of an object to 700.


aff_maxmana

   %object.aff_mana%

Returns the maximum mana an object gives. 

   nop %object.aff_maxmana(2000)%

Sets the maximum mana of an object to 2000.


aff_maxmove

   %object.aff_maxmove%

Returns the maximum moves an object gives. 

   nop %object.aff_maxmove(500)%

Sets the maximum moves of an object to 500.


aff_mine_bonus

   %object.aff_mine_bonus%

Returns the mine bonus an object gives. 

   nop %object.aff_mine_bonus(10)%

Sets the mine bonus of an object to 10.


aff_mine_protection

   %object.aff_mine_protection%

Returns the mine protection an object gives. 

   nop %object.aff_mine_protection(25)%

Sets the mine protection of an object to 25.


aff_mine_speed

   %object.aff_mine_speed%

Returns the mine speed an object gives. 

   nop %object.aff_mine_speed(30)%

Sets the mine speed of an object to 30.


aff_mine_stealth

   %object.aff_mine_stealth%

Returns the mine stealth an object gives. 

   nop %object.aff_mine_stealth(10)%

Sets the mine stealth of an object to 10.


aff_paralyze_def

   %object.aff_paralyze_def%

Returns the paralyze defense an object gives. 

   nop %object.aff_paralyze_def(5)%

Sets the paralyze defense of an object to 5.


aff_petrify_def

   %object.aff_petrify_def%

Returns the petrify defense an object gives. 

   nop %object.aff_petrify_def(3)%

Sets the petrify defense of an object to 3.


aff_rod_def

   %object.aff_rod_def%

Returns the rod defense an object gives. 

   nop %object.aff_rod_def(-2)%

Sets the rod defense of an object to -2.


aff_regen_hit

   %object.aff_regen_hit%

Returns the hitpoint regeneration an object gives. 

   nop %object.aff_regen_hit(10)%

Sets the hitpoint regeneration of an object to 10.


aff_regen_mana

   %object.aff_regen_mana%

Returns the mana regeneration an object gives. 

   nop %object.aff_regen_mana(5)%

Sets the mana regeneration of an object to 5.


aff_regen_move

   %object.aff_regen_move%

Returns the move regeneration an object gives. 

   nop %object.aff_regen_move(10)%

Sets the move regeneration of an object to 10.


aff_speed

   %object.aff_speed%

Returns the speed an object gives. 

   nop %object.aff_speed(50)%

Sets the speed of an object to 50.


aff_spell_def

   %object.aff_spell_def%

Returns the spell defense an object gives. 

   nop %object.aff_spell_def(10)%

Sets the spell defense of an object to 10.


aff_str

   %object.aff_str%

Returns the strength an object gives. 

   nop %object.aff_str(2)%

Sets the strength of an object to 2.


aff_wis

   %object.aff_wis%

Returns the wisdom an object gives. 

   nop %object.aff_wis(-1)%

Sets the wisdom of an object to -1.


assemble

   nop %actor.assemble(123)%

If the inventory of actor holds the ingredients of the assembly, then they are replaced by object 123.


assembly

   %assembly.exists(103)%

Returns 1 if an assembly exists which creates an object with vnum 103. 

   %assembly.craft(5770)%

Returns 1 if an assembly exists that creates object 5770 by using the command craft. 

   %assembly.brew(beer bottle)%

Returns 1 if an assembly exists that creates an object named beer bottle with the command brew.


assemblycheck

   %actor.assemblycheck(123)%

Returns 1 if actor has the ingredients to assemble object 123.


attach

   attach %mob% 123

Attaches trigger 123 to mob which is a uid here. You can also attach to an id: 

   attach %obj.id% 234


body

   %actor.body%

Returns all body positions. 

   nop %player.body(crest)%

Toggles the extra body position crest. Only extra body positions can be toggled.


bodycheck

   %player.bodycheck(rknee)

Returns 1 if player has the body position rknee (mobs have all body positions).


carriedamount

   %actor.carriedamount%

Returns the number of items actor has in inventory.


carriedweight

   %actor.carriedweight%

Returns the total weight actor is carrying in inventory and equipment combined.


charat

Returns a letter in a string: 

   eval word test
   %echo% %word.charat(3)%

Result: S


clan

   %player.clan%

Returns the clan number player is in. 

   %player.clan(2)%

Puts player in clan 2.


clanname

   %player.clanname%

Returns the name of the clan player is in.


clanrank

   %player.clanrank%

Returns the clan rank of player. 

   %player.clanrank(3)%

Sets the clan rank of player to 3.


class_tier

   %actor.class_tier%

Returns the tier of actor. 

   %mob.class_tier(3)%

Sets the tier of mob to 3.


colour

See the crafting section.


contained_by

   %object.contained_by%

Returns the uid of the container which holds the object.


cool

   %player.cool%

Returns the coolness of player. 

   %player.cool(7)%

Adds 7 to the coolness of player. The resulting value will lie between 3 and 22.


damroll

   %player.damroll%

Returns the damroll of player. 

   %player.damroll(50)%

Adds 50 to the damroll of player. The resulting value will lie between 3 and 150.


dest

   %mob.dest%

Returns the room vnum of the destination of the mob. 

   %mob.dest(123)%

Sets the room vnum of the destination of mob to 123. 

   %object.dest%

Returns the room vnum of the destination of the object. 

   %object.dest(234)%

Sets the room vnum of the destination of object to 234.


dg_affect

Sets or removes an affect or apply on a character. See help dg_affect.


dg_dest

   dg_dest add 567 self

Add room 567 to the destination list of the mob or object the trigger is on. 

   dg_dest remove 123 %object%

Remove destination room 123 from object. 

   dg_dest remove all %mob%

Remove the entire travel list from mob.


dg_letter

Returns a letter in a string: 

   eval word test
   dg_letter letter 3 %word%
   %echo% %letter%

Result: S


dg_peek

   dg_peek %actor% 3001

Shows room 3001 to actor.


dimension

   %room.dimension%

Returns the dimension a room is in.


dyecount

See the section on crafting.


exp_needed

   %player.exp_needed%

Returns the exp player needs to make the next level.


flag

   %room.flag(peaceful)%

Returns 1 if the room is peaceful. The flag names are the same ones as in the room flags section of redit.


follower_in_room

   %player.follower_in_room(123)%

Returns 1 if the follower with vnum 123 of player is in the same room as player. 

   %player.follower_in_room(the black dog)%

Returns 1 if a follower of player is called the black dog and is in the same room as player.


forget_subskills

   %player.forget_subskills(combatant)%

Makes player lose all subkills belonging to the profession combatant.


function

   function 123 book 1 shield

Calls function trigger 123 with the argument book 1 shield, which is available to the trigger through the variable %args%. A function trigger runs inside the script of the calling trigger, so it has access to all global variables. A return value can be set in another global variable, which the calling trigger can use once the function trigger finishes.


has_pos

   %object.has_pos(wield)%

Returns 1 if object can be wielded.


has_script

   %room.has_script%

Returns 1 if there's a script attached to room.


hitroll

   %player.hitroll%

Returns the hitroll of player.


hunger

   %player.hunger%

Returns the hunger value of player. It's a measure of how full a player is. 

   nop %player.hunger(50)%

Sets the hunger value of player to 50. If the value is -1 then player will never be hungry. If the value is 0 then player is extremely hungry. If the value is larger than 47 then player is full.


hunt

   %mob.hunt%

Returns 1 if mob is hunting and makes mob move towards the target.


hunting

   %mob.hunting%

Returns the uid of the character mob is hunting.


in_material_group

See the crafting section.


innate

   %object.innate%

Returns the spell number of the innate on object. 

   nop %object.innate(1)%

Sets the innate of object to armor. 

   nop %object.innate(shield)%

Sets the innate of object to shield.


insert_word

Syntax: insert_word <word> <pos> <v>

Inserts word <word> at position <pos> in variable <v>.

The first position is 1. If the position is larger than the number of words, the word is appended. 

   eval sentence Hello how are you?
   insert_word there, 2 sentence
   %echo% %sentence%

Result: Hello there, how are you?


is_cheater

   %player.is_cheater%

Returns 1 if player has the cheater flag. 

   nop %player.is_cheater(on)%

Sets player's cheater flag. 

   nop %player.is_cheater(off)%

Removes player's cheater flag.


is_flying

   %actor.is_flying%

Returns 1 if actor is flying.


is_helper

   %player.is_helper%

Returns 1 if player is a newbie helper. 

   nop %player.is_helper(on)%

Makes player a newbie helper. 

   nop %player.is_helper(off)%

Stops player from being a newbie helper.


is_herd_cattle

   %mob.is_herd_cattle%

Returns 1 if mob is flagged as a cattle herd mob. These mobs follow other mobs from the same herd.

is_herd_horse

   %mob.is_herd_horse%

Returns 1 if mob is flagged as a horse herd mob. These mobs follow other mobs from the same herd.

is_herd_sheep

   %mob.is_herd_sheep%

Returns 1 if mob is flagged as a sheep herd mob. These mobs follow other mobs from the same herd.


is_hero

   %player.is_hero%

Returns 1 if player is a hero.


is_npc

   %actor.is_npc%

Returns 1 if actor is a mob.


is_pk

   %player.is_pk%

Returns 1 if player is a PK-er.


is_pregnant

   %player.is_pregnant%

Returns 1 if player is expecting. 

   nop %player.is_pregnant(on)%

Makes player pregnant. 

   nop %player.is_pregnant(off)%

Stops player's pregnancy.


is_roleplay

   %player.is_roleplay%

Returns 1 if player has an RP flag.


is_rpl

   %player.is_rpl%

Returns 1 if player is an RP leader.


is_wizinvis

   %mob.is_wizinvis%

Returns 1 if mob is wizinvis.


lag

   %lag% %actor% 100

Lags actor for 10 seconds (the maximum is 300 = 30 seconds).

%lag% translates to mlag for mob triggers, olag for object triggers and wlag for room triggers.


longdesc

   %mob.longdesc%

Returns the look desc of mob.


material

See the crafting section.


maxcarriedamount

   %actor.maxcarriedamount%

Returns the maximum number of items actor can carry.


maxcarriedweight

   %actor.maxcarriedweight%

Returns the maximum weight actor can carry.


max_quality_value

See the crafting section.


maxstamina

   %actor.maxstamina%

Returns the maximum stamina of actor.


mid

   %mob.mid%

Returns the id of the master of mob.


mod

   %mod.5(2)%

Returns 5 % 2 (the modulo operation).


mzreset

   mzreset

If it's a mob trigger, the mob resets the zone it's in.


next_follower

   %actor.next_follower%

Returns the id of the next follower if actor is a follower.


next_in_list

   %object.next_in_list%

If object is inside a container, it returns the uid of the next object.


nographics

   %player.nographics%

Returns 1 if player has nographics toggled on.


now

   %now%

Returns the current unix time.


num_of_repairs

See the crafting section.


omr

   %omr%

Returns mobile for a mob trigger, object for an obj trigger and room for a room trigger.


origin

See the crafting section.


people

   %object.people%

Returns the uid of the first character in the room of object.

The object may be in a room, worn, carried or inside a container. 

   %object.people(123)%

Returns the uid of the first character with vnum 123 in the room.

The same goes for 

   %room.people%
   %room.people(123)%
   %actor.people%
   %actor.people(123)%


perc

   %player.perc%

Returns the involvement of player. For example: 33.3333


pkdeaths

   %player.pkdeaths%

Returns the number of deaths of player in a PK fight.


pkkills

   %player.pkkills%

Returns the number of PK victories of player.


pkpoints

   %player.pkpoints%

Returns the number of PK points player has.


playeruid

   playeruid p Bob

Sets p to the uid of Bob, if Bob is online.


purgemob

   purgemob %mob%

Completely purges mob, including equipment and inventory. 

   purgemob self

This works if it's a mob trigger.


quality_value

See the crafting section.


random

   %random.char%

Returns the uid of a random character in the room. It won't be an imm unless it has nohassle off.

If it's a mob trigger then the character is seen by the mob. 

   %random.dir%

Returns a random direction you can move in. 

   %random.7%

Returns a number from 1 to 7.


realday

   %realday%

Returns 86400, the number of seconds in a day.


realhour

   %realhour%

Returns 3600, the number of seconds in an hour.


remorts

   %player.remorts%

Returns the number of remorts of player.


repair

See the crafting section.


replace_letter

Usage: replace_letter <letter> <position> <variable>

Replaces a letter at a certain position in a variable. 

   eval x test
   replace_letter n 3 x
   %echo% %x%

Result: Tent


replace_word

Usage: replace_word <word> <position> <variable>

Replaces a word at a certain position in a variable. 

   eval x hi there
   replace_word hello 1 x
   %echo% %x%

Result: Hello there


restring

Usage: restring <id|uid> <field> <value>

Changes an object desc. 

   restring 123 name heavy object

Renames the object with id 123. 

   restring %object% short a heavy object

Changes the shortdesc of object. 

   restring %object.id% long A heavy object is lying here.

Changes the long desc of object. 

   restring %object% extra 'side right' The right side is very interesting.

Adds an extra desc for side right. 

   restring %self% extra 'side right' The right side is not very interesting anymore.

Changes the extra desc for side right.


ridden_by

   %actor.ridden_by%

Returns the uid of the character riding actor.


riding

   %actor.riding%

Returns the uid of the character actor is riding.


rpgroup

   %player.rpgroup%

Returns the name of the RP group player is in.


save_affects

See the crafting section.


sector

   %room.sector%

Returns the sector name of room.


set_colour_name

See the crafting section.


set_material_name

See the crafting section.


set_quality_name

See the crafting section.


speed

   %actor.speed%

Returns the speed of actor.


stage_value

See the crafting section.


stamina

   %actor.stamina%

Returns the stamina of actor. 

   nop %actor.stamina(75)%

Sets the stamina of actor to 75. The value will lie between 0 and the maximum of actor.


subdecrease

   %player.subdecrease(pillage)%

Decreases the skill player has in pillage by 2%.


subincrease

   %player.subincrease(garotte)%

Increases the skill player has in garotte by 2%. The subskill is added if player doesn't know it.


subskill

   %player.subskill(weaver)%

Returns the weaver skill of player.


target

Syntax: target <uid of actor> inv|eq|room|char <argument>

Creates a local variable that holds the target of what an argument refers to, seen through the eyes of actor. 

   target %actor% obj inv %arg%
   target %actor% obj eq %arg%
   target %actor% obj room %arg%

Matches arg with an object in inventory, equipment and room, respectively. If there's no match, %obj% will be empty. 

   target %actor% ch char %arg%

Matches arg with a character in the room.


thirst

   %player.thirst%

Returns the thirst value of player. It's a measure of how full a player is. 

   nop %player.thirst(30)%

Sets the thirst value of player to 30. If the value is -1 then player will never be thirsty. If the value is 0 then player is parched. If the value is larger than 47 then player is full.


time

   %time.hour%
   %time.day%
   %time.month%
   %time.year%
   %time.season%
   %time.moon%

Returns the respective mud time.


trade

   %player.trade%

Returns the number of tradepoints player has. 

   nop %player.trade(10)%

Adds 10 tradepoints to player's balance.


val

   %object.val1%

Returns object value 1 of object. 

   nop %object.val2(7)%

Sets object value 2 of object to 7.


word_count

   %text.word_count%

Returns the number of words in text.


wordat

Returns a word from a sentence. 

   eval text Once upon a time
   %echo% %text.wordat(2)%

Result: Upon


zecho

   %zecho% 30 Boo!

Sends a message to all players in zone 30. It translates to mzecho for mob triggers, to ozecho for obj triggers and to wzecho for room triggers.


zonename

   %room.zonename%

Returns the name of the zone room is in.


zrecho

   %zrecho% 30 3001 3010 Boo!

Sends a message to every player in zone 30 in rooms 3001-3010. It translates to mzrecho for mob triggers, to ozrecho for obj triggers and to wzrecho for room triggers.


Scripting Debugger

The script debugger can be used to figure out what's happening in a trigger. This is easier than putting in echos and having to remove them afterwards.

The main command is dbg, followed by a number of subcommands. The syntax for each debugging command is given. It uses the | symbol to denote or: you need to choose between what comes before and after. Arguments between [] are optional in some cases. An argument between <> means what's in between should be replaced by something else. All subcommands may be abbreviated down to the first letter.

All debugging messages start with a yellow [DBG]. More than one imm can debug the same trigger, and each imm will see what the other is doing.

It's not possible to directly debug a load trigger since it doesn't exist at first. One way around this is to temporarily change the type of the trigger and debug it.

Debugging a death trigger is special in that when it hits a breakpoint, the mob dies and the trigger is destroyed. This is how it should be, otherwise a wait would postpone a mob's death. In this case you can also change the trigger type to debug it.


Start Debugging

The syntax is 

   dbg mob|obj|room [<name>] <trigger vnum>

To start debugging trigger 123 on a cow which is in the room: 

   dbg mob cow 123

Debugging trigger 234 on the room: 

   dbg room 234

Debugging trigger 177 on a worn or carried object, or when it's in the room: 

   dbg obj waybread 177


Display Info

The syntax is 

   dbg info [<number>] [breakpoints|variables]

To get the debugging list: 

   dbg info

It shows all triggers being debugged, if they're running, the breakpoints, and local and global variables. If there's more than one trigger you only get the trigger names. In that case doing 

   dbg info <number>

shows the detailed info for that trigger.

If you're only interested in the breakpoints you can do 

   dbg info [<number>] breakpoints

and to only see the variables: 

   dbg info [<number>] variables


Trigger List

The syntax is 

   dbg list [<number>]

It shows the trigger with line numbers, so you know where to set a breakpoint.


Setting Breakpoints and Variables

The syntax for setting a breakpoint is 

   dbg set [<number>] breakpoint <line number>

When a trigger reaches a breakpoint it stops running. This is because a breakpoint is a long wait inserted before the line where it needs to break. This gives you time to see the current state and go from there. 

   dbg set 2 breakpoint 34

sets a breakpoint at line 34 in debugged trigger 2. Giving the same command removes the breakpoint.

The syntax for setting a variable is 

   dbg set [<number>] variable  <args>

It can only change existing variables: 

   dbg set variable var A new value

sets global or local variable var to A new value.

In this way variables don't have to be changed in the trigger itself when testing.


Printing expressions

The syntax is 

   dbg print <expression>

This prints the result of any scripting expression between the %% symbols. If you want to know the value of the local variable %x% you can look it up in dbg info, or do 

   dbg print %x%

It can also be used to see the result of an expression not related to the trigger: 

   dbg print %now%
   dbg print %time.moon%


Flow Control

The syntax for continuing a trigger is 

   dbg continue [<number>]

When a trigger is at a breakpoint, this resumes a trigger. Because a breakpoint is a wait, continue can also be used to skip long waits in the trigger.

The syntax for stepping through a trigger is 

   dbg next [<number>]

Next executes only the current line and breaks in the next. It's a quick way of going through a trigger line by line without having to set and remove breakpoints.


Stop Debugging

The syntax is 

   dbg delete [<number>]

The trigger is resumed if it was at a breakpoint and you were the only one debugging the trigger. Delete also happens when you logout.


Crafting


A player can craft an object by using ingredients, tools and subskills. The crafts are currently Metalworker, Leatherworker, Stoneworker, Textileworker, Woodworker, Brewing, Scribing and Cooking. The command professions shows the subskills available in the profession groups.

The object will be a unique item, different from the prototype, that will change with use. The differences are mostly stored in the object values 7 through 14: 

   7. Colour
   8. Quality
   9. Material
   10. Dyecount
   11. Origin
   12. Stage
   13. Repairs
   14. Maximum Quality

Crafting is explained by treating each object value and describing the scripting commands that work on these values.


7. Colour

The colours are listed in the crafting section of oedit. The idea is that every colour has its own properties, which are up to the builder.


colour

   %obj.colour%

Returns the colour name. 

   nop %obj.colour(red)%

Sets the colour of obj to 3 (red).


set_colour_name

   nop %obj.set_colour_name%

Adds or replaces a colour in the shortdesc of obj. 

   %echo% %obj.shortdesc% 
   nop %obj.set_colour_name%
   %echo% %obj.shortdesc%

Possible results:

a sword
a black sword

a green car
a blue car

some grains
some orange grains


8. Quality

14. Maximum Quality

Quality and maximum quality are percentages reflecting how good an object is and how good it can be when it's repaired. When an object is created, the maximum quality should be set first, before setting the quality, because quality is forced to be less or equal to the maximum quality.


max_quality_value

   %object.max_quality_value%

Returns the max quality value of object. 

   nop %obj.max_quality_value(80)%

Sets the max quality value of object to 80. If the quality is larger than the maximum, it's set to the maximum. The stats are updated as well.


quality_value

   %object.quality_value%

Returns the quality value of object. 

   nop %obj.quality_value(80)%

Sets the quality value of object to 80. If the quality is larger than 80, it's set to 80. The stats are updated as well.


set_quality_name

   nop %object.set_quality_name%

Sets or replaces the quality name of object in the shortdesc, depending on the quality value.


save_affects

   nop %object.save_affects%

Sets the original stats of object to the current stats. This should be called if the object has stats and when it's at the maximum quality. Negative stats (e.g. -3 wis or +5 AC) are permanent, the others can be lost if the object loses quality, and gained when it's repaired. If the stats are +1 wis, -1 AC, -3 str then the object has 2 positive stats. One stat is lost when the quality drops below 2/3 and the remaining stat is gone once the quality reaches 1/3 of the maximum. A repair to the maximum quality recovers all lost stats.


9. Material

Every object is made out of a certain material, which belong to a material group. The material groups are: base-material, metal, stone, organic, textile, wood, and other. The materials are listed in the crafting section of oedit.


material

   %object.material%

Returns the name of the material object is made of. 

   nop %object.material(plastic)

Sets the material of object to plastic.


in_material_group

   %object.in_material_group(organic)%

Returns 1 if object is made of a material from the group organic.


10. Dyecount

Dyeing gives an object colour. To add a bit of risk to dyeing, the dyecount is saved so you can check if an object should turn black forever for example.


dyecount

   %object.dyecount%

Returns the number of times object has been dyed. 

   nop %object.dyecount(3)%

Sets the dyecount of object to 3.


11. Origin

The origin of an object may determine the quality of the end product, or what you can do with it. The origins are listed in the crafting section of oedit. Currently, there are origins for trees and animals. When a tree is lumberjacked, the log gets the origin of the tree. Similarly, the skin from a corpse automatically gets the origin of the animal.


origin

   %object.origin%

Returns the origin name of object.


12. Stage

To make sure the end product is always made in the same order, the work can be divided into stages. At each step the activity can be matched with the stage.


stage_value

   %object.stage_value%

Returns the stage value of object. 

   %object.stage_value(2)%

Sets the stage value of object to 2.


13. Repairs

An object can be repaired, which raises the quality and returns some or all of the original stats. When the maximum quality becomes zero, the object reverts to being a normal object and can no longer be repaired.


num_of_repairs

   %object.num_of_repairs%

Returns the number of times object has been repaired.


repair

   %object.repair(70)%

Sets the max quality of object to 70, or to the original max quality if it's smaller than 70. The quality is set to the maximum quality. The number of repairs is increased by one and the affects are updated.


save_affects

   nop %object.save_affects%

Sets the original stats of object to the current stats. This should be called if the object has stats and when it's at the maximum quality. Negative stats (e.g. -3 wis or +5 AC) are permanent, the others can be lost if the object loses quality, and gained when it's repaired. If the stats are +2 wis, -2 AC, -1 str then the object has four positive stats. One stat is lost if the object quality drops below 80%. A second stat is lost if it drops below 60%, and all stats are gone if the quality is below 20%. A repair may recover all lost stats.

Retrieved from "http://4dimensions.org/wiki/index.php?title=Scripting&oldid=1143"