@wonderyard/vivarium 0.1.1 → 0.1.3

package/README.md

@@ -1,28 +1,93 @@
-# vivarium
+# Vivarium
 
-## Work in progress
+⚠️ Work in progress ⚠️
+
+## Introduction
+
+Vivarium is a TypeScript library that aims to provide a simple yet expressive way of creating your own cellular automata and run simulations on the web.
+
+Vivarium exposes a minimal API that attempts to express complex rules and conditions in a way that resembles natural language. Concepts and technical terms from the cellular automata theory are almost transparent to the user. This way the cognitive effort of translating ideas into code is reduced. By lowering this barrier we enable fast prototyping during the creative coding process, especially for users who are approaching the cellular automata world for the first time.
+
+Read the **WIP** [docs] to get started, or continue reading for a quick overview and **WIP** [demo].
+
+## Overview
 
 ### Install
 
-```shell
+Install Vivarium as a dependency. No other dependecies required.
+
+```bash
+npm i @wonderyard/vivarium
+```
+
+```bash
 pnpm add @wonderyard/vivarium
 ```
 
+```bash
+yarn add @wonderyard/vivarium
+```
+
 ### Import
 
+Import it once and use it anywhere.
+
 ```TypeScript
-import { vivarium } from "@wonderyard/vivarium";
+import { vivarium, setup } from "@wonderyard/vivarium";
 ```
 
-### Use
+### Create
+
+To give you an idea of what the API can offer and how intuitive it can be to reason about rules and conditions, we recreated the most popular cellular automaton: [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life). Now featuring (with a little bit of imagination) orange cats 🐈
+
+> We suggest you to read about Game of Life and how it works before continuing reading. If you don't understand clearly what the following code is representing, it's okay! Visit the **WIP** [docs] for a gentler introduction to cellular automata and what vivarium is meant for.
 
 ```TypeScript
 const vi = vivarium();
 
-const space = vi.element("space", "black");
+const space = vi.element("space", "white");
 const cat = vi.element("cat", "orange");
 
+// A cat is born if there's a family of 3 in the area.
 space.to(cat).count(cat, 3);
-cat.to(cat).count(cat, [2, 3]);
+
+// The cat stays if the area is neither too empty nor too crowded...
+cat.to(cat).count(cat, 2, 3);
+
+// ...otherwise the cat will leave the area forever.
 cat.to(space);
+
+const life = vi.create();
 ```
+
+### Run
+
+```TypeScript
+// Create a new canvas (or you could use an existing one)
+const canvas = document.createElement(canvas);
+document.body.appendChild(canvas);
+
+// Set the canvas size. This will be the automaton size as well.
+const size = 512;
+canvas.width = size;
+canvas.height = size;
+
+// Pass the canvas and the automaton you created to the setup function:
+const { evolve } = setup({ canvas, automaton: life });
+
+// Create a simple loop that evolves the canvas:
+const loop = async () => {
+  await evolve();
+  requestAnimationFrame(loop);
+}
+requestAnimationFrame(loop);
+```
+
+**WIP** [See the live demo here]
+
+## Browser compatibility
+
+Vivarium runs its simulation entirely on the GPU thanks to the WebGPU API and its compute shaders. WebGPU is a relatively new technology. It is available since Chrome 113, Safari 26. See implementation status in other browsers [here](https://github.com/gpuweb/gpuweb/wiki/Implementation-Status). Vivarium has been tested on Chrome 139 for macOS and Safari 26.0 for macOS, showing better performances on Chrome overall.
+
+## Contributing
+Although I've been researching and experimenting with cellular automata for years, this is my first WebGPU-based project, so it might be rough around the edges. With WebGPU I've been able to achieve something it wouldn't be possible in a browser otherwise: to build something simple, customizable, and accessible for the end user, without compromising on performance. The intent is to offer this library as a learning tool and something other people can build on top of. If you share the vision and you would like to improve this software, PRs are welcome.

package/dist/blueprint/rule-blueprint.d.ts

@@ -8,7 +8,8 @@ export declare class RuleBlueprint extends BaseBlueprint {
     protected rule: Rule;
     constructor(context: BlueprintContext, automaton: Automaton, rule: Rule);
     private condition;
-    count(refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor, count?: number | number[]): RuleBlueprintWithAccept;
+    count(refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor, count: number[]): RuleBlueprintWithAccept;
+    count(refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor, ...count: number[]): RuleBlueprintWithAccept;
     is(neighbor: AnyNeighbor, refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor): RuleBlueprintWithAccept;
     chance(part: number, whole?: number): RuleBlueprintWithAccept;
 }

package/package.json

@@ -1,10 +1,18 @@
 {
   "name": "@wonderyard/vivarium",
   "description": "Modern, intuitive, WebGPU-powered toolkit for creating your own cellular automata.",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "repository": "https://github.com/WonderYard/vivarium",
   "license": "MIT",
   "author": "OrangeNote",
+  "keywords": [
+    "cellular-automata",
+    "compute",
+    "creative-coding",
+    "game-of-life",
+    "simulation",
+    "webgpu"
+  ],
   "type": "module",
   "files": [
     "dist"

package/README.md.local

@@ -1,93 +0,0 @@
-# vivarium
-
-A _vivarium_ is a set of elements that interact with each other in a grid, changing into other elements over time. With this library you can define your vivarium and see it evolve on your screen.
-
-You can start defining your vivarium like this:
-
-```TypeScript
-import { vivarium } from "@wonderyard/vivarium";
-
-const vi = vivarium();
-```
-
-## Elements
-
-An _element_ is the basic bit of your simulation. It can be represented with a little square on your screen.
-
-Here's how to define one.
-
-```TypeScript
-const cat = vi.element("cat", "orange");
-```
-
-We're not drawing it on the screen yet. For now we are just defining what a cat is, so that our system is aware of its existence in the vivarium.
-
-## Kinds
-
-The second base concept of vivarium is _kinds_. A kind is not an element, it doesn't have a color and so it cannot be directly represented on a screen. However it can be inherited by elements to share common characteristics. It is not necessary to use _kinds_. Consider it an advanced concept that allows you to write less code and achieve more complex. To start, I'll show you how to define one, which is similar to how we define elements.
-
-```TypeScript
-const animal = vi.kind("animal");
-```
-
-## Rules
-
-The heart of vivarium is made of _rules_. A rule is a way to tell elements how to behave in our vivarium. Every step of the simulation, an element can become another element or stay the same. Let's see a simple rule first:
-
-```TypeScript
-const space = vi.element("space", "white");
-const cat = vi.element("cat", "orange");
-
-space.to(cat);
-```
-
-The method `to` can be read as "becomes" or "evolves to". So with this last line, what we are saying is: when we will run the system, at every simulation step, every space element will become a cat element. It's like cats appearing out of nowhere, so on the screen we would see every white cell in the grid becoming orange as soon as we start the simulation. A room filled with cats!
-
-## Conditions
-
-However in a system like that, nothing interesting would happen after the first step. All free spaces are occupied by cats immediately and they will just sit there forever.
-
-Let's create a more interesting system, this time by adding a condition to the existing rule.
-
-```TypeScript
-space.to(cat).count(cat, 1);
-```
-
-By calling the method `count` we are stating that every time the simulation attempts to apply the rule `space.to(cat)` it must first count the number of whatever we pass as first parameter (`cat` in this case) in from the neighborhood of `space` and compare that with the second argument (`1` in this case). If the condition is satisfied, that is, the number of cats in the neighborhood of space is exactly 1, then the rule is applied, otherwise it is skipped for the current step.
-
-With this rule, we are filling the room bit by bit in an interesting pattern. It almost looks like a net made of cat tails! Eventually the simulation becomes stable and nothing else happens.
-
-## Game of Life
-
-Probably the most famous cellular automata, Game of Life rules are not that far from what we created just before. There's many ways to implement Game of Life rules. Here's one version:
-
-```TypeScript
-// A new cat is born near a family of 3
-space.to(cat).count(cat, 3);
-// Underpopulation: the cat leaves the space because it feels lonely there
-cat.to(space).count(cat, [0, 1]);
-// Overpopulation: too many cats!
-cat.to(space).count(cat, [4, 5, 6, 7, 8]);
-```
-
-Feel free to come up with your own implementation! Vivarium is designed to allow you to define the same thing in multiple ways, depending on the structure and conventions you want to use.
-
-Here's an equivalent list of rule declarations:
-
-```TypeScript
-// Same as before
-space.to(cat).count(cat, 3);
-// Cat stays there when the number of cats around it is just right
-cat.to(cat).count(cat, [2, 3]);
-// Cat vanishes :'(
-cat.to(space);
-```
-
-Here we compressed the two `cat.to(space)` rules into one inverse rule, and we let it evolve to space otherwise, unconditionally. Try to reason on why this set of rules is equivalent to the previous one and notice two important things:
-
-- Rules without conditions are still meaningful, so use them when they might simplify your overall rule syntax.
-- Order of rules matters!
-
-## Order of rules
-
-Did I mention it already? Order of rules matters! Yes, because the system has to evaluate rules one by one. Whichever rule satisfies its conditions first, will be the one evolving the cell. No more rules are evaluated for that cell until the next simulation step. In other words, rules are declared in order of priority, high to low. The first rule passing the test is the winner. Every other rule is ignored. So it's important that you design your vivarium with this concept in mind, or your rules won't work as expected.