You can manipulate string or object fields, getting or setting key=value pairs.
Fields you would most often want to use this on are: matvals,skills,pocket,slot1,slot2,slot3 however there is no restriction.
Yes pocket is a new field for an object.. I will promote this instead of pocket variables.. maybe replace them all-together.
Syntax: manipulate {thing} set|get {key} to|add|take {value|$variable[ cap {amount}]} [by {delimiter}]
(optionally this can be called 'value of' or 'value for' but Im thinking manipulate is nicer..
You are either setting a key=value pair into a string or getting the value for the key from a string.
You can use either an object's field eg $actor's slot1 or any variable name. This means you can directly manipulate an objects field without having tor read it into a variable, manipulate it, then write it back.
You should not enclose the key in quotes.. however you can use a variable to indicate the key.
You should enclose the value in quotes, or use a variable.
If you are adding a blank variable then you will remove the key=value pair from the string and everything shuffles up to take its place.
The following example will remove the mouse={somevalue} from the string. It leaves $oldkey and $oldvalue with the contents of this key=value pair before they were removed.
manipulate $thing set mouse to "";
(manipulate, mani, value of or value for) are all synonymous
(get, var or read) all get the current value from the key and leave it in a variable
(set, put, update or write) all set the key=value par into the string
(=, to, as, with, add or take) separate the key from the value
So technically:
value for $thing write mouse as "cute";
is the same as:
manipulate $thing set mouse to "cute";
(I just havnt tired any of the variations yet)
The global @list is used so you will find you can use foreach in list do {block}; and you will have:
$list_line = the complete key=value string
$for_key = the key;
$for_value = the value;
You also have the standard @list variables:
$list_count = how many items in this list..
$randomitem = a randomkey=value pait from the list
$istitem = the key=value pair you are manipulating
You can also refer to specific numbered key=value pairs with $list[n]
either reading values $pair = $list[0];
Or setting values so you can access them in a foreach loop: $list[4]='bingo=bingo";
When adding or taking you can optional indicate a cap amount. if the existing value exceeds this cap amount then it will be set to this cap amount and a variable called $capped will be set to 'yes'.
Since the value is always a string or a variable, you can embed variables within it . Here are some examples:
$max = 5;
$mini = -3; rem - the variable $min is a reserved word, sorry;
$step = 1;
manipulate $actor's pocket set hunger add "1";
manipulate $actor's pocket set hunger add "1 cap 10";
manipulate $actor's pocket set hunger add "1 cap $max";
manipulate $actor's pocket set hunger add "$step cap $max";
$cped = "$step cap $max";
$key = "hunger";
manipulate $actor's pocket set $key add $cped;
manipulate $actor's pocket set hunger take "5 cap $mini";
if $capped eq "yes" then capreached;
The delimer is a number or letter (or anything) wrapped in out-facing curly brackets eg }1{ and }8{ or even }abc{. I affectionatly called thes number butterflies as they looks ilke butterflies and will mostly be numbers.
The default delimiter is 1 which is }1{ and you dont need to specif this. All other delimiters will need to be specified using the by n.
For sanities sake, use ascending numbers when nesting key=value pairs within other key=value pairs.
Some basic setting and getting examples:
$pop = "mouse=no";
manipulate $pop set balloon to "yes";
$pop is now "mouse=no}1{balloon=yes" with }1{ as the delimiter by default
Lets try and read the values of 'mouse' and 'balloon' from $pop using default delimiters:
manipulate $pop get mouse to $answer;
print "Will the mouse pop? $answer";
manipulate $pop get balloon to $answer;
print "Will the balloon pop? $answer";
Lest now save our pop string as a value into another string:
$purr = 'cat=yes}1{frog=no';
manipulate $touch set prick to $pop by 2;
manipulate $touch set stroke to $purr by 2;
$touch now has two sets of delimited strings.. the outer is delimited by }2{ and the inner by }1{
it looks like this:
"prick=mouse=no}1{balloon=yes}2{stroke=cat=yes}1{frog=no"
Nested key=value pairs do look odd with key=key=value, but it all makes logical sense and is quite readable.
Be very careful about reading back values.. if you want to read back the value for 'cat' you first have to read the value for 'stroke' delimited by 2 then you can get to the 'cat' delimited by 1.
Confusingly, but no-doubt useful, we can do this again.. and again, using different delimiters.