1 |
root |
1.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) |