@wonderyard/vivarium 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OrangeNote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# vivarium
+
+## Work in progress
+
+### Install
+
+```shell
+pnpm add @wonderyard/vivarium
+```
+
+### Import
+
+```TypeScript
+import { vivarium } from "@wonderyard/vivarium";
+```
+
+### Use
+
+```TypeScript
+const vi = vivarium();
+
+const space = vi.element("space", "black");
+const cat = vi.element("cat", "orange");
+
+space.to(cat).count(cat, 3);
+cat.to(cat).count(cat, [2, 3]);
+cat.to(space);
+```

package/README.md.local

@@ -0,0 +1,93 @@
+# 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.

package/dist/automaton/types.d.ts

@@ -0,0 +1,56 @@
+import { Accept } from '../common/constants';
+export type Neighborhood = "square" | "cross";
+export type RefType = "element" | "kind";
+export type Kind = {
+    type: "kind";
+    id: string;
+    name: string;
+};
+export type Color = string;
+export type Automaton = {
+    neighborhood: Neighborhood;
+    elements: Element[];
+    kinds: Kind[];
+    rules: Rule[];
+};
+export type Element = {
+    type: "element";
+    id: string;
+    name: string;
+    color: string;
+    extensions: string[];
+};
+export type Rule = {
+    fromId: string;
+    fromType: RefType;
+    to: string | Point | undefined;
+    when: Condition[];
+    accept: Accept;
+};
+export type Condition = Count | Is | Chance;
+export type Count = {
+    type: "count";
+    id: string;
+    check: string | Point | undefined;
+    count: number[];
+};
+export type Is = {
+    type: "is";
+    id: string;
+    compare: Point | undefined;
+    with: string | Point | undefined;
+};
+export type Ratio = {
+    part: number;
+    whole: number;
+};
+export type Chance = {
+    type: "chance";
+    id: string;
+    ratio: Ratio;
+};
+export type Strategy = "all" | "any" | "one" | "none";
+export type Point = {
+    x: number;
+    y: number;
+};

package/dist/automaton/types.js

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,10 @@
+import { Automaton, Color } from '../automaton/types';
+import { BlueprintContext } from './types';
+export declare abstract class BaseBlueprint {
+    protected abstract automaton: Automaton;
+    protected abstract context: BlueprintContext;
+    protected assertNotCreated(): void;
+    protected assertUniqueName(name: string): void;
+    protected assertUniqueColor(color: Color): void;
+    protected assertNotEmpty(): void;
+}

package/dist/blueprint/base-blueprint.js

@@ -0,0 +1,29 @@
+class o {
+  assertNotCreated() {
+    if (this.context.created)
+      throw new Error("Blueprint methods can no longer be called after create");
+  }
+  assertUniqueName(e) {
+    if (e.trim().length === 0)
+      throw new Error("Name cannot be empty");
+    if (this.automaton.elements.some((t) => t.name === e))
+      throw new Error(`Element with name "${e}" already exists`);
+    if (this.automaton.kinds.some((t) => t.name === e))
+      throw new Error(`Kind with name "${e}" already exists`);
+  }
+  assertUniqueColor(e) {
+    if (e.trim().length === 0)
+      throw new Error("Color cannot be empty");
+    if (this.automaton.elements.some((t) => t.color === e))
+      throw new Error(`Element with color "${e}" already exists`);
+  }
+  assertNotEmpty() {
+    if (!this.automaton.elements.length)
+      throw new Error(
+        "No elements found in automaton, at least one element is required"
+      );
+  }
+}
+export {
+  o as BaseBlueprint
+};

package/dist/blueprint/helpers.d.ts

@@ -0,0 +1,9 @@
+import { Neighborhood } from '../automaton/types';
+export declare class Helpers {
+    private neighborhoodName?;
+    constructor(neighborhoodName?: Neighborhood | undefined);
+    not(value: number | number[]): number[];
+    between(min: number, max: number): number[];
+    even(): number[];
+    odd(): number[];
+}

package/dist/blueprint/helpers.js

@@ -0,0 +1,32 @@
+class s {
+  constructor(r) {
+    this.neighborhoodName = r;
+  }
+  not(r) {
+    const e = this.neighborhoodName === "cross" ? /* @__PURE__ */ new Set([0, 1, 2, 3, 4]) : /* @__PURE__ */ new Set([0, 1, 2, 3, 4, 5, 6, 7, 8]);
+    return typeof r == "number" ? e.delete(r) : Array.isArray(r) && r.forEach((o) => {
+      e.delete(o);
+    }), Array.from(e);
+  }
+  between(r, e) {
+    if (r < 0)
+      throw new Error("min cannot be less than 0");
+    if (e > 8)
+      throw new Error("max cannot be more than 8");
+    if (e <= r)
+      throw new Error("max cannot be less or equal than min");
+    const o = [];
+    for (let n = r; n <= e; n++)
+      o.push(n);
+    return o;
+  }
+  even() {
+    return this.neighborhoodName === "cross" ? [0, 2, 4] : [0, 2, 4, 6, 8];
+  }
+  odd() {
+    return this.neighborhoodName === "cross" ? [1, 3] : [1, 3, 5, 7];
+  }
+}
+export {
+  s as Helpers
+};

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

@@ -0,0 +1,24 @@
+import { Automaton, Element, Kind, RefType } from '../automaton/types';
+import { BaseBlueprint } from './base-blueprint';
+import { RuleBlueprint } from './rule-blueprint';
+import { AnyNeighbor, BlueprintContext } from './types';
+export declare abstract class RefBlueprint extends BaseBlueprint {
+    protected automaton: Automaton;
+    id: string;
+    name: string;
+    type: RefType;
+    constructor(automaton: Automaton, ref: Element | Kind);
+    to(elementBlueprintOrNeighbor: ElementBlueprint | AnyNeighbor): RuleBlueprint;
+}
+export declare class ElementBlueprint extends RefBlueprint {
+    protected context: BlueprintContext;
+    type: "element";
+    id: string;
+    constructor(context: BlueprintContext, automaton: Automaton, element: Element);
+}
+export declare class KindBlueprint extends RefBlueprint {
+    protected context: BlueprintContext;
+    type: "kind";
+    id: string;
+    constructor(context: BlueprintContext, automaton: Automaton, kind: Kind);
+}

package/dist/blueprint/ref-blueprint.js

@@ -0,0 +1,42 @@
+import { BaseBlueprint as r } from "./base-blueprint.js";
+import { R as n } from "../rule-blueprint-Df5BKApy.js";
+import { toRefIdOrPoint as p } from "./utils.js";
+import { A as u } from "../constants-Ry69vZz5.js";
+class o extends r {
+  constructor(e, t) {
+    super(), this.automaton = e, this.id = t.id, this.name = t.name, this.type = t.type;
+  }
+  id;
+  name;
+  type;
+  to(e) {
+    this.assertNotCreated();
+    const t = {
+      fromId: this.id,
+      fromType: this.type,
+      to: p(e),
+      when: [],
+      accept: u.ALL
+    };
+    return this.automaton.rules.push(t), new n(this.context, this.automaton, t);
+  }
+}
+class h extends o {
+  constructor(e, t, s) {
+    super(t, s), this.context = e, this.id = s.id;
+  }
+  type = "element";
+  id;
+}
+class l extends o {
+  constructor(e, t, s) {
+    super(t, s), this.context = e, this.id = s.id;
+  }
+  type = "kind";
+  id;
+}
+export {
+  h as ElementBlueprint,
+  l as KindBlueprint,
+  o as RefBlueprint
+};

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

@@ -0,0 +1,18 @@
+import { Automaton, Rule, Strategy } from '../automaton/types';
+import { BaseBlueprint } from './base-blueprint';
+import { RefBlueprint } from './ref-blueprint';
+import { AnyNeighbor, BlueprintContext } from './types';
+export declare class RuleBlueprint extends BaseBlueprint {
+    protected context: BlueprintContext;
+    protected automaton: Automaton;
+    protected rule: Rule;
+    constructor(context: BlueprintContext, automaton: Automaton, rule: Rule);
+    private condition;
+    count(refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor, count?: number | number[]): RuleBlueprintWithAccept;
+    is(neighbor: AnyNeighbor, refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor): RuleBlueprintWithAccept;
+    chance(part: number, whole?: number): RuleBlueprintWithAccept;
+}
+declare class RuleBlueprintWithAccept extends RuleBlueprint {
+    accept(strategy: Strategy): void;
+}
+export {};

package/dist/blueprint/rule-blueprint.js

@@ -0,0 +1,7 @@
+import { R as m } from "../rule-blueprint-Df5BKApy.js";
+import "./base-blueprint.js";
+import "./utils.js";
+import "../constants-Ry69vZz5.js";
+export {
+  m as RuleBlueprint
+};

package/dist/blueprint/types.d.ts

@@ -0,0 +1,8 @@
+import { Cross, Square } from '../common/constants';
+export type AnyNeighbor = Cross | Square;
+export type Neighbor<N> = N extends "cross" ? Cross : Square;
+export type ConditionStrategy = "all" | "any" | "one" | "none";
+export type ConditionExpression = (neighborhood: Uint8Array, x: number, y: number) => boolean;
+export type BlueprintContext = {
+    created: boolean;
+};

package/dist/blueprint/types.js

@@ -0,0 +1 @@
+

package/dist/blueprint/utils.d.ts

@@ -0,0 +1,4 @@
+import { Point } from '../automaton/types';
+import { RefBlueprint } from './ref-blueprint';
+import { AnyNeighbor } from './types';
+export declare const toRefIdOrPoint: (refBlueprintOrNeighbor: RefBlueprint | AnyNeighbor) => string | Point;

package/dist/blueprint/utils.js

@@ -0,0 +1,5 @@
+import { n as t } from "../constants-Ry69vZz5.js";
+const s = (o) => typeof o == "string" ? t[o] : o.id;
+export {
+  s as toRefIdOrPoint
+};

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

@@ -0,0 +1,18 @@
+import { Automaton, Color, Neighborhood } from '../automaton/types';
+import { BaseBlueprint } from './base-blueprint';
+import { Helpers } from './helpers';
+import { ElementBlueprint, KindBlueprint } from './ref-blueprint';
+import { Cross, Square } from '../common/constants';
+export declare class VivariumBlueprint<N extends Neighborhood = "square"> extends BaseBlueprint {
+    private neighborhoodName?;
+    protected automaton: Automaton;
+    protected context: {
+        created: boolean;
+    };
+    neighbor: N extends "cross" ? typeof Cross : typeof Square;
+    helpers: Helpers;
+    constructor(neighborhoodName?: N | undefined);
+    element(name: string, color: Color, extensions?: KindBlueprint[]): ElementBlueprint;
+    kind(name: string): KindBlueprint;
+    create(): Automaton;
+}

package/dist/blueprint/vivarium-blueprint.js

@@ -0,0 +1,47 @@
+import { n as o } from "../rule-blueprint-Df5BKApy.js";
+import { BaseBlueprint as n } from "./base-blueprint.js";
+import { Helpers as a } from "./helpers.js";
+import { ElementBlueprint as h, KindBlueprint as m } from "./ref-blueprint.js";
+import { C as u, S as p } from "../constants-Ry69vZz5.js";
+class C extends n {
+  constructor(t) {
+    super(), this.neighborhoodName = t, this.helpers = new a(this.neighborhoodName), this.neighbor = this.neighborhoodName === "cross" ? u : p, this.automaton = {
+      neighborhood: t ?? "square",
+      elements: [],
+      kinds: [],
+      rules: []
+    };
+  }
+  automaton;
+  context = { created: !1 };
+  neighbor;
+  helpers;
+  element(t, e, r = []) {
+    this.assertNotCreated(), this.assertUniqueName(t), this.assertUniqueColor(e);
+    const s = {
+      type: "element",
+      id: o(),
+      name: t,
+      color: e,
+      extensions: r.map((i) => i.id)
+    };
+    return this.automaton.elements.push(s), new h(this.context, this.automaton, s);
+  }
+  kind(t) {
+    this.assertNotCreated(), this.assertUniqueName(t);
+    const e = {
+      type: "kind",
+      id: o(),
+      name: t
+    };
+    return this.automaton.kinds.push(e), new m(this.context, this.automaton, e);
+  }
+  create() {
+    this.assertNotCreated(), this.assertNotEmpty();
+    const t = this.automaton;
+    return this.context.created = !0, t;
+  }
+}
+export {
+  C as VivariumBlueprint
+};

package/dist/common/constants.d.ts

@@ -0,0 +1,64 @@
+import { Point, Strategy } from '../automaton/types';
+import * as d from "typegpu/data";
+export declare enum Square {
+    TOP_LEFT = "TOP_LEFT",
+    TOP = "TOP",
+    TOP_RIGHT = "TOP_RIGHT",
+    LEFT = "LEFT",
+    SELF = "SELF",
+    RIGHT = "RIGHT",
+    BOTTOM_LEFT = "BOTTOM_LEFT",
+    BOTTOM = "BOTTOM",
+    BOTTOM_RIGHT = "BOTTOM_RIGHT"
+}
+export declare enum Cross {
+    TOP = "TOP",
+    LEFT = "LEFT",
+    SELF = "SELF",
+    RIGHT = "RIGHT",
+    BOTTOM = "BOTTOM"
+}
+export declare const neighborhoodPoints: Record<Square, Point>;
+export declare enum To {
+    ELEMENT_ID = 0,
+    POINT = 1
+}
+export declare enum Opcode {
+    NOOP = 0,
+    COUNT_ELEMENT = 1,
+    COUNT_POINT = 2,
+    COUNT_KIND = 3,
+    IS_ELEMENT = 4,
+    IS_POINT = 5,
+    IS_KIND = 6,
+    CHANCE = 7
+}
+export declare enum Accept {
+    ALL = 0,
+    ANY = 1,
+    ONE = 2,
+    NONE = 3
+}
+export declare const acceptMap: Record<Strategy, Accept>;
+export declare const GpuElement: d.WgslStruct<{
+    color: d.U32;
+    ruleStart: d.U32;
+    ruleEnd: d.U32;
+}>;
+export declare const GpuRule: d.WgslStruct<{
+    toType: d.U32;
+    toId: d.U32;
+    toNeighbor: d.Vec2u;
+    accept: d.U32;
+    conditionsStart: d.U32;
+    conditionsEnd: d.U32;
+}>;
+export declare const GpuCondition: d.WgslStruct<{
+    opcode: d.U32;
+    checkId: d.U32;
+    countOrWithId: d.U32;
+    checkPointOrComparePoint: d.Vec2u;
+    withPoint: d.Vec2u;
+    chance: d.F32;
+}>;
+export declare const WORKGROUP_SIZE: [number, number];

package/dist/common/constants.js

@@ -0,0 +1,14 @@
+import { A as o, C as e, a5 as p, a1 as c, a2 as n, a6 as t, S as r, a4 as u, cf as i, a7 as G, n as d } from "../constants-Ry69vZz5.js";
+export {
+  o as Accept,
+  e as Cross,
+  p as GpuCondition,
+  c as GpuElement,
+  n as GpuRule,
+  t as Opcode,
+  r as Square,
+  u as To,
+  i as WORKGROUP_SIZE,
+  G as acceptMap,
+  d as neighborhoodPoints
+};

package/dist/common/utils.d.ts

@@ -0,0 +1 @@
+export declare const colorToABGR: (color: string) => number;

package/dist/common/utils.js

@@ -0,0 +1,53 @@
+const u = (e) => {
+  switch (e.toLowerCase()) {
+    case "black":
+      return "#000000";
+    case "silver":
+      return "#c0c0c0";
+    case "gray":
+      return "#808080";
+    case "white":
+      return "#ffffff";
+    case "maroon":
+      return "#800000";
+    case "red":
+      return "#ff0000";
+    case "purple":
+      return "#800080";
+    case "fuchsia":
+      return "#ff00ff";
+    case "green":
+      return "#008000";
+    case "lime":
+      return "#00ff00";
+    case "olive":
+      return "#808000";
+    case "yellow":
+      return "#ffff00";
+    case "navy":
+      return "#000080";
+    case "blue":
+      return "#0000ff";
+    case "teal":
+      return "#008080";
+    case "aqua":
+      return "#00ffff";
+    default:
+      return e;
+  }
+}, l = (e) => {
+  e = u(e);
+  const n = /^#?([a-f\d])([a-f\d])([a-f\d])$/i;
+  e = e.replace(
+    n,
+    (d, a, t, f) => a + a + t + t + f + f
+  );
+  const r = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(e);
+  if (!r)
+    throw new Error("Bad color");
+  const s = parseInt(r[1], 16), c = parseInt(r[2], 16);
+  return 4278190080 | parseInt(r[3], 16) << 16 | c << 8 | s;
+};
+export {
+  l as colorToABGR
+};