diff --git a/.ldoctest b/.ldoctest new file mode 100644 index 0000000..35a8350 --- /dev/null +++ b/.ldoctest @@ -0,0 +1,12 @@ +-- Environment for `forma` ldoctests +return { + math = math, + assert = assert, + print = function() end, + cell = require('forma.cell'), + pattern = require('forma.pattern'), + automata = require('forma.automata'), + primitives = require('forma.primitives'), + subpattern = require('forma.subpattern'), + neighbourhood = require('forma.neighbourhood'), + } diff --git a/CHANGELOG.md b/CHANGELOG.md index 4911150..b83406b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,3 +60,16 @@ - Slightly faster convergence check for `automata.iterate` - Harmonised coordinate handling between pattern prototype and tostring + +0.4 +--------- + +# Features +- Perlin noise sampling +- Quadratic Bezier curve drawing. + +# Misc + - Check that CA rule sets don't have neighbourhoods that are too large for + the rule signature format (>10 neighbours) + - Fixed some typos in usage examples + - Setup forma documentation example checking with `ldoctest` diff --git a/README.md b/README.md index 3140276..66e1aa5 100644 --- a/README.md +++ b/README.md @@ -21,12 +21,13 @@ suited (but not limited) to the generation of roguelike environments. - **A spatial-hashing pattern** class for fast lookup of active cells. - **Pattern manipulators** such as the addition, subtraction, rotation and reflection of patterns. -- **Rasterisation algorithms** for 2D primitives, e.g lines, circles, squares. +- **Rasterisation algorithms** for 2D primitives, e.g lines, circles, squares and Bezier curves. - A very flexible **cellular automata** implementation with - Synchronous and asynchronous updates - Combination of multiple rule sets - **Pattern sampling** algorithms including - Random (white noise) sampling + - Perlin noise sampling - Poisson-disc sampling - Mitchell's best-candidate sampling - **Algorithms for subpattern finding** including @@ -69,7 +70,7 @@ end -- Find all 4-contiguous segments of the CA pattern -- Uses the von-neumann neighbourhood to determine 'connectedness' --- but any custom neighbourhood can be used) +-- but any custom neighbourhood can be used. local segments = subpattern.segments(ca, neighbourhood.von_neumann()) -- Print a representation to io.output @@ -82,12 +83,19 @@ subpattern.print_patterns(domain, segments) is written in pure Lua, no compilation is required. Including the project is as simple as including the `forma` directory in your project or Lua path. -The easiest way to do this is via LuaRocks: +The easiest way to do this is via LuaRocks. To install the latest stable version +use: ```Shell luarocks install forma ``` +Alternatively you can try the dev branch with: + +```Shell + luarocks install --server=http://luarocks.org/dev golflike +``` + ## Documentation Documentation is hosted [here](https://nhartland.github.io/forma/). diff --git a/docs/contents.html b/docs/contents.html index 77612f5..e56de72 100644 --- a/docs/contents.html +++ b/docs/contents.html @@ -51,6 +51,7 @@

Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -127,6 +128,10 @@

    Examples

    maxrectangle.lua + + perlin.lua + + readme.lua @@ -145,7 +150,7 @@

    Examples

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/async_automata.lua.html b/docs/examples/async_automata.lua.html index afefc3c..9c48016 100644 --- a/docs/examples/async_automata.lua.html +++ b/docs/examples/async_automata.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -107,7 +108,7 @@

    async_automata.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/binary_space_partition.lua.html b/docs/examples/binary_space_partition.lua.html index 16b2bf0..a6d11b2 100644 --- a/docs/examples/binary_space_partition.lua.html +++ b/docs/examples/binary_space_partition.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -81,7 +82,7 @@

    binary_space_partition.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/bubbles.lua.html b/docs/examples/bubbles.lua.html index 0fc90d8..c3f1db1 100644 --- a/docs/examples/bubbles.lua.html +++ b/docs/examples/bubbles.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -91,7 +92,7 @@

    bubbles.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/cellular_automata.lua.html b/docs/examples/cellular_automata.lua.html index 4e248ff..33de9e0 100644 --- a/docs/examples/cellular_automata.lua.html +++ b/docs/examples/cellular_automata.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -94,7 +95,7 @@

    cellular_automata.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/corridors.lua.html b/docs/examples/corridors.lua.html index baa56fd..9f27e31 100644 --- a/docs/examples/corridors.lua.html +++ b/docs/examples/corridors.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -99,7 +100,7 @@

    corridors.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/isolines.lua.html b/docs/examples/isolines.lua.html index efaa5cc..cf94f78 100644 --- a/docs/examples/isolines.lua.html +++ b/docs/examples/isolines.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -102,7 +103,7 @@

    isolines.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/maxrectangle.lua.html b/docs/examples/maxrectangle.lua.html index 5d35f00..35075b5 100644 --- a/docs/examples/maxrectangle.lua.html +++ b/docs/examples/maxrectangle.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -85,7 +86,7 @@

    maxrectangle.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/perlin.lua.html b/docs/examples/perlin.lua.html new file mode 100644 index 0000000..c73dab7 --- /dev/null +++ b/docs/examples/perlin.lua.html @@ -0,0 +1,94 @@ + + + + + forma Reference + + + + +
    + +
    + +
    +
    +
    + + +
    + + + + + + +
    + +

    perlin.lua

    +
    +-- Perlin noise sampling
+-- Here we sample a square domain pattern according to perlin noise,
+-- generating three new patterns consisting of the noise thresholded at
+-- values of 0, 0.5 and 0.7.
+
+local subpattern = require('forma.subpattern')
+local primitives = require('forma.primitives')
+
+local domain = primitives.square(80,20)
+local frequency, depth = 0.2, 1
+local thresholds = {0, 0.5, 0.7}
+local noise  = subpattern.perlin(domain, frequency, depth, thresholds)
+
+-- Print resulting pattern segments
+subpattern.print_patterns(domain, noise, {'.', '+', 'o'})
    + + +
    +
    +
    +generated by LDoc 1.4.6 +Last updated 2019-01-07 21:10:29 +
    +
    + + diff --git a/docs/examples/readme.lua.html b/docs/examples/readme.lua.html index 1d2f4c4..cbde4e0 100644 --- a/docs/examples/readme.lua.html +++ b/docs/examples/readme.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -112,7 +113,7 @@

    readme.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/sampling.lua.html b/docs/examples/sampling.lua.html index 2240198..e37e952 100644 --- a/docs/examples/sampling.lua.html +++ b/docs/examples/sampling.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -93,7 +94,7 @@

    sampling.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/examples/voronoi.lua.html b/docs/examples/voronoi.lua.html index 9bb5ca2..38ec4c9 100644 --- a/docs/examples/voronoi.lua.html +++ b/docs/examples/voronoi.lua.html @@ -41,6 +41,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -85,7 +86,7 @@

    voronoi.lua

    generated by LDoc 1.4.6 -Last updated 2018-08-08 18:12:10 +Last updated 2019-01-07 21:10:29
    diff --git a/docs/modules/forma.automata.html b/docs/modules/forma.automata.html index cf1f194..3f9d04a 100644 --- a/docs/modules/forma.automata.html +++ b/docs/modules/forma.automata.html @@ -59,6 +59,7 @@

    Examples

  • corridors.lua
  • isolines.lua
  • maxrectangle.lua
    • +
  • perlin.lua
  • readme.lua
  • sampling.lua
  • voronoi.lua
    • @@ -73,25 +74,27 @@

    Module forma.automata

    -

    Cellular Automata are defined here by two parameters. Firstly a - neighbourhood that the rule acts on. Secondly a rule specifying the - conditions under which cells are Born (B) or Survive (S). These rules - are initialised with a string rule in the "Golly" format. i.e a rule which - activates cells with one neighbour and deactivates cells with two would have - the rule string "B1/S2". The neighbourhood is specified by an instance of - the neighbourhood submodule as usual.

    +

    Cellular Automata are defined here by a ruleset (a table of individual + CA rules). Each rule consists of two parts. Firstly a neighbourhood that + the rule acts on. Secondly a rule signature specifying the conditions + under which cells are Born (B) or Survive (S). These rule signatures are + initialised with a string in the "Golly" format. i.e a rule which activates + cells with one neighbour and deactivates cells with two would have the rule + string "B1/S2". The neighbourhood is specified by an instance of the + forma.neighbourhood class as usual.

    -

    Once a rule is specified, there are two provided implementations of a CA. +

    Once a ruleset is specified, there are two provided implementations of a CA. Firstly the standard synchronous CA is implemented in automata.iterate whereby all cells are updated simultaneously. Secondly an asynchronous update is provided in automata.async_iterate in which each iteration updates only one cell at random.

    -

    For both methods, multiple rules can be applied simultaneously through the - ruleset by supplying a table containting more than one rule. Rule - conflicts are resolved in favour of cell deactivation, i.e if there are two - nested rulesets, with a cell passing one and failing the other either - survival or birth rules, the cell will be deactivated in the next iteration.

    +

    When a ruleset consists of only one rule, the CA is unambiguous and is + applied in the conventional manner. When multiple rules are provided, rule + conflicts are resolved in favour of cell deactivation. For example, if there + are two rules in the set, cell activation requires that the candidate cell + passes the 'birth' criterion of both rules. Cell deactivation requires only + that one 'survive' criterion fails.

    All CA updates here are only possible on a finite domain of cells. That domain must be specified as a pattern in the iteration call.

    @@ -211,7 +214,7 @@

    Usage: