[ViewVC] Annotation of: cvs/deliantra/server/doc/historic/Developers/regions

Included herein is a description of the Region system, as implemented in March 2005.

If by the time you read this, this date is old, then this file may not have been kept
up to date, either that or no relevant changes have occurred, the Changelog should help
you determine which is the case.

*****Contents*****

How to read this file
Overview
Struct values and meaning
Sample region file entry and meaning.
Functions exposed and purpose thereof
player visible changes
Known/suspected bugs.
Future plans

*****How to read this file*****

If you are a mapper and want to create a new region for your maps
read: 
Overview 
Sample region file entry and meaning.

If you want to add new features to regions, read 
Struct values and meaning.
Known/suspected bugs.
Future plans
maybe the rest if you can be bothered.

If you are developing something else and want to interact with region information read:
Functions exposed and purpose thereof
Known/suspected bugs.

If you are merely a curious player who stumbled upon this by accident, read:
player visible changes
and, if you care enough...
Future plans

*****Overview*****
Regions are connected to maps, they allow a set of common properties to be associated with
the maps in the game.
The map struct has had a pointer to a region struct added. This pointer points to the region
that the map is in. 

The map files are altered to have a new field in the header

The line should read
region name

where 'name' is the name of a region defined in the regions file.

The maps are linked to their regions at load time.

Each region is guaranteed only to have 3 values, a name, next and a parent
 exception to this, there is a base region with a NULL parent pointer, this should have *all*
 other fields defined, if a region doesn't have a field defined, then it traverses up the
 inheritance tree, until it finds a definition of the field.
 
Look to the next section to see what the values stored in the region are.
 
Example of this.
region world, this is the base region, with no parent.
region scorn, this has parent world, and longname "Kingdom of scorn"
        it has msg "you are in scorn"
region scornoldcity, this has parent scorn, and no longname, it has msg
        "you are under scorn"

if we call get_region_msg(region) with scornoldcity as the region, it will return
"you are under scorn"
if we call get_region_longname(region) with scornoldcity as the region, it will return
"Kingdom of scorn"

This means that any combination of values can be used scoped appropriately.

Next the values themselves....

*****Struct Values and Meaning*****
This contains a list of the information about the regions and what the fields mean.
*next; 
 we construct a singly-linked list of regions, to check all, you go through one by one
 calling region->next until such time as next is NULL. This is the same as the way most
 other structures in the game work.

*name
 This field is compulsory, it is the name of the region, which is used to connect the maps to the
 regions.

*parent_name
 This is the name of the parent, only used during initialisation
 
*parent
 pointer to the parent region.
 
*longname
 The title of the region, this should be the full, verbose title, with lots of pompousness
 
*counter
 This doesn't really have a fixed meaning, it is just somewhere to count things 
 (at the moment the number of players)
 
*msg
 The description of the region, think guidebook entry.
 Displayed to provide some background flavour.
 
*fallback
 If a map has a misspelling, say scron instead of scorn, then we can't match the name.
 One region should have this set, so that the map can still be assigned a region
 until such time the map creator learns to spell.

*jailmap
 The path to the map that a player who is arrested in this region (or any
 subregion hereof) will go to

*jailx, jaily
 The x and y coordinates on the jailmap the player will go to.

*****Sample Regions file entry*****

region scorn
longname The Kingdom of Scorn
msg
Nestled snugly in a sheltered bay at the west of the Imperial Highway, etc
endmsg
parent world
end

Here we see a relatively high level region, it has a longname, that is the title of the kingdom
It has a description, and a parent.
the region is called scorn, and all maps containing the line 'region scorn' will be in this region

The msg field (description) is contained within the lines msg and endmsg
NB see Known Bugs section about this...

The other line that it could have contained was 
fallback 1
this would've made it the default region for maps with no region set.
However Scorn isn't a sensible choice for this.

Each entry in the regions file is finished with a line saying
end

The regions file stops being parsed when a line saying 
nomore

is encountered.

*****Functions exposed and purpose thereof*****

The following functions are currently accessible, this list is still fluid, expect it to change.

Note, I am describing the functions' specification, what they should be doing, look at the 
source code to see what they /are/ doing....

extern char *get_region_longname(region *r);
        returns the longname that the region should use

extern object *get_jail_exit(object *op);
        returns an object through which the player op should enter to be jailed.

extern char *get_region_msg(region *r);
        returns the description of the region.

extern region *get_region_by_name(char *region_name);
        given a name returns the region with that name, or the fallback if there isn't one.
        Used by the map loader and stuff using get_name_of_region_for_map at the moment.
        
extern int region_is_child_of_region(region *child, region *r);
        1 if the child is a subregion of r
        0 otherwise

extern region *get_region_from_string(char *name);
        tries to guess which region 'name' corresponds to

extern region *get_region_by_map(mapstruct *m);
        takes a map returns the region it is in.

extern char *get_name_of_region_for_map(mapstruct *m);
        takes a map and returns the name of the region it is in.
        
extern void parse_regions();
        used to load the values for the regions at startup
        called by init regions, may end up being called during runtime if region updating is added.
        
extern void init_regions();
        calls parse regions, performs some checks beforehand.
        called by the startup code.
        
extern region *get_region_struct();
        calloc's a new region struct and blanks it for use
        shouldn't really be used externally yet (maybe later though)
        
extern void assign_region_parents();
        called after parse regions, makes the child regions find their parents.
        shouldn't be called externally yet (maybe later though)
        
*****Player visible changes*****

The command mapinfo now returns the region name (not longname, but what is included in the map file)

There is a command whereami that prints the regions name and description.

There is a command whereabouts that shows region names and the number of players there.

who can be given regions as arguments, and only show the players in that region.

*****Known/suspected bugs*****

The region parser is not particularly robust, it dies if the 'endmsg' line is missing, 
or if 'nomore' is missing, or if the 'end' line is missing. These stop the server from
starting, if it starts, it should be fine afterwards.

*****Future plans*****

medium term:

Have the regions file 'compiled' in the same way the archetypes are.

Limit word of recall's range based upon region, add a default savebed to each region, 
and store in the player the savebeds for each region. 

add a 'capabilities' field to the region, defining what the region can do. eg, 
limits_word_of_recall, if set then casting Word of recall takes to the savebed for 
that region, otherwise for the parent region.

Long term:

All sorts of other things, regional leaders, governments, economies, justice systems, 
wars, import restrictions, citizenship, etc, etc

Look on CFMB for some of the things that have been suggested.
Revision:	1.1
Committed:	Thu Sep 7 21:42:57 2006 UTC (17 years, 10 months ago) by pippijn
Branch:	MAIN
CVS Tags:	rel-2_82, rel-2_81, rel-2_80, rel-3_1, rel-3_0, rel-2_6, rel-2_7, rel-2_4, rel-2_5, rel-2_2, rel-2_3, rel-2_0, rel-2_1, rel-2_72, rel-2_73, rel-2_71, rel-2_76, rel-2_77, rel-2_74, rel-2_75, rel-2_54, rel-2_55, rel-2_56, rel-2_79, rel-2_52, rel-2_53, rel-2_32, rel-2_90, rel-2_92, rel-2_93, rel-2_78, rel-2_61, rel-2_43, rel-2_42, rel-2_41, HEAD
Log Message:	Moved documents to doc/historic
#	User	Rev	Content
1	pippijn	1.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.