minetest_perlin_explorer_2025/README.md

# Perlin Explorer [`perlin_explorer`]

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 yet.

## 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 a map 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 various things such as generating the map,
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 might it make more
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. Please refer to the Minetest Lua API
documentation to learn more.

### 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 heart 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
* eased
* absvalue

Please refer to Minetest Lua API documentation for a definition.
Node this mod will enforce sanity check 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 current
noise parameters. First, the minimum and maximum possible value
throughout 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 the official Lua documentation discourages
this. If this happens, either increase the spread, the octaves
or the lacunarity.

###### 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 two types of profiles:

* Builtin profiles are the noise parameters
  of the official Minetest mapgens, loaded from settings.
  Their name always begins with `mg_`
  They can not be deleted.
* Custom profiles: These are your profiles, you can
  add and remove them at will. These are named like
  “Profile 1”

The buttons do the following:

* Add: Save the current noise parameters into a new entry in the list
* Load: Load the currently selected profile and replace the
        input fields
* Delete: Delete the currently selected profile (not possible
          for builtin profiles)

Note: Currently, profiles are temporary. They are **not** saved on shutdown!

##### Noise options
This section roughly says how the noise parameters are “interpreted”. You
can do 3 things here:

* 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 millions of values (without generating a
  map 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 10 “buckets” of
  equal sizes, beginning with the lowest theoretical value and
  ending with the highest one.
  The statistics are useful if you want to make sure certain values
  occur with a certain probability.

##### 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.

In 2D mode, the mapgen will a flat XZ plane with nodes,
one node for every value.

In 3D mode, the mapgen will place nodes at every position
with a value of greater than or equal to 0. Negative values
will be air.
(Negative nodes are not placed because then the whole area
would be full of nodes and you would barely see anything! :D)

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

* White to yellow to orange: Zero and positive values
* Light blue to blue (with a small dot): Negative values

Now, here are the parameters you can use:

* Min. color at: You are supposed to enter a Perlin value here.
  This is the value at which the color gradient of the
  negative values begins. This number must be negative.
* Max. color at: Same as above, but this is where the
  positive color gradient ends. Must be a positive number

You don’t *really* need the color coding to be setup right as
you can always use the Perlin Value Getter. But it can be
very helpful to get a feel.

* 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.

Finally, there is a list of node types. This is just to
give different visualizations of the same thing and has
no other meaning:

* 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 positive 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,
consider reducing the render distance if you get dizzy.
Also be warned this might drop your FPS sharply, especially
if your rendering distance is too large.


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

The footer is the final part of the formspec. He

* Apply: Set the current noise params as the “active noise”. If the
  mapgen is active, it will automatically update
* Apply and create: Generate some nodes at the specified XYZ coordinates
  with the specified size (see 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 *currently active noise
params* (by triggering the “Accept” or “Accept and create” button in the Perlin Noise
Creator). It completely ignores what kind of terrain you touch, so this
tool also works if you haven’t generated any nodes.
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, but do not regenerate map
* Place: Set a new seed and regenerate nodes (using the XYZ and Size parameters
  in the Perlin Noise Creator)

### 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 values in the histogram seem to be strongly biased
The statistics screen randomly picks values from -30000 to +30000 in
each axis.
When the noise spread is very large (usually over 10000), the
quality of the statistics becomes worse down as it only picks values
from a small section of the noise.
Don’t worry: Your noise might still have a proper distribution, it’s
just the statistics fails to see them.
As a workaround, you can consider reducing the spread temporarily, just for
the statistics, to get a better impression.

#### The histogram shows 100% for one bucket. Why?
The most likely reason is that `scale` is exactly 0. This is correct.
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.
But this 100% problem can also happen if you have a huge spread (see above).

## 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.