| 1 |
Fields that the rest of loader.l doesn't understand are recorded in the |
| 2 |
object as 'key/value fields'. The first word on the line is the key, and the |
| 3 |
rest of the line (leading and trailing whitespace is stripped) is the value |
| 4 |
(which may be an empty string!). |
| 5 |
|
| 6 |
These allow arbitrary addition of new fields to the object definition |
| 7 |
without any changes to the loader/saver, and without any increase in object |
| 8 |
space. Use these to reduce the overloading of various fields for sets of |
| 9 |
infrequently used objects. |
| 10 |
|
| 11 |
Storing as key/value pairing makes it so that it is only parsed once during |
| 12 |
loading - this makes accessing data much faster than if it was just a free |
| 13 |
block of text that needed parsing each time something might need to get a |
| 14 |
key. The data itself does remain as text, so if the data is desired in |
| 15 |
another format, function will need to convert it (eg, atoi) as needed. |
| 16 |
|
| 17 |
How to use them: |
| 18 |
================= |
| 19 |
|
| 20 |
From inside crossfire-server (these are defined in object.c): |
| 21 |
|
| 22 |
const char *get_ob_key_value(object *op, const char *key) |
| 23 |
|
| 24 |
Returns the value parameter for the given key, or NULL if the |
| 25 |
object doesn't have such an extra_field. The string returned is |
| 26 |
a shared string so should not be modified. |
| 27 |
|
| 28 |
Note there is no way to tell if the field does not exist or has |
| 29 |
been set to an empty value. If this differentiation is necessary, |
| 30 |
a value should be stored away. |
| 31 |
|
| 32 |
int set_ob_key_value(object *op, const char *key, const char *value, int add_key) |
| 33 |
|
| 34 |
Sets the value for the given key. If add_key is true, it will add the key |
| 35 |
if not defined, otherwise, it only updates existing keys. Returns |
| 36 |
true/false based on success. |
| 37 |
|
| 38 |
The passed in value is converted to a shared string. Thus, once this function |
| 39 |
is called, modifying value should not be done. |
| 40 |
|
| 41 |
Note - usually add_key should be false - there should be little reason |
| 42 |
to only update existing keys - if you want to store that data away, you should |
| 43 |
do it regardless of the type. |
| 44 |
|
| 45 |
Passing in NULL as the value effectively clears the value. |
| 46 |
|
| 47 |
|
| 48 |
Use in objects/maps: |
| 49 |
-------------------- |
| 50 |
|
| 51 |
Just add the lines to the object, eg |
| 52 |
foo bar |
| 53 |
|
| 54 |
will automatically be handled so that key 'foo' is set to 'bar' |
| 55 |
|
| 56 |
|
| 57 |
When to use key/value compared to adding new fields: |
| 58 |
==================================================== |
| 59 |
|
| 60 |
The following should be considered: |
| 61 |
|
| 62 |
1) Access to key/value fields is slower than accessing a field directly. |
| 63 |
Thus, should not be used in time sensitive areas (combat related |
| 64 |
basically) |
| 65 |
|
| 66 |
For example, if the only time the key/value would need to be used is by |
| 67 |
player activating the object, that doesn't happen all that often, so good |
| 68 |
option. |
| 69 |
|
| 70 |
If however the key/value would be examined for map updates (say |
| 71 |
glow_radius) probably not a good option. |
| 72 |
|
| 73 |
Note also that the performance impact of key/values depend on the |
| 74 |
number of key/values used for the specific object. If an object has |
| 75 |
10 key/value pairs, access is much worse than if it just has one. |
| 76 |
|
| 77 |
However, in all cases, performance is slow because a the key has to |
| 78 |
looked up in the shared string database and then pointer comparisons |
| 79 |
done. |
| 80 |
|
| 81 |
This performance consideration is only something that needs to be if the |
| 82 |
actual key/value is used in the time critical area, and not the object |
| 83 |
as a whole. For example, setting a key/value for a monster isn't |
| 84 |
a problem if that key/value isn't examined during combat (maybe |
| 85 |
something related to conversation). However, storing attack |
| 86 |
related value there would not be a good idea. |
| 87 |
|
| 88 |
2) Use of key values is more memory intensive than just adding fields |
| 89 |
for objects. On a 32 bit system, eg key/value structure is 12 bytes, |
| 90 |
compared to just 4 bytes for a pointer to a string. |
| 91 |
|
| 92 |
One big advantage of the key value is this memory is only used when |
| 93 |
a key is set. So if you do the math, if more than about 1/3 of the |
| 94 |
items would have that key/value pair, actually uses less memory to |
| 95 |
just add a field. |
| 96 |
|
| 97 |
As of this writing (August 2005) there are 30 values used by less then |
| 98 |
10 archetypes. Some number of these should perhaps be moved to |
| 99 |
key/value lists. |
| 100 |
|
| 101 |
3) Key/value fields shouldn't be used if they are related to an existing |
| 102 |
field. For example, if there is a 'foo' field, add you want a |
| 103 |
maxfoo value, it should be done as another field and not as a |
| 104 |
get_ob_key_value(op, "maxfoo") - trying to main that is difficult. |
| 105 |
|
| 106 |
Caveats: |
| 107 |
========= |
| 108 |
|
| 109 |
- key/values don't guard against real fields being used: |
| 110 |
set_ob_key_value(ob, "hp", "acidic") |
| 111 |
will not have the desired effect. |
| 112 |
|
| 113 |
The load/save code is such that it will save the key/value lists |
| 114 |
before actual field values. When loading, the last value is |
| 115 |
used, so in the above example, there may be two lines: |
| 116 |
|
| 117 |
hp acidic |
| 118 |
hp 20 |
| 119 |
|
| 120 |
After load, the value of hp will be 20, since that is the last value |
| 121 |
loaded. |
| 122 |
|
| 123 |
- Using get_ob_key_value(...) with a key for an actual field in the object |
| 124 |
will not work. Eg, get_ob_key_value(op, "hp") will not return the |
| 125 |
hp value of the object - there is no easy way for the functions to |
| 126 |
to access all the fields. |
| 127 |
|
| 128 |
- Thanks to its partial dependence on the loader, Crossedit will correctly |
| 129 |
save and load extra_fields. It can't set or change them, however; there's a |
| 130 |
whitelist in Attr.c::allowed_variables. |
| 131 |
|
| 132 |
- Since all lines are valid, catching errors in arches is now difficult. |
| 133 |
For now, there is a debug statement when we get key/values. When |
| 134 |
key/values get more use, this will be removed. |
| 135 |
|
| 136 |
- Key/values are limited to single lines - you can't do something like |
| 137 |
|
| 138 |
startfoo |
| 139 |
line1 |
| 140 |
line2 |
| 141 |
endfoo |
| 142 |
|
| 143 |
and have it work. However, the line length allowed in the loader is |
| 144 |
quite long. |
| 145 |
|
| 146 |
- There is no function that walks the key/value list for you. If this |
| 147 |
is needed, should write your own. However, sucn functionality really |
| 148 |
shouldn't be needed. |
| 149 |
|
| 150 |
- key names with no value are an indicator to the loader that there is |
| 151 |
no value, and that key should be deleted. |
| 152 |
This is most often used by the saver to denote that the object |
| 153 |
has cleared the key/value. Eg, the archetype has a key/value |
| 154 |
pair, but this object doesn't have a key/value that name. |
| 155 |
|
| 156 |
- Checking two objects against each other can be costly with key/values - |
| 157 |
its basically a O(n^2) operation because have to check of objects 1 |
| 158 |
keys are in object 2 and vice versa. At a cost of a higher load time, |
| 159 |
if the fields were sorted, this could be much quicker, as logic is then |
| 160 |
becomes iterating both lists at the same time, and if any mismatches, |
| 161 |
know it is different right there. However, this is likely to only |
| 162 |
become an issue if the number of key/value pairs for any objects go |
| 163 |
above some certain amount. It's also conceivable since the real |
| 164 |
high cost here is the comparisons, hashing the keys or values and |
| 165 |
storing that hash in the object could be a big gain, but once again, |
| 166 |
depends on how often the values change (as you'd have to recalcuate |
| 167 |
the entire hash) |
