Version 1.0.3

[minetest_perlin_explorer.git] / README.md

# Perlin Explorer [`perlin_explorer`]

Version: 1.0.3

Perlin Explorer is a mod for Minetest to allow to test and experiment around with Perlin noises.

This is especially useful for game and mod developers who want to fine-tune the noises in an
efficient manner. It’s also useful to discover useful noise parameters for the various
mapgen settings in Minetest.

This mod uses Minetest’s builtin Perlin noise, so the same rules apply here.
Refer to Minetest’s documentation to learn about noise parameters.

## /!\ WARNING WARNING WARNING /!\

This mod can aggressively **grief** your world due to its
mapgen feature! Don’t use it in worlds with buildings
you care about.

**NEVER** use this mod on a public server, it has not been
security-tested.

## Features

* Powerful noise parameter editor to quickly adjust parameters
* Look up Perlin noise value at a given position
* Special nodes to represent noise values
        * Color denotes value, cutoff points can be customized
        * Choose between solid nodes, transparent grid nodes, and tiny climbable cube nodes
* Generate a small portion of the noise as map at a given area
* Enable “mapgen mode” to automatically generate nodes as you move around
* Load predefined Perlin noises from the Minetest configuration
* Save noise parameters into profiles for later use
* Mathematical and statistical analysis of noises

## Usage
### Before you begin
This document assumes you already have a rough understanding of what
Perlin noises are used for.

To use this mod, create a brand new world to avoid accidents.

Everything in this mod requires the `server` privilege, so obtain
this privilege as well.

### Overview
The main feature and tool in this mod is the Perlin Noise Creator. Using
this item opens a window in which you can view, modify, analyze and
manage noise parameters, generate nodes and perform some basic
analysis.

### What are noise parameters?
These are used by Minetest for the Perlin noises.
Perlin noises are used for various things such as generating the world,
decorations (trees, plants, etc.), ores, biomes and much more.

And noise parameters are, well, the parameters that are used
to tweak the Perlin noises. They change the output numbers,
they stretch or squeeze the noise, they make more or less
detailed, and more.

The Perlin Explorer mod’s main use case is to allow you to
try out various parameters and to modify them in a quick
manner so you can quickly get results. This is much more
efficient than tweaking the noise in the Minetest settings
or Lua code.

This document is *not* an introduction to Perlin noises
and noise parameters themselves! Please refer to the Minetest
Lua API documentation to learn more.

### Active noise
This mod heavily relies on something called the “active noise”
(or “active noise parameters”). These are the noise parameters
and options that the mod will use for various operations, like
getting values, generating nodes, using mapgen mode, etc. The “Apply” button
in the Perlin Noise Creator tool sets the active noise.
There can only be one active noise parameters. Also, the active
noise is always valid; if you enter invalid noise parameters,
the mod refuses them for the active noise.

Initially, there are no active noise parameters, so you have
to push the “Apply” button mentioned before first.

### The tools
This section explains the various tools you have at your disposal.
These tools are items, so check out your Creative Inventory
(or something similar) to get them.

#### Perlin Noise Creator
This is the main tool of this mod. Hold this item in hand and punch
to open a window.

The window has multiple sections:

* Noise parameters: You specify noise parameters here
* Noise options: This is how the noise parameters are being interpreted
* Node generation: Stuff you need to specify when you want to generate
  a chunk (or chunks) of nodes

##### Noise parameters

This section has 2 parts: The top part is a list of profiles.
An explanation for that is below.

The bottom part contains the actual noise parameters:

* Offset
* Scale
* Seed
* X/Y/Z Spread
* Octaves
* Persistence
* Lacunarity
* Flags (defaults, eased, absvalue)

Please refer to Minetest Lua API documentation for a definition.
This mod enforces a few sanity checks on some for the values,
i.e. octaves can’t be lower than 1.

**Hint**: If you hit “Enter” while the focus is on any of the noise
parameters, this is the same as if you clicked “Accept” or “Accept
and create” (see below). Use this to your advantage to quickly
tweak a particular value.

The little dice button randomizes the seed, it’s a simple
convenience.

The “Analyze” button shows you some basic info about the
noise parameters as displayed in the form. First, the
theoretical minimum and maximum possible value
of the entire noise.
Then, the “wavelengths” for each axis. This means across
how many nodes (roughly) the noise is stretched out, specified
for each octave, beginning with the first.
If any wavelength reaches a number lower than 1, it will be
shown in red because this means your noise parameters are invalid.
If this happens, either increase the spread or decrease the octaves
or lacunarity.

**Note**: The Analyze feature uses the noise parameters as they
are displayed in the form, *not* the *active* noise parameters.
This is because the active noise must always be valid.

###### Profiles
A profile is just noise parameters that you can load for later use.
It’s a convenience feature.
The drop-down list to the left is the list of all profiles.
This list contains three types of profiles:

* Active noise parameters: Special profile that represents
  the currently active noise. Can not be deleted.
* Builtin profiles are the noise parameters
  of the official Minetest mapgens, loaded from settings.
  Their name always begins with `mg_`
  Can not be deleted.
* User profiles: These are your profiles, you can
  add and remove them at will. These are named like
  “Profile 1”

User profiles will also automatically saved on disk so they
get restored when restarting the world.

The buttons do the following:

* Add: Save the current noise parameters into a new user profile
* Load: Load the currently selected profile and replace the
        input fields
* Delete: Delete the currently selected user profile (not possible
          for non-user profiles)

##### Noise options
This section roughly says how the noise parameters are “interpreted”.
These fields are available:

* Number of dimensions (2D or 3D)
    * 2D: Noise is 2-dimensional. In the world, only the X and Z
      coordinates are used. The Y coordinate is ignored.
    * 3D: Noise uses the same 3 dimensions as the Minetest world,
      with X, Y and Z coordinates.
* Pixelization: If this number is higher than 1, the noise values
  will be repeated for this number of nodes, along every axis.
  This gives a “pixelized”/“voxelized” look. You normally don’t need
  this but it’s useful to emulate the `sidelen` parameter of
  mapgen decorations (relevant for game development)
* Statistics: Will calculate tons of values (without generating
  nodes) in a predefined area/volume to make some statistics. This
  will take a while to do so.
  The main feature is a histogram which shows which values were the most
  common. The first row shows the percentage, the 2nd and 3rd row show
  the maximum and minimum value of that column. For example,
  if the column says “31.4%”, “0.0” for “Max.” and “-4.2” for “Min.” that means
  that 31.4% of all values that were calculated were greater than or equal
  to -4.2, but smaller than 0.
  The statistics always distributes the values into “buckets” of
  equal sizes, beginning with the lowest theoretical value and
  ending with the highest one.
  The histogram is useful if you want to see how common or rare
  each value is.
  **Note**: This button will calculate statistics of the noise settings
  as they were displayed in the form. It does *not* use the active noise.

##### Node generation

Playing around with parameters isn’t very useful if you don’t
get a visual result. That’s where the node generation comes
into play. Here you specify parameters for generating nodes
from the noise.
All noise values are either high or low; they are divided
by the **midpoint**: Values equal to or higher than the
midpoint are high, otherwise low.

In 2D mode, the mapgen will be a flat XZ plane with nodes.

In 3D mode, the mapgen will place nodes at every position
in the 3D world.

###### Build modes

The drop-down list to the bottom right stands for the
“build modes”. This sets for which noise values nodes
will be generated:

* Auto: In 2D mode, generate nodes for every value,
        in 3D mode, only generate nodes for high values
* All: Generate nodes for every value
* High only: Only generate nodes for high values
* Low only: Only generate nodes for low values

###### Node visualization

Generated nodes will be color-coded, which stands for the value:

* White to yellow to orange: High values
* Light blue to blue (with a small dot): Low values

There are two parameters:

* Low color at: The lowest noise value at which the
  color gradient for low noise values begins.
* High color at: The highest noise value at which the
  color gradient for high noise values ends.

The low color gradient begins at the “Low color at”
setting and ends right before the the midpoint.
The high color gradient begins at the midpoint
and ends at the ”High color at” setting.

For example, if 0 is the midpoint, and the “low/high color”
settings are -1 and 1, respectively, all values below 0 (the
midpoint) will use the ‘low values’ color gradient and all
values above 0 will use the ‘high values’ color gradient.
All values at -1 and below will have the “extreme low”
color (dark blue) and all values at 1 or above will have the
“extreme high” (orange) color.
Note that the colors only serve as a visual aid and
given the limited palette, is only an estimation
of the noise values. You can always use the Perlin Value
Getter for the exact values.
If you have problems seeing color differences, activate
the grayscale color palette in the mod settings.

###### Node types

Right to the color settings, there is a list of node types.
This is for different node styles for different
noise visualizations:

* Solid Nodes: Simple, solid, opaque cubes
* Grid Nodes: Solid see-through nodes (like glass)
* Minibox Nodes: See-thorough nodes, but smaller. You can also
  walk and climb up on down in these
* Stone: Places stone for high values, air otherwise.
  This uses the stone node from the game (if it supports it).

Solid Nodes are recommend to use normally.

Grid or Minibox nodes can be useful in 3D mode if you want to
expose the inner structure of complex 3D noises. This can be quite
trippy and reduce your FPS sharply, so consider reducing the
render distance.

###### Position settings

The following settings are only used when you want
to place nodes in a certain area:

* X, Y, Z: Coordinates of the bottom left front corner if you
 want to generate an area manually with “Apply and create”
* Size: Side length of the square or cube of the area/volume
  to generate, if you generate it with “Apply and create”.
  **ATTENTION:** Don’t make this value too large
  (especially in 3D), otherwise map generation
  will take forever and the game freezes.

#### Footer (Apply / Apply and close / Enable mapgen / Disable mapgen)

The footer is the final part of the form. It has these buttons:

* Apply: Set the current noise params as the “active noise”. If the
  mapgen is active, it will automatically update the world around
  players
* Apply and create: Generate some nodes at the specified XYZ coordinates
  with the specified size (see Position settings above)
* Enable mapgen: Enable the mapgen mode. In mapgen mode, nodes will
  automatically be generated according to the settings around players.
  This allows you to actually *explore* a world.
  When a new part of the world is created, a little star icon will
  appear in its center to show you this part is new.
  Note: When mapgen mode is enabled, the XYZ, size and “Apply and create”
  buttons disappear because those are for single generations.
  Note: If you modify the noise parameters and hit “Accept”, the mapgen
  will automatically update.
* Disable mapgen: Disables the mapgen again. The “XYZ”, “Size”
  and “Apply and create” will appear again.

### Perlin Value Getter
This item tells you the (nearly) exact value of the current active
noise parameters at a given position. You can use it on nodes
and in mid-air.

Use the “Place” key on a node to get the value of the node position.
Use the “Punch” key anywhere to get the value of *your* position (rounded).
If you hold down “Sneak” while punching, your *exact* position (not rounded)
will be used instead.

**Note**: This tool always calculates the values of the *active noise*
It completely ignores whatever nodes were generated and what those nodes
represents, so tool also works if you haven’t generated any nodes.
It actually only looks at the coordinates of the node or yourself.
If you’re unsure about what the current active noise is, just hit “Accept” again
in the Perlin Noise Creator.

### Random Perlin seed setter

This is just a convenience item. Using it is the same as opening the Perlin Noise
Creator, changing the seed and accepting.

In mapgen mode, punching or placing will set a new seed only, but the mapgen
will then instantly update the map.

If mapgen mode is disabled, the meaning of this tool is this:

* Punch: Set a new seed of the active noise, but do not regenerate map
* Place: Set a new seed  of the active noise, then regenerate nodes
  (using the XYZ and Size parameters in the Perlin Noise Creator)

This can be useful to look at many different variations of the noise.

### Troubleshooting

#### The mod hangs up / is extremely slow
Sorry! :-(

This can happen if the mod tries to calculate enormous numbers of values
or generates a huge number of nodes.

Which is the case if you selected a huge number when starting to
generate nodes.

Be careful with large numbers in 3D mode as it is exponentially more
expensive to calculate than 2D.

The only thing you can do is to just not generate huge areas at once.
The mod doesn’t have any warnings in place for now, so you’re on
your own for now. Sorry! :-(

#### The Perlin noise gives the exact same value everywhere.
The most likely reason is that `scale` is exactly 0.
Because if `scale` is 0, the noise will return the same value
everywhere. Remember the result of all noise computations is multiplied
with `scale` at the end, so a multiplication with 0 will
literally nullify all that.
This is correct behavior but obviously useless.
Just pick a non-zero scale to fix this.

## Credits
This mod was written by Wuzzy.

## License

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.