terrain.rst 8.26 KB
Newer Older
scrawl's avatar
scrawl committed
1
Terrain Settings
2
################
scrawl's avatar
scrawl committed
3
4
5
6
7
8
9
10

distant terrain
---------------

:Type:		boolean
:Range:		True/False
:Default:	False

11
Controls whether the engine will use paging (chunking) and LOD algorithms to load the terrain of the entire world at all times.
scrawl's avatar
scrawl committed
12
13
14
Otherwise, only the terrain of the surrounding cells is loaded.

.. note::
15
	When enabling distant terrain, make sure the 'viewing distance' in the camera section is set to a larger value so
16
	that you can actually see the additional terrain and objects.
scrawl's avatar
scrawl committed
17

18
19
20
21
To avoid frame drops as the player moves around, nearby terrain pages are always preloaded in the background,
regardless of the preloading settings in the 'Cells' section,
but the preloading of terrain behind a door or a travel destination, for example,
will still be controlled by cell preloading settings.
scrawl's avatar
scrawl committed
22

23
The distant terrain engine is currently considered experimental and may receive updates in the future.
24

bzzt's avatar
bzzt committed
25
26
27
28
29
30
31
32
33
vertex lod mod
--------------

:Type:      integer
:Range:     any
:Default:   0

Controls only the Vertex LOD of the terrain. The amount of terrain chunks and the detail of composite maps is left unchanged.

34
35
Must be changed in increments of 1. Each increment will double (for positive values) or halve (for negative values) the number of vertices rendered.
For example: -2 means 4x reduced detail, +3 means 8x increased detail.
bzzt's avatar
bzzt committed
36

37
38
39
Note this setting will typically not affect near terrain. When set to increase detail, the detail of near terrain can not be increased
because the detail is simply not there in the data files, and when set to reduce detail,
the detail of near terrain will not be reduced because it was already less detailed than the far terrain (in view relative terms) to begin with.
bzzt's avatar
bzzt committed
40

41
42
43
44
45
46
47
lod factor
----------

:Type:		float
:Range:		>0
:Default:	1.0

48
49
Controls the level of detail if distant terrain is enabled.
Higher values increase detail at the cost of performance, lower values reduce detail but increase performance.
50

51
52
53
Note: it also changes how the Quad Tree is split.
Increasing detail with this setting results in the visible terrain being divided into more chunks,
where as reducing detail with this setting would reduce the number of chunks.
bzzt's avatar
bzzt committed
54

55
56
57
Fewer terrain chunks is faster for rendering, but on the other hand a larger proportion of the entire terrain
must be rebuilt when LOD levels change as the camera moves.
This could result in frame drops if moving across the map at high speed.
bzzt's avatar
bzzt committed
58

59
60
61
62
For this reason, it is not recommended to change this setting if you want to change the LOD.
If you want to do that, first try using the 'vertex lod mod' setting to configure the detail of the terrain outlines
to your liking and then use 'composite map resolution' to configure the texture detail to your liking.
But these settings can only be changed in multiples of two, so you may want to adjust 'lod factor' afterwards for even more fine-tuning.
bzzt's avatar
bzzt committed
63

64
65
66
67
68
composite map level
-------------------

:Type:		integer
:Range:		>= -3
Alexei Kotov's avatar
Alexei Kotov committed
69
:Default:	0
70

71
Controls at which minimum size (in 2^value cell units) terrain chunks will start to use a composite map instead of the high-detail textures.
72
73
With value -3 composite maps are used everywhere.

74
75
76
A composite map is a pre-rendered texture that contains all the texture layers combined.
Note that resolution of composite maps is currently always fixed at 'composite map resolution',
regardless of the resolution of the underlying terrain textures.
Alexei Kotov's avatar
Alexei Kotov committed
77
If high resolution texture replacers are used, it is recommended to increase 'composite map resolution' setting value.
78
79
80
81
82
83
84
85

composite map resolution
------------------------

:Type:		integer
:Range:		>0
:Default:	512

86
87
88
Controls the resolution of composite maps. Larger values result in increased detail,
but may take longer to prepare and thus could result in longer loading times and an increased chance of frame drops during play.
As with most other texture resolution settings, it's most efficient to use values that are powers of two.
89

90
91
92
93
94
95
96
97
98
99
100
101
An easy way to observe changes to loading time is to load a save in an interior next to an exterior door
(so it will start preloding terrain) and watch how long it takes for the 'Composite' counter on the F4 panel to fall to zero.

max composite geometry size
---------------------------

:Type:		float
:Range:		>=1.0
:Default:	4.0

Controls the maximum size of simple composite geometry chunk in cell units. With small values there will more draw calls and small textures,
but higher values create more overdraw (not every texture layer is used everywhere).
102

Cédric Mocquillon's avatar
Cédric Mocquillon committed
103
104
105
106
107
108
109
debug chunks
------------

:Type:		boolean
:Range:		True/False
:Default:	False

110
111
112
113
This debug setting allows you to see the borders of each chunks of the world by drawing lines arround them (as with toggleborder). 
If object paging is set to true then this debug setting will allows you to see what objects have been merged in the scene
by making them colored randomly.

Cédric Mocquillon's avatar
Cédric Mocquillon committed
114

115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
object paging
-------------

:Type:		boolean
:Range:		True/False
:Default:	True

Controls whether the engine will use paging (chunking) algorithms to load non-terrain objects
outside of the active cell grid.

Depending on the settings below every object in the game world has a chance
to be batched and be visible in the game world, effectively allowing
the engine to render distant objects with a relatively low performance impact automatically.

In general, an object is more likely to be batched if the number of the object's vertices
and the corresponding memory cost of merging the object is low compared to
the expected number of the draw calls that are going to be optimized out.
This memory cost and the saved number of draw calls shall be called
the "merging cost" and the "merging benefit" in the following documentation.

Objects that are scripted to disappear from the game world
will be handled properly as long as their scripts have a chance to actually disable them.

This setting has no effect if distant terrain is disabled.

object paging active grid
-------------------------
:Type:		boolean
:Range:		True/False
144
:Default:	True
145
146
147
148
149

Controls whether the objects in the active cells use the mentioned paging algorithms.
Active grid paging significantly improves the framerate when your setup is CPU-limited.

.. note::
150
151
152
153
154
	There is a limit of light sources which may affect a rendering shape at the moment.
	If this limit is too small, lighting issues arising due to merged objects
	being considered a single object, and they may disrupt your gameplay experience.
	Consider increasing the 'max lights' setting value in the 'Shaders' section to avoid this issue.
	With the Legacy lighting mode this limit can not be increased (only 8 sources can be used).
155
156
157
158
159
160
161

object paging merge factor
--------------------------
:Type:		float
:Range:		>0
:Default:	250.0

162
163
164
165
166
Affects the likelyhood of more complex objects to get paged.
Higher values improve visual fidelity at the cost of performance and RAM.

Technically this factor is a multiplier of merging benefit and affects the decision
whether displaying the object is cheap enough to justify the sacrifices.
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207

object paging min size
----------------------
:Type:		float
:Range:		>0
:Default:	0.01

Controls how large an object must be to be visible in the scene.
The object's size is divided by its distance to the camera
and the result of the division is compared with this value.
The smaller this value is, the more objects you will see in the scene.

object paging min size merge factor
-----------------------------------
:Type:		float
:Range:		>0
:Default:	0.3

This setting gives inexpensive objects a chance to be rendered from a greater distance
even if the engine would rather discard them according to the previous setting.

It controls the factor that the minimum size is multiplied by
roughly according to the following formula:

	factor = merge cost * min size cost multiplier / merge benefit
	
	factor = factor + (1 - factor) * min size merge factor

Since the larger this factor is, the smaller chance a large object has to be rendered,
decreasing this value makes more objects visible in the scene
without impacting the performance as dramatically as the minimum size setting.

object paging min size cost multiplier
--------------------------------------
:Type:		float
:Range:		>0
:Default:	25.0

This setting adjusts the calculated cost of merging an object used in the mentioned functionality.
The larger this value is, the less expensive objects can be before they are discarded.
See the formula above to figure out the math.