Simulate natural systems with JavaScript.
npm install florajsIn Flora, the 'world' is your web browser. DOM elements inhabit the world and behave according to rules meant to simulate a natural environment. You can find demos at http://vinceallenvince.github.io/FloraJS.
The formulas driving a large part of Flora are adapted from Daniel Shiffman's 'The Nature of Code'. Inspiration also came from the writings of Valentino Braitenberg and Gary Flake.
To include FloraJS as a component in your project, use the node module.
``
npm install florajs --save
You can also use the standalone version and reference both the css and js files from your document.
`
...
#### Simple System
1. Pass a function to Flora.System.setup() that describes the items in your world.
2. The first item must be a World. (eg. this.add('World')).
3. Call Flora.System.loop() to start the animation.
`html`
You should see a block fall and bounce off the bottom of your browser window.
http://vinceallenvince.github.io/FloraJS/Flora.Agent.html
#### The System and its Worlds
Every Flora system starts with one System and one World. While a System may have many Worlds, by default, Flora's system uses the <body> as the only World.
In the example above, immediately after the system starts, it creates an Agent and appends it to the World (or <body>).
Worlds carry two properties that directly affect their elements.
* gravity {Vector} default: new Vector(0, 1)
* c (coefficient of friction) {number} 0.01
We can change these defaults by passing options when we add the world.
`html`
We've reversed the World's gravity and increased its friction. Now the block slowly drifts upwards.
http://vinceallenvince.github.io/FloraJS/Flora.WorldProperties.html
#### Agents
Agents are basic Flora elements that respond to forces like gravity, attraction, repulsion, etc. They can also chase after other Agents, organize with other Agents in a flocking behavior, and steer away from obstacles.
Agents are highly configurable. For a complete list of options see the docs at http://vinceallenvince.github.io/FloraJS/doc/Agent.html
For an example of an Agent's seek behavior, set 'followMouse' to 'true' when creating the Agent.
`html`
http://vinceallenvince.github.io/FloraJS/Flora.Agent.FollowMouse.html
#### Walkers
Walkers are a step down on the evolutionary chain from Agents. They have no seeking, steering or directional behavior and just randomly explore their World. Use Walkers to create wandering objects or targets for Agents to seek.
Walkers carry a property that directly affect how they 'walk'.
* perlin {boolean} default: true
By default, Walkers use an algorithm called Perlin Noise (http://en.wikipedia.org/wiki/Perlin_noise) to navigate their World. Below is an example of 60 Walkers wandering around.
`html`
http://vinceallenvince.github.io/FloraJS/Flora.Walker.Perlin.html
#### Targets
In the Agent example above, the Agent targeted the mouse. By saving a reference to a new Walker and passing at as a 'seekTarget' for a new Agent, we can make the Agent seek the Walker.
`html`
http://vinceallenvince.github.io/FloraJS/Flora.Agent.SeekWalker.html
#### Flocking
Agents can also organize in flocks. The following properties affect flocking behavior.
* flocking {boolean} default: false
desiredSeparation {number} default: width 2
* separateStrength {number} default: 0.3
* alignStrength {number} default: 0.2
* cohesionStrength {number} default: 0.1
In the example below, we create two groups of Agents and set their 'seekTarget' to Walkers. We also set 'flocking' to true to enable the flocking behavior.
`html`
http://vinceallenvince.github.io/FloraJS/Flora.Agent.Flocking.html
In the example below, Agents flock to the mouse.
`html`
http://vinceallenvince.github.io/FloraJS/Flora.Agent.FlockToMouse.html
#### Proximity
FloraJS has some built in Proximity objects that exert a force on Agents that come in direct contact or land within the object's range of influence.
* Dragger
* Attractor
* Repeller
In the example below, we create a Dragger object and an Agent that follows the mouse. You can click and drag to place the Dragger anywhere in the World. Use your mouse to make the Agent pass through the Dragger.
`html`
You can replace 'Dragger' with 'Attractor' or 'Repeller' to view how the Proximity objects affect an Agent.
http://vinceallenvince.github.io/FloraJS/Flora.Dragger.html
#### Sensors and Stimuli
Agents can carry an unlimited amount of Sensors that react to Flora's Stimulus types. The following Stimulus types are available:
* Cold
* Heat
* Food
* Light
* Oxygen
Sensors are tuned specifically to a Stimulant and can be configured to activate a specific behavior. The following behaviors are available:
* ACCELERATE
* DECELERATE
* AGGRESSIVE
* COWARD
* LIKES
* LOVES
* EXPLORER
* CURIOUS
* DESTROY
* CONSUME
In the example below, an Agent carries a Sensor that senses Heat. When activated, it triggers the 'COWARD' behavior.
`html`
Notice, we've updated the World and removed any gravitational forces. We've also updated the 'motorSpeed' property to give the Agent a constant velocity. You should see the Agent navigate the World and avoid the Heat objects.
http://vinceallenvince.github.io/FloraJS/Flora.Sensor.Coward.html
#### A Small World
Putting it all together, we can observe Agents navigate a World with multiple Stimuli and Proximity objects.
`html`
http://vinceallenvince.github.io/FloraJS/Flora.Sim.MultipleStimuli.html
#### Camera
Notice in the above example, we view the world from the first-person point of view of an Agent. Setting 'controlCamera' to 'true' on an agent will force Flora's camera to track that agent. Of course, there can only be one agent controlling the world's camera.
...
this.add('Agent', {
controlCamera: true,
...
#### Your own worlds
Flora allows you to define worlds using any DOM element. This is useful if you want your world to live alongside other DOM elements or simply do not want the entire body defined as a world.
To define a world, just create the DOM element you want to represent the world and reference it when calling new Burner.World().
`html`
http://vinceallenvince.github.io/FloraJS/Flora.WorldDOM.html
#### Multiple worlds
Flora also supports multiple worlds... here's an example.
`html`
http://vinceallenvince.github.io/FloraJS/Flora.WorldsMultiple.html
#### Sound
Flora uses SoundBed to generate ambient noise for simluations. To use it, just create a new Flora.SoundBed.Player and pass in your opitons via player.init().
`
Flora.System.setup(function() {
...
var player = new Flora.SoundBed.Player();
player.init({
volumeMin: 0.25,
volumeMax: 0.5
});
...
});
#### Advanced exmaples
The following examples implement advanced functions of FloraJS.
Building this project
------
This project uses Grunt. To build the project first install the node modules.
`
npm install
Next, run grunt.
`
grunt
To run the tests, run 'npm test'.
`
npm test
To check test coverage run 'grunt coverage'.
`
grunt coverage
A pre-commit hook is defined in /pre-commit that runs jshint. To use the hook, run the following:
`
ln -s ../../pre-commit .git/hooks/pre-commit
A post-commit hook is defined in /post-commit that runs the Plato complexity analysis tools. To use the hook, run the following:
`
ln -s ../../post-commit .git/hooks/post-commit