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 statistics screen shows my values are very crowded or even 100% in a bucket!

This can happen when the spread is very large (usually larger than 1000), then it’s likely the statistics only has seen only a small portion of the structure. Don’t worry: Your noise might still have a proper distribution, it’s just the statistics calculations weren’t complete enough. Note that calculating statistics for arbitrary large areas/volumes would just be too computationally expensive so that’s not a good option. As a workaround, you can consider reducing the spread temporarily, just for the statistics, to get a better impression.

Another reason for hitting exactly 100% when every value really is equal. This can happen if scale is exactly 0. Remember the result of all noise computations is multiplied with scale afterwards, and multiplying with 0 will, of course, eliminate it all.

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.

README.md Unescape Escape

Perlin Explorer [perlin_explorer]