Types/NoiseExpression: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
m (Syntax-highlight the literal-object example)
(Removed old prototype docs)
Tag: Replaced
 
(36 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== Basics ==
<div class="stub"><p>'''The prototype docs have moved to a new website with an improved format.''' This documentation page can now be found here: [https://lua-api.factorio.com/latest/types/NoiseExpression.html https://lua-api.factorio.com/latest/types/NoiseExpression.html]


A fragment of a functional program used to generate coherent noise, probably for purposes related to terrain generation.
</p><p>This wiki page is no longer updated and '''will be removed at some point in the future''', so please update your browser bookmarks or other links that sent you here. If you'd like to contribute to the new docs, you can leave your feedback [https://forums.factorio.com/viewforum.php?f=233 on the forums].</p></div>
 
Noise expressions can be provided as object literals or built using functions in the built-in <code>noise</code> library.
<code>noise.define_noise_function</code> allows noise expressions to be defined using a shorthand
that's a subset of Lua (see [[#Example definition|example definition]] for an example and its literal equivalent).
 
== Mandatory properties ==
 
=== type ===
 
'''Type''': [[Types/string]]
 
Name of the type of this expression.
Which other properties apply depend on the expression type.
 
== Expression types ==
 
=== variable ===
 
Reference to a pre-defined variable, constant, or a named noise expression.
 
Predefined variables include "x", "y", and "distance".
 
Properties:
 
* '''variable_name''': a [[Types/string]]
 
=== function-application ===
 
Apply a function to a list or associative array of arguments.
Some functions expect arguments to be named and some expect them not to be.
 
Function calls are their own class of expression
(as opposed to every function just being its own expression type)
because function calls all have similar properties --
arguments are themselves expressions,
a call to any pure function (i.e. most functions other than <code>random()</code>)
is [https://en.wikipedia.org/wiki/Referential_transparency referentially transparent]
and can be constant-folded if all of its arguments are constant, etc.
 
Properties:
 
* '''function_name''' (a string; see functions, below)
* '''arguments''' (a list or associative array of argument expressions)
 
=== literal-number ===
 
Evaluates to the same number every time, given by the '''literal_value''' property.
 
=== literal-string ===
 
Evaluates to the same string every time, given by the '''literal_value''' property.
 
Since the noise generation runtime has no notion of strings or use for them,
this is useful only in constant contexts.
 
=== literal-object ===
 
Evaluates to the same object every time, given by the '''literal_value''' property.
 
e.g.
 
<syntaxhighlight lang="lua">
{
  type = "literal-object",
  literal_value = {
    name = "Bob Hope",
    birth_date = {
      year = 1903,
      month = 5,
      day_of_month = 29
    }
  }
}
</syntaxhighlight>
 
Since the noise generation runtime has no notion of objects or use for them,
this is useful only in constant contexts, such as the '''points''' argument
of the '''distance-from-nearest-point''' function.
 
== Functions ==
 
=== add ===
 
'''Arguments (positional)''': term, other term
 
Takes 2 positional arguments and adds them.
 
=== subtract ===
 
'''Arguments (positional)''': minuend, subtrahend
 
Takes 2 positional arguments and subtracts the second from the first.
 
=== multiply ===
 
'''Arguments (positional)''': factor, other factor
 
Takes 2 positional arguments and multiplies them.
 
=== divide ===
 
'''Arguments (positional)''': dividend, divisor
 
Takes 2 positional arguments and divides the first by the second.
 
=== exponentiate ===
 
'''Arguments (positional)''': base, exponent
 
Takes 2 positional arguments, and raises the first to the second power.
 
=== absolute-value ===
 
'''Arguments (positional)''': value to be absoluted
 
Takes a single positional argument and returns its absolute value.  i.e. If the argument is negative, it is inverted.
 
=== clamp ===
 
'''Arguments (positional)''': value to be clamped, lower limit, upper limit
 
First argument is clamped between the second and third. The second is treated as a lower limit and the third the upper limit.
 
=== ridge ===
 
'''Arguments (positional)''': value to be ridged, lower limit, upper limit
 
Similar to clamp but the input value is folded back across the upper and lower limits
until it lies between them.
 
=== factorio-basis-noise ===
 
'''Arguments (named)''':
 
* '''x'''
* '''y'''
* '''seed0''' - integer between 0 and 4294967295 (inclusive) used to populate the backing random noise
* '''seed1''' - integer between 0 and 255 (inclusive) used to provide extra randomness when sampling
* '''input_scale''' (default: 1) - x and y will be multiplied by this before sampling
* '''output_scale''' (default: 1) - output will be multiplied by this before being returned
 
Scaling input and output can be accomplished other ways, but are done so commonly
as to be built into this function for performance reasons.
 
=== factorio-multioctave-noise ===
 
'''Arguments (named)''':
 
* '''x'''
* '''y'''
* '''seed0''' - integer between 0 and 4294967295 (inclusive) used to populate the backing random noise
* '''seed1''' - integer between 0 and 255 (inclusive) used to provide extra randomness when sampling
* '''octaves''' - how many layers of noise at different scales to sum
* '''persistence''' (constant) - how strong is each layer compared to the next larger one
* '''input_scale''' (default: 1) - x and y will be multiplied by this before sampling
* '''output_scale''' (default: 1) - output will be multiplied by this before being returned
 
== Example definition ==
 
To override the 'temperature' named noise expression with one that linearly increases to the southeast:
 
<syntaxhighlight lang="lua">
local noise = require("noise");
 
data:extend{
  {
    type = "noise-expression",
    name = "temperature", -- for 0.17; for 0.16 override "default-temperature" instead.
    expression = noise.define_noise_function( function(x,y,tile,map)
      return (x + y) / 1000
    end)
  }
}
</syntaxhighlight>
 
Which is equivalent to:
 
<syntaxhighlight lang="lua">
local noise = require("noise");
 
data:extend{
  {
    type = "noise-expression",
    name = "temperature",
    expression = {
      type = "function-application",
      function_name = "divide",
      arguments = {
        {
          type = "function-application",
          function_name = "add",
          arguments = {
            {
              type = "variable",
              variable_name = "x"
            },
            {
              type = "variable",
              variable_name = "y"
            }
          }
        },
        {
          type = "literal-number",
          literal_value = 1000
        }
      }
    }
  }
}
</syntaxhighlight>

Latest revision as of 14:32, 25 October 2024

The prototype docs have moved to a new website with an improved format. This documentation page can now be found here: https://lua-api.factorio.com/latest/types/NoiseExpression.html

This wiki page is no longer updated and will be removed at some point in the future, so please update your browser bookmarks or other links that sent you here. If you'd like to contribute to the new docs, you can leave your feedback on the forums.

Retrieved from "https://wiki.factorio.com/index.php?title=Types/NoiseExpression&oldid=202822"