1 |
Included herein is a description of the Region system, as implemented in March 2005. |
2 |
|
3 |
If by the time you read this, this date is old, then this file may not have been kept |
4 |
up to date, either that or no relevant changes have occurred, the Changelog should help |
5 |
you determine which is the case. |
6 |
|
7 |
*****Contents***** |
8 |
|
9 |
How to read this file |
10 |
Overview |
11 |
Struct values and meaning |
12 |
Sample region file entry and meaning. |
13 |
Functions exposed and purpose thereof |
14 |
player visible changes |
15 |
Known/suspected bugs. |
16 |
Future plans |
17 |
|
18 |
*****How to read this file***** |
19 |
|
20 |
If you are a mapper and want to create a new region for your maps |
21 |
read: |
22 |
Overview |
23 |
Sample region file entry and meaning. |
24 |
|
25 |
If you want to add new features to regions, read |
26 |
Struct values and meaning. |
27 |
Known/suspected bugs. |
28 |
Future plans |
29 |
maybe the rest if you can be bothered. |
30 |
|
31 |
If you are developing something else and want to interact with region information read: |
32 |
Functions exposed and purpose thereof |
33 |
Known/suspected bugs. |
34 |
|
35 |
If you are merely a curious player who stumbled upon this by accident, read: |
36 |
player visible changes |
37 |
and, if you care enough... |
38 |
Future plans |
39 |
|
40 |
*****Overview***** |
41 |
Regions are connected to maps, they allow a set of common properties to be associated with |
42 |
the maps in the game. |
43 |
The map struct has had a pointer to a region struct added. This pointer points to the region |
44 |
that the map is in. |
45 |
|
46 |
The map files are altered to have a new field in the header |
47 |
|
48 |
The line should read |
49 |
region name |
50 |
|
51 |
where 'name' is the name of a region defined in the regions file. |
52 |
|
53 |
The maps are linked to their regions at load time. |
54 |
|
55 |
Each region is guaranteed only to have 3 values, a name, next and a parent |
56 |
exception to this, there is a base region with a NULL parent pointer, this should have *all* |
57 |
other fields defined, if a region doesn't have a field defined, then it traverses up the |
58 |
inheritance tree, until it finds a definition of the field. |
59 |
|
60 |
Look to the next section to see what the values stored in the region are. |
61 |
|
62 |
Example of this. |
63 |
region world, this is the base region, with no parent. |
64 |
region scorn, this has parent world, and longname "Kingdom of scorn" |
65 |
it has msg "you are in scorn" |
66 |
region scornoldcity, this has parent scorn, and no longname, it has msg |
67 |
"you are under scorn" |
68 |
|
69 |
if we call get_region_msg(region) with scornoldcity as the region, it will return |
70 |
"you are under scorn" |
71 |
if we call get_region_longname(region) with scornoldcity as the region, it will return |
72 |
"Kingdom of scorn" |
73 |
|
74 |
This means that any combination of values can be used scoped appropriately. |
75 |
|
76 |
Next the values themselves.... |
77 |
|
78 |
*****Struct Values and Meaning***** |
79 |
This contains a list of the information about the regions and what the fields mean. |
80 |
*next; |
81 |
we construct a singly-linked list of regions, to check all, you go through one by one |
82 |
calling region->next until such time as next is NULL. This is the same as the way most |
83 |
other structures in the game work. |
84 |
|
85 |
*name |
86 |
This field is compulsory, it is the name of the region, which is used to connect the maps to the |
87 |
regions. |
88 |
|
89 |
*parent_name |
90 |
This is the name of the parent, only used during initialisation |
91 |
|
92 |
*parent |
93 |
pointer to the parent region. |
94 |
|
95 |
*longname |
96 |
The title of the region, this should be the full, verbose title, with lots of pompousness |
97 |
|
98 |
*counter |
99 |
This doesn't really have a fixed meaning, it is just somewhere to count things |
100 |
(at the moment the number of players) |
101 |
|
102 |
*msg |
103 |
The description of the region, think guidebook entry. |
104 |
Displayed to provide some background flavour. |
105 |
|
106 |
*fallback |
107 |
If a map has a misspelling, say scron instead of scorn, then we can't match the name. |
108 |
One region should have this set, so that the map can still be assigned a region |
109 |
until such time the map creator learns to spell. |
110 |
|
111 |
*jailmap |
112 |
The path to the map that a player who is arrested in this region (or any |
113 |
subregion hereof) will go to |
114 |
|
115 |
*jailx, jaily |
116 |
The x and y coordinates on the jailmap the player will go to. |
117 |
|
118 |
*****Sample Regions file entry***** |
119 |
|
120 |
region scorn |
121 |
longname The Kingdom of Scorn |
122 |
msg |
123 |
Nestled snugly in a sheltered bay at the west of the Imperial Highway, etc |
124 |
endmsg |
125 |
parent world |
126 |
end |
127 |
|
128 |
Here we see a relatively high level region, it has a longname, that is the title of the kingdom |
129 |
It has a description, and a parent. |
130 |
the region is called scorn, and all maps containing the line 'region scorn' will be in this region |
131 |
|
132 |
The msg field (description) is contained within the lines msg and endmsg |
133 |
NB see Known Bugs section about this... |
134 |
|
135 |
The other line that it could have contained was |
136 |
fallback 1 |
137 |
this would've made it the default region for maps with no region set. |
138 |
However Scorn isn't a sensible choice for this. |
139 |
|
140 |
Each entry in the regions file is finished with a line saying |
141 |
end |
142 |
|
143 |
The regions file stops being parsed when a line saying |
144 |
nomore |
145 |
|
146 |
is encountered. |
147 |
|
148 |
*****Functions exposed and purpose thereof***** |
149 |
|
150 |
The following functions are currently accessible, this list is still fluid, expect it to change. |
151 |
|
152 |
Note, I am describing the functions' specification, what they should be doing, look at the |
153 |
source code to see what they /are/ doing.... |
154 |
|
155 |
extern char *get_region_longname(region *r); |
156 |
returns the longname that the region should use |
157 |
|
158 |
extern object *get_jail_exit(object *op); |
159 |
returns an object through which the player op should enter to be jailed. |
160 |
|
161 |
extern char *get_region_msg(region *r); |
162 |
returns the description of the region. |
163 |
|
164 |
extern region *get_region_by_name(char *region_name); |
165 |
given a name returns the region with that name, or the fallback if there isn't one. |
166 |
Used by the map loader and stuff using get_name_of_region_for_map at the moment. |
167 |
|
168 |
extern int region_is_child_of_region(region *child, region *r); |
169 |
1 if the child is a subregion of r |
170 |
0 otherwise |
171 |
|
172 |
extern region *get_region_from_string(char *name); |
173 |
tries to guess which region 'name' corresponds to |
174 |
|
175 |
extern region *get_region_by_map(mapstruct *m); |
176 |
takes a map returns the region it is in. |
177 |
|
178 |
extern char *get_name_of_region_for_map(mapstruct *m); |
179 |
takes a map and returns the name of the region it is in. |
180 |
|
181 |
extern void parse_regions(); |
182 |
used to load the values for the regions at startup |
183 |
called by init regions, may end up being called during runtime if region updating is added. |
184 |
|
185 |
extern void init_regions(); |
186 |
calls parse regions, performs some checks beforehand. |
187 |
called by the startup code. |
188 |
|
189 |
extern region *get_region_struct(); |
190 |
calloc's a new region struct and blanks it for use |
191 |
shouldn't really be used externally yet (maybe later though) |
192 |
|
193 |
extern void assign_region_parents(); |
194 |
called after parse regions, makes the child regions find their parents. |
195 |
shouldn't be called externally yet (maybe later though) |
196 |
|
197 |
*****Player visible changes***** |
198 |
|
199 |
The command mapinfo now returns the region name (not longname, but what is included in the map file) |
200 |
|
201 |
There is a command whereami that prints the regions name and description. |
202 |
|
203 |
There is a command whereabouts that shows region names and the number of players there. |
204 |
|
205 |
who can be given regions as arguments, and only show the players in that region. |
206 |
|
207 |
*****Known/suspected bugs***** |
208 |
|
209 |
The region parser is not particularly robust, it dies if the 'endmsg' line is missing, |
210 |
or if 'nomore' is missing, or if the 'end' line is missing. These stop the server from |
211 |
starting, if it starts, it should be fine afterwards. |
212 |
|
213 |
*****Future plans***** |
214 |
|
215 |
medium term: |
216 |
|
217 |
Have the regions file 'compiled' in the same way the archetypes are. |
218 |
|
219 |
Limit word of recall's range based upon region, add a default savebed to each region, |
220 |
and store in the player the savebeds for each region. |
221 |
|
222 |
add a 'capabilities' field to the region, defining what the region can do. eg, |
223 |
limits_word_of_recall, if set then casting Word of recall takes to the savebed for |
224 |
that region, otherwise for the parent region. |
225 |
|
226 |
Long term: |
227 |
|
228 |
All sorts of other things, regional leaders, governments, economies, justice systems, |
229 |
wars, import restrictions, citizenship, etc, etc |
230 |
|
231 |
Look on CFMB for some of the things that have been suggested. |