anarchy 2.0

Managed chaos for procedural content generation, including incremental/reversible pseudo-random numbers and shuffling/distribution.

Overview

anarchy is a package for managed & beautiful chaos, designed with incremental procedural content generation in mind. It includes incremental & reversible random numbers, a selection of distribution functions for random values, cohort operations that can be applied incrementally to groups along an indefinite 1-dimensional space, and function to incrementally/reversibly manage uneven distribution of items among segments.

The goal is to give a high level of control to designers of PCG systems while maintaining incremental operation and reversibility.

Coming soon: fractal coordinates.

Changelog

• Version 2.0: Added distribution sub-module, moved some old cohort functions over to it. Fixed bugs & added many tests. Added distribution_items and the sumtable_* functions. Got rid of max_smaller in favor of sumtable_segment.
• Version 1.1: Initial working version.

Versions

There are implementations of at least the core functionality available in C, C#, Javascript, Python, and Lua; this documentation applies most closely to the Python implementation, and it is drawn from that code. Each different language implementation has its own idiosyncrasies, but the higher-level things, like number and meaning of parameters, are the same for the core functions.

TODO: Links to versions...

Note: the anarchy Python package uses 64-bit integers, for compatibility with the C version of the library and for a larger output space. Technical limitations with JavaScript and Lua mean that the JS and Lua versions of the library effectively use 32-bit integers (stored inside 64-bit floats) and will therefore give different results.

Dependencies

The python version requires Python 3; tests use pytest and require Python >=3.6.

Example Application

The incremental shuffling algorithm can be used as a replacement for a standard random number generator in cases where you want to guarantee a global distribution of items and are currently using independent random number checks to control item distribution. For example, if you have code that looks like this...

def roll_item():
  r = random.random()
  if r < 0.01: # 1% chance for Rare item
    return "Rare"
  elif r < 0.06: # 5% chance for Uncommon item
    return "Uncommon"
  else:
    return "Common"

...you have no guarantees about exactly how often rare/uncommon items will be, and some players will get lucky or unlucky. Instead, even if you don't know the number of roll_item calls, with anarchy you can do this:

N = 0
seed = 472389223

def roll_item():
  global N, seed
  r = anarchy.cohort_shuffle(N, 100, seed + N//100)
  N += 1
  if r < 1:
    return "Rare"
  elif r < 6:
    return "Uncommon"
  else:
    return "Common"

In this code there are two extra variables that have to be managed in some way, but the benefit is that for every 100 calls to the function, "Rare" will be returned exactly once, and "Uncommon" will be returned exactly 5 times. Each group of 100 calls will still have a different ordering of the items, because it uses a different seed.

Here's an image illustrating the differences between these two approaches: in the top half, results are generated using independent random numbers, while the bottom half uses anarchy's cohort shuffling to guarantee one red cell and 5 blue cells per 10×10 white square..

{.pixels}\

There are many other potential applications of reversible/incremental shuffling; this is one of the most direct.