188 lines
16 KiB
HTML
188 lines
16 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
<link rel="icon" href="./favicon.png">
|
||
<title>Manual for the Luanti Biome Point Visualizer</title>
|
||
<link rel="stylesheet" href="./dark_style.css">
|
||
</head>
|
||
|
||
<body>
|
||
<h1>LiBPoV Manual</h1>
|
||
<div id="mainContentContainer" class="contentContainer">
|
||
<p><a href="./index.html">Back to the main program</a></p>
|
||
<h2>What is this?</h2>
|
||
<p>LiBPoV is the <u>L</u>uant<u>i</u> <u>B</u>iome <u>Po</u>int <u>V</u>isualizer, a tool for people who develop games and mods for <a href="https://luanti.org">Luanti</a>. It allows them to <b>visualize the heat and humidity points</b> of biomes. It runs in your <b>web browser</b> using JavaScript.</p>
|
||
|
||
<h2>Features</h2>
|
||
<ul>
|
||
<li><b>Add</b> the heat and humidity points of biomes</li>
|
||
<li><b>Visualize</b> the biomes on a <a title="Wikipedia: Voronoi diagram" href="https://en.wikipedia.org/wiki/Voronoi_diagram">Voronoi diagram</a></li>
|
||
<li>Show biomes for given <b>world coordinates</b> only</li>
|
||
<li>Modify the <b>noise parameters</b> of the heat and humidity Perlin noises used by the mapgen</li>
|
||
<li>Visualize the biomes of the <b>v6 mapgen</b> in a special diagram</li>
|
||
<li><b>Export</b> to Lua, LiBPoV JSON and <i>Amidst for Minetest</i> biome profiles</li>
|
||
<li><b>Import</b> from LiBPoV JSON and <i>Amidst for Minetest</i> biome profiles</li>
|
||
</ul>
|
||
|
||
<h2>Quick reminder how biomes work</h2>
|
||
<p>When Luanti generates the world, each (X, Z) coordinate is assigned a <b>heat</b> and <b>humidity</b> value (“heat” is also sometimes called “temperature”). Also, each biome is assigned a heat and humidity value as well. Heat and humidity act as coordinates on a <b>2-dimensional plane</b>. For any world position, the biome that has a heat and humidity value that are closest to the heat and humidity will be used for that position. This happens for every position.</p>
|
||
|
||
<p>Luanti also may apply “blending” at the biome borders for a smoother transition, but this is ignored in LiBPoV.</p>
|
||
|
||
<p>The challenge for the developer is to figure out good heat and humidity points of custom biomes to make sure they are well-balanced. This is where this program will help you.</p>
|
||
|
||
<p>The v6 map generator is an exception: Here, biomes don’t have heat and humidity points. Instead, Luanti instead just checks if the world position’s heat and humidity lies between some (mostly) hardcoded values and then decides which of the hardcoded biomes to use.</p>
|
||
|
||
<p>Please refer to the official Luanti Lua API documentation for a more in-depth explanation.</p>
|
||
|
||
<h2>Interpreting the diagram</h2>
|
||
<p>On top of the page, you see the biome diagram. The horizontal axis represents heat and the vertical axis represents humidity. The visible diagram area represents all mathematically possible values. Note that the further you go from the center, the less likely they will become, with the area close to the border being extremely unlikely.</p>
|
||
|
||
<p>In “<b>biome points</b>” mode, the default value range of heat and humidity is from −37.5 to 137.5, with 50 as the midpoint. As a rule of thumb, most values will be somewhere between 0 and 100 by default.</p>
|
||
|
||
<p>In “<b>v6 biomes</b>” mode, the default value range is smaller. The value range may be changed by the noise parameters (which will be explained later).</p>
|
||
|
||
<p>Red dots represent the <b>biome points</b> (only in “biome points” mode), and they are labelled by their name. Dark green border lines represent the boundaries of Voronoi cells and the large colored areas represent the biomes themselves.</p>
|
||
|
||
<p>By default, a <b>grid</b> is displayed. A grid line is shown for every 10 units in “biome points” mode and 0.1 units in “v6 biomes” mode. Note: The grid lines may disappear if there would be too many of them.</p>
|
||
|
||
<p>Below the diagram, a couple of <b>status information</b> is shown: The current world coordinates (this is for biomes that <i>could</i> appear at these coordinates, applying min./max. X/Y/Z biome limits), the heat and humidity range of the current diagram and your cursor position (if it is on the diagram).</p>
|
||
|
||
<h3>An example</h3>
|
||
<p>Let’s say in the “biome points” mode there are 2 biomes at the (heat, humidity) coordinates (10, 10) and (90, 90). This will divide the diagram in 2 sections. Each of these sections is a Voronoi cell, or the set of all (heat, humidity) value pairs of that biome.</p>
|
||
|
||
<p>Let’s look what happens at position heat=0, humidity=0. If you read the diagram, you will see it belongs to the first biome. This means that whenever a world position has a heat of 0 and humidity of 0, that biome will be used. Now at heat=70, humidity=50, we can read it belongs to the second biome. And this is how you can understand this diagram.</p>
|
||
|
||
<h2>Usage</h2>
|
||
<p>This section explains how you can interact with the various parts of the program.</p>
|
||
|
||
<p>The interactive sections have a header with an arrow symbol at the beginning. Click on this arrow to collapse or extend a section.</p>
|
||
|
||
<h3>Biome modes</h3>
|
||
<p>Above the diagram, there are two buttons: “Biome points” and “v6 biomes”. These are the <b>biome modes</b>. Click on one of these buttons to change the biome mode. This affects the entire program.</p>
|
||
|
||
<p>In “<b>biome points</b>” mode, you can add, see and visualize heat and humidity points as well as the biome area on a diagram. This is the default mode. Biome points are used in all Luanti map generators except v6.</p>
|
||
|
||
<p>The “<b>v6 biomes</b>” mode displays the biomes of the v6 mapgen. The v6 biomes work completely differently and are hardcoded because this mapgen is very old. There are no biome points and your options to configure them are limited to a few settings only. You can’t add custom biomes here.</p>
|
||
|
||
<h3>Diagram</h3>
|
||
<p>Hover with the mouse cursor over the diagram to see the heat and humidity coordinates at this position.</p>
|
||
|
||
<p>When you hover the diagram, a small <b>grabbing widget</b> will appear in the bottom right corner. You can use this to <b>resize</b> the whole diagram. Hold down Shift while resizing to preserve the aspect ratio.</p>
|
||
|
||
<p>In “Biome points” mode, you can click on a point to <b>select</b> it, click on it again and hold down the mouse button to <b>drag</b> it. You can add a new point by <b>double-clicking</b> on the diagram, provided a click wouldn’t select an already selected point.</p>
|
||
|
||
<h3>Biome configuration</h3>
|
||
<p>You can configure the biomes here. This section differs on the selected biome mode.</p>
|
||
|
||
<h4>“Biome points” mode</h4>
|
||
<p>Here you can see a list of all currently active biomes. Each biome has a name of your choice. The program always starts with a default biome at (50, 50). Select a biome in the list so you can edit it.</p>
|
||
|
||
<p>The “Add” button adds a new biome with a random heat and humidity. “Remove” removes the currently selected biome.</p>
|
||
|
||
<p>Once you’ve selected a biome in the list, the fields in “Selected biome” will activate. Here, you can <b>edit</b> the selected biome’s heat and humidity point (corresponds to <code>heat_point</code> and <code>humidity_point</code> in the Lua API). You can also edit the <b>minimum and maximum X/Y/Z positions</b> this biome will be generated in (corresponds to <code>min_pos</code>/<code>max_pos</code> in the Lua biome definition).</p>
|
||
|
||
<p>Each biome has a <b>name</b> and a <b>color</b> which can be changed, too. These are only used for display purposes and don’t affect the calculations.</p>
|
||
|
||
<p>Changing a value in any of these fields will immediately take effect.</p>
|
||
|
||
<h4>“v6 biomes” mode</h4>
|
||
<p>In this mode you can configure a few settings of the v6 biomes. The “Flags” sections changes the v6-specific mapgen flags (on/off settings) and corresponds to the Luanti setting <code>mgv6_spflags</code>. The Desert noise threshold corresponds to <code>mgv6_freq_desert</code>.</p>
|
||
|
||
<p>These settings can be changed:</p>
|
||
|
||
<ul>
|
||
<li><b>snowbiomes</b>: Activates the 5-biome system which introduces tundra and taiga. This will also force-enable jungles.</li>
|
||
<li><b>jungles</b>: Activates the jungle biome. This is only available if snowbiomes are disabled. Otherwise, jungles are force-enabled.</li>
|
||
<li><b>Desert noise threshold</b> (<code>mgv6_freq_desert</code>): Deserts will generate if the heat is above this value. This is only available if snowbiomes is off. If snowbiomes is on, the desert heat is fixed.</li>
|
||
</ul>
|
||
|
||
<p>You can’t add any custom biomes.</p>
|
||
|
||
<h3>Diagram view settings</h3>
|
||
<p>These settings only affect the <b>visual representation</b> and not the data. The checkboxes can be used to hide several things in the diagram, like the grid.</p>
|
||
|
||
<p>The world position setting changes at which world coordinates (XYZ) the diagram “looks” at. The diagram will only show biomes that would generate at these coordinates, applying the biome’s Min./Max. X/Y/Z settings. In “v6 biomes” mode, the world position has no effect.</p>
|
||
|
||
<p>Note: If you hide the points, you can no longer select them in the diagram. You can still select them in the biome list, however.</p>
|
||
|
||
<h3>Noise parameters</h3>
|
||
<p>This is fairly advanced and most games don’t modify this. You can experiment with this if you want to see what happens if you use non-default heat and/or humidity Perlin noise parameters. The parenthesis if the Heat and Humidity sections show the name of the setting the noise parameters correspond to. The noise setting names depend on the current biome mode. The explanation of Perlin noises is out of scope for this document. See the Luanti Lua API documentation.</p>
|
||
|
||
<p>Changing the noise parameters has an <b>effect on the possible value range</b> for heat and humidity which has an effect on the probability of all biomes.</p>
|
||
|
||
<p>If your game or mod does not modify these noise parameters, you can ignore this section and leave it at default. Click on “<b>Reset noise parameters</b>” to reset them to the default if you accidentally changed them.</p>
|
||
|
||
<p>This section works mostly the same in both biome modes. But in “v6 biomes” mode, the humidity can never exceed 0.0 and 1.0. This is why you might not immediately see a change when you change the humidity noise in this mode.</p>
|
||
|
||
<h3>Import</h3>
|
||
<p>This is only available in “Biome points” mode.</p>
|
||
|
||
<p>This allows you to <b>import biomes</b> from text. There are two formats that can be imported:</p>
|
||
|
||
<p><b>LiBPoV JSON</b> is LiBPoV’s native format that LiBPoV creates when exporting.</p>
|
||
|
||
<p>The <b>Amidst for Minetest</b> option imports from a biome profile from <a href="https://github.com/Treer/Amidst-for-Minetest">Amidst for Minetest</a>. Biome profile files usually have the ending “<code>.mt</code>”.</p>
|
||
|
||
<p>To use the import functionality, just paste the text in the text box and press the corresponding import button. <b>This will replace all biomes.</b> A message below the text box will tell you if the import has succeeded or failed. If the import has failed, nothing will happen.</p>
|
||
|
||
<p>To import biomes from an existing Luanti game, use the Luanti mod <code><a href="https://codeberg.org/Wuzzy/libpov_biome_exporter" title="Luanti mod: libpov_biome_exporter">libpov_biome_exporter</a></code>. This prints the biomes of an existing Luanti game in LiBPoV JSON format to the console, from which you can copy it to the import text box. Refer to the README file of that mod for details.</p>
|
||
|
||
<h3>Export</h3>
|
||
<p>This is only available in “Biome points” mode.</p>
|
||
|
||
<p>This allows you to export the current biomes into text. You can choose to export them in one of various formats. Only biome information is included, not the noise parameters.</p>
|
||
|
||
<p>The <b>LiBPoV JSON</b> option exports the biomes in LiBPoV’s native format. It contains all the biome information that LiBPoV uses, including the biome color in the diagram, but not the noise parameters. You may want to copy this into a text file for later use.</p>
|
||
|
||
<p>The <b>Lua</b> export gives you a very basic Lua code that can be pasted into a Luanti mod. The code is very basic and does not include the “landscape materials”, like what the surface is made of (dirt, stone, sand, etc.). Biome coordinate limits (<code>y_min</code>/<code>y_max</code> or <code>min_pos</code>/<code>max_pos</code>) are added to the export only if they differ from the default values -31000 and 31000.</p>
|
||
|
||
<p>The <b>Amidst for Minetest</b> export gives you a biome profile you can use for <a href="https://github.com/Treer/Amidst-for-Minetest">Amidst for Minetest</a>. The export does not include biome coordinate limits on the X and Z axis because those aren’t supported by that software at the time of this writing.</p>
|
||
|
||
<p>The “<b>Clear</b>” button clears the previous export.</p>
|
||
|
||
<h2>Caveats / Limitations</h2>
|
||
<p>In “biome points” mode, it is perfectly <b>legal</b> to have the biome points to be <b>out of the bounds</b> of the diagram. These out-of-bounds points are represented as arrows in the diagram. However, you can’t select them with your mouse on the diagram unless it’s close to the edge. Use the biome list to edit points that are out of bounds.</p>
|
||
|
||
<p>Heat/humidity <b>values above 1,000,000 or below −1,000,000</b> are <b>not supported</b> and will trigger an error message. This is a much smaller range than what Luanti supports. Also, no diagram can be drawn if the heat or humidity noise scale equals 0 or is very small, although this is legal in Luanti. This does not mean that your chosen settings won’t work in Luanti, just that LiBPoV can’t visualize them.</p>
|
||
|
||
<h2>Credits / License</h2>
|
||
<p>LiBPoV is <b>free software</b>. See the <a href="./license.html">License</a> page for details.</p>
|
||
|
||
<h2>Appendix</h2>
|
||
|
||
<h3>LiBPoV JSON format</h3>
|
||
<p>LiBPoV uses JSON to import and export the biome points. For general information about JSON, see <a href="https://www.json.org/" title="Introducing JSON">www.json.org</a>. This section explains how this format is used by LiBPoV.</p>
|
||
|
||
<p>“LiBPoV JSON” is just normal JSON. The name “LiBPoV JSON” is used to clarify that LiBPoV is the intended use case for this JSON format. The reason for this name is because internally, the <i>Amidst for Minetest</i> biome profiles are also JSON-based, so we say “LiBPoV JSON” to avoid any confusion.</p>
|
||
|
||
<h4>Definition</h4>
|
||
|
||
<p>A LiBPoV JSON text is a JSON text that is an array of objects. Each object in that array represents a biome. Each of these objects must contain the following fields:</p>
|
||
|
||
<ul>
|
||
<li><code>name</code>: Biome name (string). Same name as in Lua</li>
|
||
<li><code>heat_point</code>: Heat point (number). Same name as in Lua</li>
|
||
<li><code>humidity_point</code>: Humidity point (number). Same name as in Lua</li>
|
||
</ul>
|
||
|
||
<p>Additionally, the object may optionally specify any of the following fields:</p>
|
||
|
||
<ul>
|
||
<li><code>x_min</code>: Minimum X position of biome (number). Corresponds to <code>min_pos.x</code> in Lua</li>
|
||
<li><code>x_max</code>: Maximum X position of biome (number). Corresponds to <code>max_pos.x</code> in Lua</li>
|
||
<li><code>y_min</code>: Minimum Y position of biome (number). Corresponds to <code>min_pos.y</code> or <code>y_min</code> in Lua</li>
|
||
<li><code>y_max</code>: Maximum Y position of biome (number). Corresponds to <code>max_pos.y</code> or <code>y_max</code> in Lua</li>
|
||
<li><code>z_min</code>: Minimum Z position of biome (number). Corresponds to <code>min_pos.z</code> in Lua</li>
|
||
<li><code>z_max</code>: Maximum Z position of biome (number). Corresponds to <code>max_pos.z</code> in Lua</li>
|
||
<li><code>color_index</code>: A number that represents a color of the biome color palette, starting with 0. Used by LiBPoV to store the biome color in the diagram, otherwise meaningless. The number does not represent any particular color, only a palette index, as the palette might change in future.</li>
|
||
</ul>
|
||
|
||
<p>If unspecified, the minimum/maximum position arguments default to -31000 (minimum) and 31000 (maximum). If <code>color_index</code> is unspecified or is out of range, LiBPoV will pick a color index based on the position in the JSON array.</p>
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|
||
|