Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Emergence is a visualiser/processor of a primordial particle system and its emergent/interactive properties.

Implementation is based on the article, How a life-like system emerges from a simple particle motion law, by Schmickl, Stefanec, and Crailsheim:

There are two ways of using the program: graphically via the browser interface and headlessly via the commandline. The former allows the user to control various parameters and visually appreciate the effects, while the latter opens up possibilities for automation and batch analysis.



Browser interface

Point your (javascript-and-html5-capable) browser to emergence/index.html

  • For example, assuming that this repository was cloned into the Downloads folder, open a browser tab and visit file:///home/user/Downloads/mff/emergence/index.html.
Commandline interface
  1. Have nodejs installed,
  2. Download this repository.
  3. On the commandline, go to the emergence/ directory within the downloaded repository.
  4. Try node core.js -h


Visit for an instance of the browser interface.

Interface help

For quick help on the browser interface, click the HELP button at the top-left corner.

For quick help on the commandline interface, run node core.js -h.

For more detailed help, see “Usage” section below.




User-controllable state parameters

(Default values are in parentheses.)

  • width (browser|1000): world width
  • height (browser|1000): world height
  • stop (0): number of ticks of animation/computation
  • distribution (0): initial particle distribution scheme
    • 0: uniform, 1: gaussian, 2: middle
  • fps (30): frames per second (applies to browser interface only)
  • num (4000): number of particles
  • psize (3): size of individual particles
  • radius (auto): radius of neighborhoods
  • density (8.0): “density” that factors in the auto-radius calculation
  • alpha (180.0): self-dependent direction of particles
  • beta (17.0): neighbor-dependent direction of particles
  • gamma (0.134): neighbor-based speed multiplier

density, alpha, beta, and gamma are floating point numbers and the rest are integers. Except for alpha and beta, the numbers are expected to be at least 0, and in the case of width and height strictly greater than 0.

Browser interface

Usage with the browser is straightforward – buttons, input areas, and mouse-clicking being the only means of direct control.

The HELP button at the top-left corner outlines basic usage and repeats some of the information presented in this readme.

Interface structure:

  • Bar at the top:
    • Left:
      • PAUSE/RESUME: The label switches, based on the animation state.
      • HELP: Opens the “help” dialog box.
      • LOAD: Opens the “load” dialog box.
        • Text area: Type in state string directly.
        • READ IN FILE: Open a file to load its contents into the text area.
        • APPLY: Apply the world state to be whatever string is in the text area.
      • SAVE: Opens the “save” dialog box.
        • Text area: When the dialog box appears, this area gets automatically filled with a snapshot of world state. Modifiable.
        • SAVE TO FILE: Save the contents of the text area into a file.
        • COPY STATE: Copy the contents of the text area into the clipboard.
      • Dialog boxes (aka. “modals”): Size is proportional to the window size. Scrollable. Only way to close the dialog box is by clicking the “close” button at top-left.
      • Note: Clicking HELP, LOAD, or SAVE pauses animation until the user clicks RESUME or the canvas.
    • Middle:
      • History slider: Slide around to visit earlier snapshots of the animation.
      • “x”: Select the color theme.
      • “c”: Select the world “configuration” (ie. predefined/interesting alpha and beta values).
      • “o”: Select the initial particle distribution scheme.
        • Note: Selection will reanimate a new world from scratch.
      • “t”: The stop parameter.
      • RANDOM: Set the alpha and beta parameters randomly and reanimate from scratch.
    • Right:
      • APPLY: Merge all the parameters into the running world state, transitioning immediately to the new state.
      • RESTART: Set the world state as the parameters, and reanimate from scratch.
      • “f”, “n”, “z”, “r”, “d”, “alpha”, “beta”, “gamma”: The fps, num, psize, radius, density, alpha, beta, and gamma parameters respectively.
    • Note: Leaving a parameter empty, and clicking APPLY or RESTART or making a selection (of the Middle section) will reset that parameter to its default value.
  • The canvas:
    • This is an HTML5 Canvas object and all the rendering that takes place therein is computed internally, mostly by view.js.
    • Can be clicked to toggle animation, exactly like the PAUSE/RESUME button.
Commandline interface
Usage: node core.js [ -?/-h/--help | -f/--file FILE [STRING] | STRING ]
  • An example: node core.js ″500 500 200″ > base.txt && node core.js -f base.txt ″_ _ 600″
    • This runs the computation in a 500-by-500 world for 200 ticks and saves the resulting state to a file called base.txt. Once that completes, computation is run again but with the base.txt file passed in as the initial state and the number of ticks overridden to be 600. The result of this second run is printed to standard output.
  • Only the resulting state is printed to standard output. Everything else, like info messages and any post-computation analyses, is printed to standard error.
  • Note: Passing state via standard input is currently not supported.
Input format
  • The “input state string” is a string of 0 or more lines. Each line is itself a string of numbers, separated by horizontal whitespace.
    • The first line has the format width height stop distr fps num psize radius density alpha beta gamma.
    • Every line thereafter denotes a particle, and the format there is index x-coordinate y-coordinate phi, where index is the particle number starting from 1, and phi is the particle heading (ie. its direction).
    • If any of these values are unparseable, the program silently falls back to default values (or random values in the case of particle attributes). If the entire input is empty, the commandline will default, and the browser will print a warning message.
  • The state string may be incomplete (ie. partially specified). In such cases, parameters are extracted in-order and left-to-right. So, as seen in an earlier example, an input string with three numbers effectively specifies just the width, height, and stop, keeping everything else at their respective default values. In order to specify parameters non-consecutively, the _ symbol (or any other non-numeric string) can be used in the place of unwanted parameters.
    • Here is another example of the first line. 200 200 100 0 _ 50 specifies a 200-by-200 world, running for 100 ticks, with 50 particles in uniform initial distribution. All other parameters (specifically, the underscored fps) are set to default values.
    • The particle lines (ie. lines 2 until end) are optional. But if they are to be specified, certain things ought to be kept in mind.
      • index is not parsed at all. It is only there for user convenience and gets regenerated on the next save.
      • Illegal x, y, and phi values will be ignored and random values will be set in their place.
Saving & loading

Browser interface:

  • As mentioned in “Usage” above, saving and loading is done through the SAVE and LOAD buttons respectively in the top-right corner.
    • The name of the save file is predetermined.
    • Clicking APPLY in the load dialog box loads the new world and immediately starts the animation.

Commandline interface:

  • Maybe not “saving” per se, but the output of the program represents a final state of the world. Analogously, the argument string/file to the program represents an initial state of the world. These are the only ways to save and load via the commandline.
Gotchas & interoperation

Hopefully, both headless and headed operations will be intuitive to the user, and switching between the two should be seamless since the same state string format is used everywhere, as far as the user is concerned. However, there are still a few quirks to keep in mind.

Number of ticks until stop:

  • On the browser, the default behavior is to animate indefinitely until explicit user intervention. On the commandline, however, a stop value of 0 means that the initial state gets printed and no real computation gets done. The user should therefore specify the third, stop, parameter to actually “run” the world.

World dimensions:

  • On the browser, the world naturally adopts the size of the browser. On the commandline, the world defaults to 1000 by 1000 (virtual units) if the user does not provide dimensions.
  • If specific dimensions are fed directly into the browser, by pasting the output of a prior commandline execution or otherwise, the input is scaled onto the actual browser canvas. (That is, of course, if the two sizes do not match up exactly.) So, for instance, if the browser window is huge but the size of the world has been set to only 100 by 100, the particles will appear relatively huge as well.

num vs pts.length:

  • The num parameter explicitly indicates the number of particles, but the length of the particles array does so implicitly as well. The ambiguity is resolved by giving num (or its default value if unspecified) precedence every time. So, for example, a num value set to 50, but with 4 particles listed in the input, will create 4 particles as enumerated, but then 46 more random particles will also be created. On the other hand, if num is set to 4 and 50 particles are specified individually, then the list gets truncated, and only the first 4 particles will get rendered.

Development notes



The browser interface lives in index.html. The HTML file renders all the static components, and loads the javascript files.


The bulk of the functionality is implemented in four javascript files.

  • core.js contains all the global variables (discounting the file namespace variables BRDG, VIEW, and UTIL), particle and “world” creation, and the functions that compute and manipulate the “world”.
  • view.js controls the browser interface (ie. the HTML page) by manipulating and reading from the DOM.
  • bridge.js connects the core and the view by supplying each side with necessary information. The core and view know almost nothing about each other, while the bridge knows a little about both.
  • headless.js provides a minimal commandline view and performs the simple task of handling commandline options, running the core computation in a loop, and spitting out the resulting state.

The util.js file includes common or miscellaneous code snippets that do not belong to precisely one of the other files.


The entry point for the browser interface is core.tick(), and the entry point for the commandline interface is headless.exec(). The former function gets strapped onto the HTML timer mechanism (ie. via setInterval), but headless.exec() gets executed straight in a while loop.

The notion of “when to stop execution” is dealt with in and around the respective functions. Stopping is optional with visual execution but necessary in the headless.

The ability to reuse one core.js file between the browser and the commandline is made possible with the nodejs javascript runtime. At the beginning of core.js, the file checks whether it was called by a browser or by the nodejs interpreter, and in the case of the latter, a call to headless.exec() is made.

data & state

core.js defines a central data store (in the form of global variables).

  • WORLD, STATE, and PTS together make up this central data store. They cover aspects like canvas dimensions, particle size, colors, direction parameters, and almost everything else.
  • Of the 3 variables, PTS is a just a simple list of particles, where each particle holds information about its own location, heading, and neighbor count.
  • WORLD and STATE are objects that contain information that particles need in order to exist, move, and get drawn. The two variables have basically the same kind and purpose, except for the fact that STATE gets saved and loaded, whereas WORLD does not. To put it another way, STATE represents the core information that the program needs in order to recreate that entire world again, for any of the user interfaces.
  • Internally, the state data is passed around as javascript objects, but to the user, state is represented by a multiline string. The format of the string has been dealt with in “Usage” above.
  • The state snapshot history is synchronised with the slider in the browser interface.
  • The method of updating the history is outlined in comments in the source, but will be briefly mentioned here.
    • History consists of a sequence of buffer snapshots and a sequence of actual, slidable snapshots.
    • First of all, an interval size (= 100 ticks) is fixed. For the first interval (ie. the first 100 ticks), the actual snapshot sequence (or “history proper”) gets filled. For every subsequent interval, only the buffer gets filled. And at each checkpoint, the buffer gets merged into the history proper, and the buffer index is reset to zero. Then this process repeats.
    • The method of merging the buffer into the history proper is a lossy and logarithmic one. The two sequences each get squashed into half their size, and the new history proper becomes the squashed old history proper concatenated with the squashed buffer.
  • Coloring is achieved by a single formula defined in bridge.hue(): ((neighbors * 60 / density) + offset) mod 360. “Offset” is a shift in hue to make the particles look nice on different background colors.
You can’t perform that action at this time.