[ViewVC] Annotation of: cvs/deliantra/server/doc/historic/Developers/map-technical

TECHNICAL INFORMATION ABOUT MAPS:

This documented is intended to convey technical information on how
crossfire deals with the map objects and objects placed on the maps.  For
the most part, I only intend document how the new code works, and not
go too much into history on the older methods.  A lot of the map
code was re-written in early July 2001, which changed how many things are
dealt with.

Mark Wedel
July 7, 2001

------------------------------------------------------------------------------
THE MAP HEADER:

The map header is the section at the start of the map file that
describes the maps characteristics.  The values are described below.

The map variables now make some sense, and are only stored in the
map structure itself.  I still include the old value (the 'was') so
if you are looking at old maps, you know what they mean.  Generally
speaking, the values in the map files themselves match the same element
name in the map structure.

'width','height', was 'x','y': Size of the map.

'enter_x', 'enter_y', was ('hp','sp') = (x,y) of the destination on the
        new map.  These are only used if the exit does not have a specific
        location set.

'reset_timeout', was 'weight': stores the number of seconds that need
   to elapse before this map will be reset.  Ie, if 1800, it means this
   map expires after 30 minutes.  This value is not modified once loaded -
   instead reset_time is used to track this.  The value 0 means to use
   a default timeout (MAP_DEFAULTRESET).

'swap_time', was 'value': This controls how many ticks must elapse
    after the map has not been used before it gets swapped out.
    swapping out is different than reset, as a swapped out map will
    get loaded back into memory if someone re-visits it before it is due to
    reset.

'difficulty', was 'level' stores the map difficulty.  If not set to 
    anything, the server code will try to come up with some difficulty value.

'fixed_resettime', was 'stand_still': If nonzero, the map reset time will not
        be updated when someone enters/exits the map.  Thus, once the map has
        been loaded, it will reset in 'reset time' no matter what access
        happen.  This is useful for shops and towns, which are constantly
        accessed, but should be reset periodically.

'darkness', was 'invisible'.  Light/darnkess of map (overall).  If 0,
        all of map is fully bright.  

'unique' - if set, this entire map is unique.  Exactly unique to what
        will depend on how it was created (it could be a per player
        unique map, or maybe a common map that is just permanent for
        all the players.

'nosmooth' - if set, no faces in this map will be smoothed.

'outdoor' - if set, this is a hint that this is an outdoor map.
        If this is not set, weather and dawn/dusk will not occur on this
        map.  It is highly advised that this be set appropriately.

tile_path_<x> - Used with map tiling.  <x> is a number, 1 is north,
        2 is east, 3 south, 4 west.  This determines what map is tiled
        in that direction.  See the section below for more information about
        map tiling.

'shopitems', 'shopgreed', 'shoprace', 'shopmin', 'shopmax' - the type of thing 
        the shop trades in, see doc/Developers/shops for more details

'temp'  - The base temperature in farenhiet for this map.  The temperature
        is modified by the season and weather conditions.  In a map without
        weather effects, this temperature will be used as the static
        temperature for the entire map.  This can be useful to make an ice
        cave actually cold.

'pressure' - This should really never be set on a map.  The pressure in
        millibars.

'humid' - Again, should rarely be set on a map.  The humidity in percent.

'windspeed' - Rarely set.  The windspeed in kph/h.

'winddir' - Rarely set.  Direction of wind, 1-8, 1 is north, clockwise.

'sky' - The sky conditions for this map.  See weather.h.  Don't set this
        unless you really know what you are doing.

------------------------------------------------------------------------------
THE MAP OBJECTS:

The objects within the map are saved in standard 'object save' form
(same as is used for the players objects).  Other files document the
actual meaning, but the general form is:

arch <some name>
x <some value>
y <some value>
<other object specific values>
end

Note that x and y are in fact optional.  If not present, the values
default to zero.

Multipart objects:

Multipart objects pose a tricky problem, in that they have to
appear together in the map file - this makes proper handling of
layers hard to deal with.

In old map code, all the single spaces objects were saved, and
then all the multi part objects were saved.  This effectively
means that the multi part objects always ended up on top.  The multipart
objects were saved with all their parts.  For example:

slaying shops/magicshop
hp 14
sp 14
x 1
y 13
end
More
arch store_magic_2
name Magic Shop
slaying shops/magicshop
hp 14
sp 14
x 2
y 13
end
<snip - there are really two more parts>

This method does not work very well with the map tiling however (how do you
reasonably deal with a monster that may be straddling the two maps?)  Current
code now only saves the head of the object.  When the map is loaded, the
objects on the map are examined to see what objects need to have more objects
added on.  Additional parts linked in are put just above floor level when
linked in, so things like shops won't hide items that someone drops on them.
For monsters, this linking shouldn't be a problem - once they start moving,
they will get relinked as normal (on top).

The effect of saving only the head does have the effect of not being
able to customize the non head parts of the object.  This generally should not
be a problem (in the case of shops/building, the exit code now knows to look
only at the head for valid information).  The case where this may not work as
well as expected is for buildings where setting the no_pass to non
archetype defaults will get lost.

------------------------------------------------------------------------------
Map Tiling:

Map tiling is a feature that lets multiple maps be connected, effectively
forming a much larger single map.  This is most useful for the outdoor
world maps, where it is not practical to have on massive map, but
the old style tiling method (copying areas of the adjoining map to the next
one) are not very efficient.

The transfer of objects from one map to another tiled map are automatic.
Presuming the proper macros are used (out_of_map, get_map_..), minimal extra
work is necessary for everything to work right 

Notes:
Tiled maps must be the same width/height along the side they are tiled with.
If map1 has a height of 15, and you want to tile along one of the sides, the
map(s) it gets tiled with along that side should also be 15.  Given
the following diagram (not to scale):


+---x1----+----x2---+
|         |         |
| map1    |  map2   y2
y1        |         |
|         |         |
+---------+---------+

x1 is the width of map1, y1 is its height.
x2 is the width of map2, y2 is its height.
map1 will tile map2 as indicated in the above diagram.

 Given that, the following must be true:
y1 must equal y2
x1 must be greater than 12
x2 must be greater than 12
x1 and x2 do not need to be equal

The value is derived as being half the maximum viewable area.  The reason
for this is that the line of sight code (and likely some other code) will only
look one map away from a source coordinate.  While the values can be less
than 12, they should be at least 12 if the map tiles with another one in
that direction.  If the map is an 'end' map (ie, no further tiling in a 
specific direction), then having a value less than 12 should work just fine.

Note that tiles maps do not have to be symmetric - several maps
could tile to a common map.  That common map can only tile back to one of
those.  And example of where this might be used is for a courtyard of
a multi floor house - that courtyard should be visible (and be the same)
from all the levels, but you can only go from the courtyard to first floor
rooms off the courtyard.  This may not be ideal (ie, if flying, you should
be able to go to any floor), but this tiling for elevation is just an
example that can be used. 
Revision:	1.1
Committed:	Thu Sep 7 21:42:56 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	TECHNICAL INFORMATION ABOUT MAPS:
2
3			This documented is intended to convey technical information on how
4			crossfire deals with the map objects and objects placed on the maps. For
5			the most part, I only intend document how the new code works, and not
6			go too much into history on the older methods. A lot of the map
7			code was re-written in early July 2001, which changed how many things are
8			dealt with.
9
10			Mark Wedel
11			July 7, 2001
12
13			------------------------------------------------------------------------------
14			THE MAP HEADER:
15
16			The map header is the section at the start of the map file that
17			describes the maps characteristics. The values are described below.
18
19			The map variables now make some sense, and are only stored in the
20			map structure itself. I still include the old value (the 'was') so
21			if you are looking at old maps, you know what they mean. Generally
22			speaking, the values in the map files themselves match the same element
23			name in the map structure.
24
25			'width','height', was 'x','y': Size of the map.
26
27			'enter_x', 'enter_y', was ('hp','sp') = (x,y) of the destination on the
28			new map. These are only used if the exit does not have a specific
29			location set.
30
31			'reset_timeout', was 'weight': stores the number of seconds that need
32			to elapse before this map will be reset. Ie, if 1800, it means this
33			map expires after 30 minutes. This value is not modified once loaded -
34			instead reset_time is used to track this. The value 0 means to use
35			a default timeout (MAP_DEFAULTRESET).
36
37			'swap_time', was 'value': This controls how many ticks must elapse
38			after the map has not been used before it gets swapped out.
39			swapping out is different than reset, as a swapped out map will
40			get loaded back into memory if someone re-visits it before it is due to
41			reset.
42
43			'difficulty', was 'level' stores the map difficulty. If not set to
44			anything, the server code will try to come up with some difficulty value.
45
46			'fixed_resettime', was 'stand_still': If nonzero, the map reset time will not
47			be updated when someone enters/exits the map. Thus, once the map has
48			been loaded, it will reset in 'reset time' no matter what access
49			happen. This is useful for shops and towns, which are constantly
50			accessed, but should be reset periodically.
51
52			'darkness', was 'invisible'. Light/darnkess of map (overall). If 0,
53			all of map is fully bright.
54
55			'unique' - if set, this entire map is unique. Exactly unique to what
56			will depend on how it was created (it could be a per player
57			unique map, or maybe a common map that is just permanent for
58			all the players.
59
60			'nosmooth' - if set, no faces in this map will be smoothed.
61
62			'outdoor' - if set, this is a hint that this is an outdoor map.
63			If this is not set, weather and dawn/dusk will not occur on this
64			map. It is highly advised that this be set appropriately.
65
66			tile_path_<x> - Used with map tiling. <x> is a number, 1 is north,
67			2 is east, 3 south, 4 west. This determines what map is tiled
68			in that direction. See the section below for more information about
69			map tiling.
70
71			'shopitems', 'shopgreed', 'shoprace', 'shopmin', 'shopmax' - the type of thing
72			the shop trades in, see doc/Developers/shops for more details
73
74			'temp' - The base temperature in farenhiet for this map. The temperature
75			is modified by the season and weather conditions. In a map without
76			weather effects, this temperature will be used as the static
77			temperature for the entire map. This can be useful to make an ice
78			cave actually cold.
79
80			'pressure' - This should really never be set on a map. The pressure in
81			millibars.
82
83			'humid' - Again, should rarely be set on a map. The humidity in percent.
84
85			'windspeed' - Rarely set. The windspeed in kph/h.
86
87			'winddir' - Rarely set. Direction of wind, 1-8, 1 is north, clockwise.
88
89			'sky' - The sky conditions for this map. See weather.h. Don't set this
90			unless you really know what you are doing.
91
92			------------------------------------------------------------------------------
93			THE MAP OBJECTS:
94
95			The objects within the map are saved in standard 'object save' form
96			(same as is used for the players objects). Other files document the
97			actual meaning, but the general form is:
98
99			arch <some name>
100			x <some value>
101			y <some value>
102			<other object specific values>
103			end
104
105			Note that x and y are in fact optional. If not present, the values
106			default to zero.
107
108			Multipart objects:
109
110			Multipart objects pose a tricky problem, in that they have to
111			appear together in the map file - this makes proper handling of
112			layers hard to deal with.
113
114			In old map code, all the single spaces objects were saved, and
115			then all the multi part objects were saved. This effectively
116			means that the multi part objects always ended up on top. The multipart
117			objects were saved with all their parts. For example:
118
119			slaying shops/magicshop
120			hp 14
121			sp 14
122			x 1
123			y 13
124			end
125			More
126			arch store_magic_2
127			name Magic Shop
128			slaying shops/magicshop
129			hp 14
130			sp 14
131			x 2
132			y 13
133			end
134			<snip - there are really two more parts>
135
136			This method does not work very well with the map tiling however (how do you
137			reasonably deal with a monster that may be straddling the two maps?) Current
138			code now only saves the head of the object. When the map is loaded, the
139			objects on the map are examined to see what objects need to have more objects
140			added on. Additional parts linked in are put just above floor level when
141			linked in, so things like shops won't hide items that someone drops on them.
142			For monsters, this linking shouldn't be a problem - once they start moving,
143			they will get relinked as normal (on top).
144
145			The effect of saving only the head does have the effect of not being
146			able to customize the non head parts of the object. This generally should not
147			be a problem (in the case of shops/building, the exit code now knows to look
148			only at the head for valid information). The case where this may not work as
149			well as expected is for buildings where setting the no_pass to non
150			archetype defaults will get lost.
151
152			------------------------------------------------------------------------------
153			Map Tiling:
154
155			Map tiling is a feature that lets multiple maps be connected, effectively
156			forming a much larger single map. This is most useful for the outdoor
157			world maps, where it is not practical to have on massive map, but
158			the old style tiling method (copying areas of the adjoining map to the next
159			one) are not very efficient.
160
161			The transfer of objects from one map to another tiled map are automatic.
162			Presuming the proper macros are used (out_of_map, get_map_..), minimal extra
163			work is necessary for everything to work right
164
165			Notes:
166			Tiled maps must be the same width/height along the side they are tiled with.
167			If map1 has a height of 15, and you want to tile along one of the sides, the
168			map(s) it gets tiled with along that side should also be 15. Given
169			the following diagram (not to scale):
170
171
172			+---x1----+----x2---+
173			\| \| \|
174			\| map1 \| map2 y2
175			y1 \| \|
176			\| \| \|
177			+---------+---------+
178
179			x1 is the width of map1, y1 is its height.
180			x2 is the width of map2, y2 is its height.
181			map1 will tile map2 as indicated in the above diagram.
182
183			Given that, the following must be true:
184			y1 must equal y2
185			x1 must be greater than 12
186			x2 must be greater than 12
187			x1 and x2 do not need to be equal
188
189			The value is derived as being half the maximum viewable area. The reason
190			for this is that the line of sight code (and likely some other code) will only
191			look one map away from a source coordinate. While the values can be less
192			than 12, they should be at least 12 if the map tiles with another one in
193			that direction. If the map is an 'end' map (ie, no further tiling in a
194			specific direction), then having a value less than 12 should work just fine.
195
196			Note that tiles maps do not have to be symmetric - several maps
197			could tile to a common map. That common map can only tile back to one of
198			those. And example of where this might be used is for a courtyard of
199			a multi floor house - that courtyard should be visible (and be the same)
200			from all the levels, but you can only go from the courtyard to first floor
201			rooms off the courtyard. This may not be ideal (ie, if flying, you should
202			be able to go to any floor), but this tiling for elevation is just an
203			example that can be used.